API

Data models for the ILC project

class ilc_models.BaseEvent(*, team: str, time: EventTime)

Abstract base class for events.

Parameters:

• team (str) – Team this event relates to

• time (EventTime) – Event time

abstractmethod players() → list[BasePlayer]

Get the players involved in this event

time_str() → str

The event time in str format

class ilc_models.BasePlayer(*, player_id: int, name: str)

Basic level of player details.

Parameters:

• player_id (int) – ID of this player in the API

• name (str) – Player’s full (display) name

class ilc_models.Card(*, team: str, time: EventTime, event_type: Literal['card'] = 'card', color: Literal['Y', 'R'], player: BasePlayer)

Represents a red or yellow card.

Parameters:

• event_type (str) – The literal string ‘card’

• color (str) – One of ‘R’ (red card), ‘Y’ (yellow card)

• player (BasePlayer) – Player receiving the card

players() → list[BasePlayer]

Get the players involved in this event

class ilc_models.Deduction(*, team: str, points: Annotated[int, Gt(gt=0)], date: Annotated[str, WrapValidator(func=validate_deduction_date, json_schema_input_type=PydanticUndefined)] = '')

A points deduction.

Parameters:

• team (str) – Team to which this deduction applies

• points (int) – Number of points deducted

• date (str) – Date on which the deduction was implemented - if the empty string the deduction should be built in from the start of the season (default=’’)

class ilc_models.EventInfo(*, date: date, teams: Teams, score: Score, event: Event)

Event data with match info added.

Parameters:

• date (datetime.date) – Date of match

• teams (Teams) – Teams involved in the match

• score (Score) – Match score

• event (Event) – Event info

class ilc_models.EventTime(*, minutes: Annotated[int, Gt(gt=0), Le(le=120)], plus: Annotated[int, Ge(ge=0)] = 0)

The time an event occurred during a match.

Parameters:

• minutes (int) – Minutes elapsed (1-120)

• plus (int) – Additional time minutes i.e. after 45, 90 etc. (default=0)

check_valid_time() → Self

Checks the minutes field is valid if plus is non-zero

class ilc_models.Goal(*, team: str, time: EventTime, event_type: Literal['goal'] = 'goal', goal_type: Literal['N', 'O', 'P'] = 'N', scorer: BasePlayer)

Represents a goal.

Parameters:

• event_type (str) – The literal string ‘goal’

• goal_type (str) – One of ‘N’ (normal goal), ‘O’ (own goal), ‘P’ (penalty) (default=’N’)

• scorer (BasePlayer) – Goal scorer

players() → list[BasePlayer]

Get the players involved in this event

class ilc_models.League(*, league_id: Annotated[int, Gt(gt=0)], name: str, year: Annotated[int, Gt(gt=0)], start: Annotated[str, _PydanticGeneralMetadata(pattern='^[12][09]\\d{2}-[01]\\d-[0-3]\\d$')], end: Annotated[str, _PydanticGeneralMetadata(pattern='^[12][09]\\d{2}-[01]\\d-[0-3]\\d$')], current: bool, coverage: dict[str, bool], teams: list[str] = [], rounds: dict[str, list[Match]] = {}, excluded: list[str] = [], deductions: list[Deduction] = [], split: Annotated[int, Ge(ge=0)] = 0, players: dict[str, Player] = {})

Represents a League.

Parameters:

• league_id (int) – API ID of this league

• name (str) – Name of this league e.g. Premiership

• year (int) – Year this season starts

• start (str) – League start date as an ISO format string

• end (str) – League end date as an ISO format string

• current (bool) – Whether this league is still being played

• coverage (dict[str, bool]) – Coverage available from the API

• teams (list[str]) – The name of each team in this league (default=[])

• rounds (dict[str, list[Match]]) – This league’s rounds, with matches for each round (default={})

• excluded (list[str]) – Rounds to exclude from import (default=[])

• split (int) – Split point of this league (default=0)

• players (dict[str, Player]) – Players who feature in this league

events(player: BasePlayer) → list[EventInfo]

Get all events in this league in which a player is involved.

Also includes a LineupStatus event for any matches which include the player in their lineup.

Parameters:

player (BasePlayer) – Find events featuring this player

Returns:

