diff --git a/CHANGELOG.md b/CHANGELOG.md index 1d8d7a3..a90fbf5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 diff --git a/src/livetennisapi/models.py b/src/livetennisapi/models.py index 276d924..8b205ea 100644 --- a/src/livetennisapi/models.py +++ b/src/livetennisapi/models.py @@ -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 @@ -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 @@ -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 diff --git a/tests/test_models.py b/tests/test_models.py index af82431..9edfa62 100644 --- a/tests/test_models.py +++ b/tests/test_models.py @@ -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): @@ -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"