Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,24 @@
All notable changes to this project are documented here.
This project adheres to [Semantic Versioning](https://semver.org/).

## [Unreleased]

### Added
- **Seven `Fixture` fields from spec 1.13.82** — `reason` (`walkover` |
`retired` | `cancelled` | `default` | `postponed`), `match_id` (the id of
the match the fixture became, `None` until one exists), `gender` (`men` |
`women`, `None` for mixed events), `is_qualifying`, `created_at`,
`updated_at` (both parsed as UTC datetimes) and `pregame_forecasts`.
`is_qualifying` is three-valued: `None` means never stated, and `None` is
not `False`. `pregame_forecasts` is ULTRA only and absent below ULTRA, so
`None` means "not entitled" and `[]` means "no forecast yet".
- **`Match.is_qualifying` and `Match.pregame_forecasts`** — the same two
fields on the match model, with the same meaning. `pregame_forecasts` rides
on ULTRA `status="upcoming"` list rows only.

All of these were already readable through `raw` and attribute passthrough.
They are now typed, documented and parsed.

## [1.8.0] — 2026-09-02

### Added
Expand Down
44 changes: 43 additions & 1 deletion src/livetennisapi/models.py
Original file line number Diff line number Diff line change
Expand Up @@ -285,7 +285,7 @@ class Fixture(Model):
"""

_date_fields: ClassVar[tuple[str, ...]] = ("event_date",)
_datetime_fields: ClassVar[tuple[str, ...]] = ("start_time",)
_datetime_fields: ClassVar[tuple[str, ...]] = ("start_time", "created_at", "updated_at")

id: int | None = None
event_date: date | None = None
Expand All @@ -301,6 +301,37 @@ class Fixture(Model):
player1_name: str | None = None
player2_name: str | None = None
status: str | None = None
#: Why a fixture ended without being played out: ``walkover`` |
#: ``retired`` | ``cancelled`` | ``default`` | ``postponed``. ``status``
#: folds the first four into ``cancelled``; this field names which one.
#: ``None`` on a scheduled, live or finished fixture.
reason: str | None = None
#: The ``id`` of the match this fixture became, which every match method
#: accepts. ``None`` while no match exists yet — a fixture can publish
#: days before its match. Set when found and never cleared.
match_id: int | None = None
#: ``men`` | ``women`` — the same vocabulary as the ``gender=`` filter.
#: ``None`` for mixed doubles and mixed team events.
gender: str | None = None
#: Whether the fixture is in the qualifying draw. Three-valued like
#: :attr:`Match.is_qualifying`: ``None`` means never stated, and ``None``
#: is not ``False``. The qualifying draw is published under the main
#: draw's tournament name, so group a schedule on ``round_code`` and this
#: flag together.
is_qualifying: bool | None = None
#: When this row first existed, UTC. A ``created_at`` inside your polling
#: window is a new row.
created_at: datetime | None = None
#: When this row last changed, UTC. A moved ``updated_at`` with
#: ``created_at`` unchanged is a change to a row you already hold, such as
#: a re-listed start time.
updated_at: datetime | None = None
#: *(ULTRA only)* the bound match's ``stage: pregame`` forecasts, oldest
#: first, each in the :attr:`Analysis.profile` shape. ``[]`` when the
#: fixture has no ``match_id`` yet or no forecast has been written. The
#: field is absent below ULTRA, so ``None`` means "not entitled", never
#: "no forecast".
pregame_forecasts: list[dict[str, Any]] | None = None


@dataclass
Expand Down Expand Up @@ -375,6 +406,17 @@ class Match(Model):
#: no_market``). ``None`` only when talking to a server that predates the
#: field.
has_market: bool | None = None
#: Whether this match belongs to the qualifying draw. Three-valued:
#: ``None`` means never stated, and ``None`` is not ``False``. The
#: qualifying draw shares the main draw's tournament name and round
#: vocabulary, so branch on ``round_code`` and this flag together.
is_qualifying: bool | None = None
#: *(ULTRA only, ``status="upcoming"`` list rows)* the match's
#: ``stage: pregame`` forecasts, oldest first, each in the
#: :attr:`Analysis.profile` shape. ``[]`` when none has been written yet.
#: The field is absent below ULTRA and on other statuses, so ``None``
#: means "not sent", never "no forecast".
pregame_forecasts: list[dict[str, Any]] | None = None
market: Market | None = None
analysis: Analysis | None = None

Expand Down
59 changes: 59 additions & 0 deletions tests/test_models.py
Original file line number Diff line number Diff line change
Expand Up @@ -186,6 +186,51 @@ def test_player_ids_and_round_code(self):
assert fixture.player2_id is None
assert fixture.round_code == "QF"

def test_reason_match_id_and_gender(self):
fixture = Fixture.from_dict(
{"id": 1, "status": "cancelled", "reason": "walkover", "match_id": 48213, "gender": "women"}
)
assert fixture.reason == "walkover"
assert fixture.match_id == 48213
assert fixture.gender == "women"

def test_reason_match_id_and_gender_are_nullable(self):
# No match row yet, a mixed event, a fixture that was played out: all null.
fixture = Fixture.from_dict({"id": 1, "reason": None, "match_id": None, "gender": None})
assert fixture.reason is None
assert fixture.match_id is None
assert fixture.gender is None

def test_is_qualifying_is_three_valued(self):
# None means never stated, and None is not False.
assert Fixture.from_dict({"id": 1, "is_qualifying": True}).is_qualifying is True
assert Fixture.from_dict({"id": 1, "is_qualifying": False}).is_qualifying is False
assert Fixture.from_dict({"id": 1, "is_qualifying": None}).is_qualifying is None
assert Fixture.from_dict({"id": 1}).is_qualifying is None

def test_created_at_and_updated_at_are_parsed(self):
fixture = Fixture.from_dict(
{"id": 1, "created_at": "2026-09-23T08:00:00Z", "updated_at": "2026-09-24T10:30:00Z"}
)
assert isinstance(fixture.created_at, datetime)
assert isinstance(fixture.updated_at, datetime)
assert fixture.created_at.tzinfo is not None
assert fixture.updated_at > fixture.created_at
nulls = Fixture.from_dict({"id": 1, "created_at": None, "updated_at": None})
assert nulls.created_at is None
assert nulls.updated_at is None

def test_pregame_forecasts_present(self):
# ULTRA only: the bound match's pregame forecasts, oldest first.
forecast = {"win_probability_p1": 0.61, "stage": "pregame", "created_at": "2026-09-24T07:00:00Z"}
fixture = Fixture.from_dict({"id": 1, "match_id": 48213, "pregame_forecasts": [forecast]})
assert fixture.pregame_forecasts == [forecast]
assert Fixture.from_dict({"id": 1, "pregame_forecasts": []}).pregame_forecasts == []

def test_pregame_forecasts_absent_means_none(self):
# The field is absent below ULTRA: None, never a guessed empty list.
assert Fixture.from_dict({"id": 1}).pregame_forecasts is None


class TestMatchNewFields:
def test_tour_and_tournament_id(self):
Expand Down Expand Up @@ -236,6 +281,20 @@ def test_has_analysis_and_has_market_absent_means_none(self):
assert match.has_analysis is None
assert match.has_market is None

def test_is_qualifying_is_three_valued(self):
# None means never stated, and None is not False.
assert Match.from_dict({"id": 1, "is_qualifying": True}).is_qualifying is True
assert Match.from_dict({"id": 1, "is_qualifying": False}).is_qualifying is False
assert Match.from_dict({"id": 1, "is_qualifying": None}).is_qualifying is None
assert Match.from_dict({"id": 1}).is_qualifying is None

def test_pregame_forecasts_present_and_absent(self):
# ULTRA only, on upcoming list rows. Absent everywhere else: None, never [].
forecast = {"win_probability_p1": 0.58, "stage": "pregame"}
assert Match.from_dict({"id": 1, "pregame_forecasts": [forecast]}).pregame_forecasts == [forecast]
assert Match.from_dict({"id": 1, "pregame_forecasts": []}).pregame_forecasts == []
assert Match.from_dict({"id": 1}).pregame_forecasts is None

def test_draw_is_three_valued(self):
assert Match.from_dict({"id": 1, "draw": "singles"}).draw == "singles"
assert Match.from_dict({"id": 1, "draw": "doubles"}).draw == "doubles"
Expand Down
Loading