The events in this league involving the player

Return type:

list[EventInfo]

head_to_head(teams: tuple[str, str]) → list[Match]

Get all matches played between two teams.

Parameters:

teams (tuple[str, str]) – Teams to query

Returns:

All matches between these two teams

Return type:

list[Match]

match_players(team: str | None = None, teams: list[str] | None = None, h2h: tuple[str, str] | None = None) → list[BasePlayer]

Get all players involved in at least one match in this league.

If team is given return only players who have featured for this team. If teams is given return only players who have featured for one of these teams. If h2h is given return only players who featured in a match between these two teams.

Parameters:

• team (str) – Get players who played for this team (default=None)

• teams (list[str]) – Get players who played for any of these teams (default=None)

• h2h (tuple[str, str]) – Get players who played in a match between these two teams (default=None)

Returns:

All players involved in a match

Return type:

list[BasePlayer]

matches(team: str | None = None, teams: list[str] | None = None, h2h: tuple[str, str] | None = None) → list[Match]

Matches in this league.

If team is given, return only matches involving this team. If teams is given, return only matches involving one of these teams. If h2h is given, return only matches between these two teams.

Parameters:

• team (str) – Get matches for this team (default=None)

• teams (list[str]) – Get matches involving any of these teams (default=None)

• h2h (tuple[str, str]) – Get matches between these two teams (eefault=None)

Returns:

Matches sorted by date and then home team

Return type:

list[Match]

player_teams(player: BasePlayer) → list[str]

Get all the teams a player features in during this season.

Parameters:

player (BasePlayer) – Find teams this player plays for

Returns:

The teams the player plays for in this league

Return type:

list[str]

table(played: int = 0, split_point: bool = False, date: date | None = None) → list[RowTuple]

Get the league table.

Returns the league table as a list of RowTuple items, ordered by league position.

If played is non-zero the table will be returned at the first point at which all teams have played at least played matches.

If split_point is True the table will be returned at the league’s split point.

If date is not None the table will be returned at the given date, i.e. taking account only of matches where the date is earlier than or equal to date.

Parameters:

• played (int) – If non-zero, get table after this number of games (default=0)

• split_point (bool) – If True get the table at the split point (default=False)

• date (datetime.date) – If given, get the league table on this date (default=None)

Returns:

The league table as a list of tuples

Return type:

list[RowTuple]

property title: str

Title of this league e.g. Premiership 2023/24

Returns:

Title of the league

Return type:

str

update_player(old: BasePlayer, new: BasePlayer, team: str | None = None)

Replace all occurrences of old with new.

Searches all lineups and events in this league and replaces all occurrences of old with new.

If team is given, replace only occurrences where the player features for team.

Parameters:

• old (BasePlayer) – Player to be replaced

• new (BasePlayer) – New player details

• team (str) – If given, replace only where the player features for this team (default=None)

class ilc_models.Lineup(*, starting: Annotated[list[tuple[int, BasePlayer]], MaxLen(max_length=11)] = [], subs: list[tuple[int, BasePlayer]] = [])

Lineup for one team.

Each lineup entry is an (int, BasePlayer) tuple, with the int being the player’s shirt number if supplied (0 if not).

Parameters:

• starting (list[tuple[int, BasePlayer]]) – Starting XI (default=[])

• subs (list[tuple[int, BasePlayer]]) – Substitutes (default=[])

players() → list[BasePlayer]

Returns all players in this lineup

sort()

Sorts the lineup.

Each part of the lineup is sorted by shirt number, except for the first item in the starting lineup which is assumed to be the goalkeeper and is left as the first item.

class ilc_models.LineupStatus(*, team: str, time: EventTime, event_type: Literal['status'] = 'status', status: Literal['starting', 'sub'], player: BasePlayer)

Whether a player is in the starting lineup or on the bench.

Parameters:

• event_type (str) – The literal string ‘status’

• status (str) – One of ‘starting’ or ‘sub’

• player (BasePlayer) – Player involved

players() → list[BasePlayer]

Get the players involved in this event

class ilc_models.Lineups(*, home: Lineup = Lineup(starting=[], subs=[]), away: Lineup = Lineup(starting=[], subs=[]))

Match lineups for home and away teams.

Parameters:

