Series, seasons and teams¶

class Series(series_id)[source]¶

A series or league, with its seasons, teams and matches.

Example values are for Series(1449924), the Indian Premier League.

Parameters:: series_id (int)

series_id: int¶: ESPNcricinfo series (league) id.

json: dict[str, Any]¶: The core API series record.

name: str¶: 'Indian Premier League'.

short_name: str¶: Short name, e.g. 'IPL'.

abbreviation: str¶: ESPN abbreviation.

slug: str¶: URL slug.

is_tournament: bool¶: True for tournaments, False for bilateral series.

url: str | None¶: ESPNcricinfo web page for the series.

seasons: list[str]¶: Core API URLs of the series’ seasons.

years: list[str]¶: Season years as strings, e.g. ['2008', ..., '2025'].

property events: list[dict[str, Any]]¶

Core API event records for the series’ first page of events.

One request per event, made on first access.

property season_objects: list[Season]¶: Every season of the series, loaded on first access.

season(key)[source]¶

Return one season, by year or by ESPNcricinfo’s two-year label.

Multi-year seasons live under their own series id, which this exposes as season.series_id: for the Big Bash League, Series(8044).season("2024/25").series_id is 1443056.

Parameters:: key (int | str) – 2024, "2024", "2024/25", "2024-25" or "2024/2025". A bare year matches the season starting then.
Returns:: The matching season.
Raises:: NoSeasonError – If the series has no such season.
Return type:: Season

property current_season: Season | None¶: The season ESPN marks as current, or None.

property matches: list[MatchRef]¶: MatchRefs for every match across all seasons, without duplicates.

property current_matches: list[MatchRef]¶: Matches whose ESPN status is in progress (two requests per match).

class Season(season_id, series_id)[source]¶

One season of a series, with its teams and matches.

Parameters:

season_id (int | str)
series_id (int)

id: int¶: Season id, usually the year.

series_id: int¶: ESPNcricinfo series (league) id.

url: str¶: Core API URL of the season.

json: dict[str, Any]¶: The core API season record.

year: int¶

2024 for 2024/25.

Type:: ESPN’s season year, the year the season starts

name: str | None¶: 'Indian Premier League 2025'.

short_name: str | None¶: Short name, or None.

start_date: datetime | None¶: Start of the season (UTC), or None.

end_date: datetime | None¶: End of the season (UTC), or None.

label: str¶

'2024/25' for a season that crosses New Year, otherwise the year, e.g. '2025'.

Type:: ESPNcricinfo’s label

classmethod from_reference(url)[source]¶

Build a Season from a core API season URL.

Parameters:: url (str)
Return type:: Season

property teams: list[Team]¶: Teams in this season, loaded on first access (one request each).

property match_refs: list[MatchRef]¶: MatchRefs for this season’s matches, loaded on first access.

property series: Series¶: The parent Series, loaded on first access.

class Team(team_id, series_id)[source]¶

A team as it appears in one series.

Parameters:

team_id (int | str)
series_id (int)

id: int¶: ESPNcricinfo team id.

series_id: int¶: ESPNcricinfo series (league) id.

url: str¶: Core API URL of the team within the series.

json: dict[str, Any]¶: The core API team record.

name: str | None¶: 'Chennai Super Kings'.

short_name: str | None¶: Abbreviation, e.g. 'CSK'.

location: str | None¶: Home location, or None.

nickname: str | None¶: Nickname, or None.

slug: str | None¶: URL slug.

color: str | None¶: Team color as hex, or None.

logo: str | None¶: Logo URL, or None.

is_national: bool | None¶: True for national sides.

is_active: bool | None¶: True if ESPN marks the team active.

match_date: datetime | None¶: Start of the team’s linked match (UTC), or None.

match: MatchRef | None¶: The team’s linked match in this series, or None.

classmethod from_reference(url)[source]¶

Build a Team from a core API team URL.

Parameters:: url (str)
Return type:: Team

property players: list[Player]¶: The squad as Players, loaded on first access (one request each).