• home (Lineup) – Home lineup (default=Lineup())

• away (Lineup) – Away lineup (default=Lineup())

players() → list[BasePlayer]

Returns all players in this lineup

sort()

Sort the lineups.

Each part of the lineup is sorted by shirt number, except for the first item in the starting lineup which is assumed to be the goalkeeper and is left as the first item.

class ilc_models.Match(*, match_id: Annotated[int, Gt(gt=0)], kickoff: Annotated[str, _PydanticGeneralMetadata(pattern='^[12][09]\\d{2}-[01]\\d-[0-3]\\dT[0-2]\\d:[0-5]\\d:[0-5]\\d[+-][01]\\d:[0-5]\\d$')], round: str, teams: Teams, status: str, score: Score = Score(home=0, away=0), goals: list[Goal] = [], cards: list[Card] = [], substitutions: list[Substitution] = [], lineups: Lineups = Lineups(home=Lineup(starting=[], subs=[]), away=Lineup(starting=[], subs=[])))

Represents a match.

Parameters:

• match_id (int) – API ID of this match

• kickoff (str) – Date of match in ISO string format

• round (str) – Round this match is part of

• teams (Teams) – Teams involved in this match

• status (str) – Match status

• score (Score) – Score in this match (default=0-0)

• goals (list[Goal]) – Detail of goals scored in the match

• cards (list[Card]) – Detail of cards shown in the match

• substitutions (list[Substitution]) – Detail of substitutions made in the match

• lineups (Lineups) – Match lineups

delete_event(event: Event) → bool

Delete an event from this match.

Parameters:

event (Event) – Event to delete

Returns:

True if the event was successfully deleted

Raises:

ValueError if the event is not found in the match

events() → list[Event]

Returns all events in this match in chronological order.

Returns:

The combined list of goals, cards and subs in the match

Return type:

list[Event]

h2h(team1: str, team2: str) → bool

Returns True if the match is a head to head between these two teams.

Parameters:

• team1 (str) – First team

• team2 (str) – Second team

Returns:

True if the match is between the two teams, False otherwise

Return type:

bool

involves(team: str) → bool

Returns True if team is involved in this match.

Parameters:

team (str) – Team to query

Returns:

True if team is involved in this match, i.e. either as the home team or the away team

Return type:

bool

involves_any(teams: list[str]) → bool

Returns True if any of teams is involved in this match.

Parameters:

teams – Teams to query

Returns:

True if any of teams are involved in this match, i.e. either as the home team or the away team

Return type:

bool

players(team: str | None = None, teams: list[str] | None = None) → list[BasePlayer]

Get all players involved in this match.

If team is provided return only players from the team specified. If teams is provided return only players from one of the teams specified.

Parameters:

• team (list[str]) – Return only players from this team (default=None)

• teams – Return only players from these teams (default=None)

Returns:

Players involved in the match

Return type:

list[BasePlayer]

replace_event(old: Event, new: Event | None) → bool

Replace old with new. If new is None the event will be deleted.

Parameters:

• old (Event) – Event to replace

• new (Event | None) – New event (None to delete the event)

Returns:

True if the event was successfully replaced or deleted

Raises:

ValueError if the event is not found in the match

Raises:

TypeError if old and new are not the same event type

class ilc_models.Player(*, player_id: int, name: str, first_name: str, last_name: str, dob: Annotated[str, WrapValidator(func=validate_dob, json_schema_input_type=PydanticUndefined)], nationality: str)

Full player details.

Parameters:

• first_name (str) – Player’s first name

• last_name (str) – Player’s last name

• dob (str) – Player’s date of birth in ISO (yyyy-mm-dd) format

• nationality (str) – Player’s nationality

property base_player: BasePlayer

Return a BasePlayer object corresponding to this Player.

Returns:

The BasePlayer corresponding to this Player

Return type:

BasePlayer

class ilc_models.RowTuple(team: str, played: int, won: int, drawn: int, lost: int, goals_for: int, goals_against: int, gd: int, points: int, form: str)

Type for a single row of a league table.

Elements are: (team, played, won, drawn, lost, goals_for, goals_against, gd, points, form)

drawn: int

Alias for field number 3

form: str

Alias for field number 9

gd: int

Alias for field number 7

goals_against: int

Alias for field number 6

goals_for: int

Alias for field number 5

lost: int

Alias for field number 4

played: int

Alias for field number 1

points: int

Alias for field number 8

team: str

Alias for field number 0

won: int

Alias for field number 2

class ilc_models.Score(*, home: Annotated[int, Ge(ge=0)] = 0, away: Annotated[int, Ge(ge=0)] = 0)

Match score.

Parameters:

• home (int) – Home team score (default=0)

• away (int) – Away team score (default=0)

class ilc_models.Substitution(*, team: str, time: EventTime, event_type: Literal['sub'] = 'sub', player_on: BasePlayer, player_off: BasePlayer)

Represents a substitution.

Parameters:

• event_type (str) – The literal string ‘sub’

• player_on (BasePlayer) – Player entering the field

• player_off (BasePlayer) – Player leaving the field

players() → list[BasePlayer]

Get the players involved in this event

class ilc_models.TableRow(*, team: str, won: Annotated[int, Ge(ge=0)] = 0, drawn: Annotated[int, Ge(ge=0)] = 0, lost: Annotated[int, Ge(ge=0)] = 0, scored: Annotated[int, Ge(ge=0)] = 0, conceded: Annotated[int, Ge(ge=0)] = 0, deducted: Annotated[int, Ge(ge=0)] = 0, form: Annotated[str, _PydanticGeneralMetadata(pattern='^[WLD]{0,5}$')] = '')

A row in a league table.

Parameters:

• team (str) – Team name

• won (int) – Matches won (default=0)

• drawn (int) – Matches drawn (default=0)

• lost (int) – Matches lost (default=0)

• scored (int) – Goals scored (default=0)

• conceded (int) – Goals conceded (default=0)

• deducted (int) – Points deducted (default=0)

• form (str) – Team form e.g. ‘WDWWL’ (default=’’)

add_form(result: Literal['W', 'D', 'L']) → None

Add a match result to the form field.

Appends ‘W’, ‘D’ or ‘L’ to the team form, removing the oldest form indicator if the form is already displaying five matches, e.g. adding ‘D’ to ‘WWLL’ will result in ‘WWLLD’, while adding ‘D’ to ‘WWLLD’ will result in ‘WLLDD’.

Parameters:

result (str) – Result to add (‘W’, ‘L’ or ‘D’)

as_tuple() → RowTuple

Returns this row as a tuple.

Elements are: (team, played, won, drawn, lost, scored, conceded, gd, points, form)

Returns:

This row as a tuple

Return type:

RowTuple

classmethod from_tuple(row_tuple: RowTuple) → TableRow

Creates a TableRow instance from a RowTuple.

Parameters:

row_tuple (RowTuple) – Source tuple

Returns:

Newly created TableRow

Return type:

TableRow

property gd: int

Goal difference.

Returns:

The goal difference, i.e. goals scored minus goals conceded

Return type:

int

property played: int

Matches played.

Returns:

The total number of matches played

Return type:

int

property points: int

Total points gained.

Returns:

The total number of points gained

Return type:

int

class ilc_models.Teams(*, home: str, away: str)

The teams in a match.

Parameters:

• home (str) – Home team

• away (str) – Away team

ilc_models.validate_deduction_date(value: Any, handler: ValidatorFunctionWrapHandler) → str

Validate that a value conforms to a valid DOB string.

Allows empty string and yyyy-mm-dd. Any other format will raise a ValueError.

Parameters:

• value (typing.Any) – DOB to validate

• handler (pydantic.ValidatorFunctionWrapHandler) – Pydantic validation handler

Returns:

Validated value in yyyy-mm-dd format

Return type:

str

Raises:

ValueError if format is invalid

ilc_models.validate_dob(value: Any, handler: ValidatorFunctionWrapHandler) → str

Validate that a value conforms to a valid DOB string.

Allows empty string, yyyy-m-d and yyyy-mm-dd. Any other format will raise a ValueError.

Parameters:

• value (typing.Any) – DOB to validate

• handler (pydantic.ValidatorFunctionWrapHandler) – Pydantic validation handler

Returns:

Validated value in yyyy-mm-dd format

Return type:

str

Raises:

ValueError if format is invalid