diff --git a/CHANGELOG.md b/CHANGELOG.md index 3ba95dce..0a260dad 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -668,6 +668,16 @@ policies are unchanged. - `src/display_arbiter.py` -- the display loop's Arbiter (see Tooling). Core-internal: plugins have no reason to import it, so it sets no `ledmatrix_min_version` floor. +- `src/common/sports_game_over.py` -- `SportsGameOverMixin`, sports + consolidation family 5: `_is_game_really_over`, the scoreboards' + `SportsLive` check that drops a game ESPN still lists as live, once the + plugins made their five bodies one. Over on a final period text, or on a + 0:00 clock from period `FINAL_PERIOD` on unless the score is level (a tie + at the end of regulation goes to overtime). `FINAL_PERIOD` is the per-sport + class attribute, `None` by default (the clock never ends a game); the + scoreboards declare 3 (hockey), 4 (basketball, football, lacrosse) or + `None`. List the mixin before `SportsLiveSharedMixin`. A plugin may import + it once it floors on the release that ships it, and deletes its copy then. ### Tooling diff --git a/docs/SPORTS_UNIFICATION.md b/docs/SPORTS_UNIFICATION.md index fe72fe06..3c7072f2 100644 --- a/docs/SPORTS_UNIFICATION.md +++ b/docs/SPORTS_UNIFICATION.md @@ -91,6 +91,7 @@ more. Shared sports code lives in `src/common`: | `sports_live_scroll.py` | next release | `SportsLiveScrollMixin` — rebuild a live scroll strip mid-cycle, keeping the marquee's place | | `sports_display_rules.py` | next release | `SportsCardOptionsMixin`, `SportsGameRulesMixin` — scorebug date options, the no-favourites filter, non-favourite live dwell | | `sports_font_path.py` | next release | `resolve_font_path` — what the plugins' `_resolve_font_path` copies return | +| `sports_game_over.py` | next release | `SportsGameOverMixin` — `_is_game_really_over`, with the `FINAL_PERIOD` seam (family 5) | Each is described in [src/common/README.md](../src/common/README.md). @@ -134,8 +135,7 @@ constants rather than behavior: | Attribute | Meaning | Default | |---|---|---| -| `FINAL_PERIOD` | Period at/after which a zero clock can mean "over" | `4` (hockey overrides to `3`) | -| `CLOCK_COUNTS_DOWN` | Whether `0:00` means "expired" | `True` (soccer/afl/nrl override to `False` — their clocks count up, so `0:00` is kickoff) | +| `FINAL_PERIOD` | Period from which a 0:00 clock ends a game (`sports_game_over`) | `None`: the clock never ends a game (afl, nrl, soccer, baseball, ufc). Hockey sets `3`; basketball, football and lacrosse `4` | | `COALESCE_SCORING_SEQUENCE` | Fold score increments arriving during an active celebration into that one celebration | `False` (football overrides to `True` — a touchdown lands as +6, then +1 for the extra point) | ### Why these are seams and not branches @@ -146,11 +146,14 @@ so NRL matches favorites on team ID. Flattening every plugin to abbreviations would silently select the wrong club for NRL users. The base declares the seam, NRL fills it, and core never learns the string `"nrl"`. -`CLOCK_COUNTS_DOWN` exists for the same reason in the opposite direction: a +`FINAL_PERIOD` exists for the same reason in the opposite direction: a soccer clock reading `0:00` means the match has not kicked off, so running the -clock-expiry branch there would evict live games. +clock-expiry rule there would evict live games. Those sports declare `None`, +and so do baseball (innings, not a clock) and ufc (a bout ends only on ESPN's +final status). One attribute covers both questions, whether the clock can end +a game and from which period, so no separate count-down flag was added. -`COALESCE_SCORING_SEQUENCE` is the third of the same kind. In football one +`COALESCE_SCORING_SEQUENCE` is another of the same kind. In football one scoring play arrives as two score updates, so the follow-up must be folded into the first celebration; in soccer two increments a few seconds apart are two real goals, and folding them would swallow one. Neither default is "right" — which is @@ -298,6 +301,20 @@ Left in the plugins, though identical: renderers) is already core's, in `SportsHelpersMixin`; a renderer that wants it can inherit that. +### Family 5: the game-over check (core done; adoption waits for a release) + +The pilot of the method below. ledmatrix-plugins `scripts/test_game_over_check.py` +(#621) pinned 3,115 answers across the nine plugins first; the reconcile +(ledmatrix-plugins #625) made the five bodies one and +changed only the cells the owner's decisions under +[Product decisions](#product-decisions-each-family-needs) explain: ufc's +clock rule (65 cells), baseball's dormant one (53, every one a game with a +`period` baseball's games never carry), and a level score at 0:00 (five +cells in hockey, basketball, football and lacrosse). The harness renders +were pixel-identical. `src/common/sports_game_over.py` holds the body; +`test/test_sports_game_over_parity.py` compares it, and each plugin's +`FINAL_PERIOD`, with the plugin copies. + ### Why the method changes Byte-identical promotion has nearly run dry. Measured on ledmatrix-plugins @@ -333,8 +350,8 @@ game-over check); the report measures each method in it. The procedure: line in each plugin. - *A per-sport fact* (hockey ends in period 3; a soccer clock counts up). Make it a declared class constant or override point with a default, as - `FINAL_PERIOD`, `CLOCK_COUNTS_DOWN`, `COALESCE_SCORING_SEQUENCE` and - `_favorite_key` are, and add it to the tables above. Never a sport-name + `FINAL_PERIOD`, `COALESCE_SCORING_SEQUENCE` and `_favorite_key` are, + and add it to the tables above. Never a sport-name branch: core must not learn sport names. - *A product difference*: anything a user can see (which games show, a colour, a date, a badge, how long a screen stays). The owner picks the @@ -382,7 +399,7 @@ release. | # | Family | Methods (variants) | Why here | |---|---|---|---| | 4 | Identical sweep | `manager.py`: `_dispatch_switch_refresh`, `_favorite_team_is_live`, `get_vegas_priority_weight`, `_game_involves`, `_favorite_scan_targets`, `_favorite_scan_games`, `_get_total_games_for_manager` (all nine, 1); the live-scroll helpers `_preserving_scroll_position`, `_refresh_live_scroll_managers`, `_live_scroll_managers`, `_note_live_scroll_built`, `_live_scroll_needs_rebuild`, `_live_scroll_fields` (eight, 1). `sports.py`: `_card_option`, `_filtered_or_all`, `_effective_live_duration`, `_recent_date_text` (eight, 1). 58 identical families in all | Nothing to decide; brings `manager.py` into core as a `SportsPluginHostMixin`. `_resolve_font_path` (identical in nine `sports.py` and eight renderers) becomes `sports_font_path.resolve_font_path`, not `font_layout.resolve_asset_path`, which skips the cwd. Core side done; see [Stage 4](#stage-4-the-identical-sweep-core-done-adoption-waits-for-a-release) | -| 5 | Game-over check | `SportsLive._is_game_really_over` (5) | Pure logic, no pixels; its seams (`FINAL_PERIOD`, `CLOCK_COUNTS_DOWN`) were designed in B1. The pilot for the procedure | +| 5 | Game-over check | `SportsLive._is_game_really_over` (5) | Pure logic, no pixels; one seam, `FINAL_PERIOD`. The pilot for the procedure. Reconciled to one body and promoted as `sports_game_over`; adoption waits for the release that ships it. See [Family 5](#family-5-the-game-over-check-core-done-adoption-waits-for-a-release) | | 6 | Favourite matching | `_is_favorite_game` (7 across three classes), `_select_games_for_display` (2: nrl), `_select_recent_games_for_display` (3) | Everything that asks "is this a favourite" goes through the 3.5.0 `_favorite_key` seam | | 7 | Other-games rotation | `_by_importance`, `_other_games_window`, `_advance_other_games_if_due` (2 each: football), `_rotate_other_games_on_display` (2: ufc) | One outlier each; football carries two fixes the other eight lack | | 8 | Rankings | `_fetch_team_rankings` (3), `_choose_poll` (3), `_load_division_team_ids`, `_passes_other_filters`, `_best_rank`, `_is_ranked_game` (2 each: football) | Needs 7; the rank badge and the "ranked only" filter read it | @@ -416,17 +433,17 @@ family 9 prepares. Owner calls to make before (or while) reconciling. Items marked *verify* are suspected behaviour that needs a payload or a rig to confirm first. -- **5, game-over check.** Which rule each sport gets: the clock never ends a - game in afl, nrl and soccer (`CLOCK_COUNTS_DOWN = False`); hockey ends at - 0:00 from period 3, basketball, football and lacrosse from period 4. - baseball and ufc share a copy that reads a missing clock as "0:00": dormant - in baseball (its games carry no `period`), and not triggered by ufc's round - breaks either. ESPN sends a break as `STATUS_END_OF_ROUND` with displayClock - `-`, not `0:00` (verified against recorded payloads; ledmatrix-plugins#580 - pins it). Whatever rule ufc gets must not read `-` as `0:00`. Decide ufc's - rule: no clock rule (ESPN's `STATUS_FINAL` is the only end signal it needs; - this also closes a ~1 s window at the horn when the ticking clock reads - `0:00`), or its own final period. +- **5, game-over check. Decided 2026-10-05, done:** one seam, + `FINAL_PERIOD`: hockey 3; basketball, football and lacrosse 4; `None` (the + clock never ends a game) for afl, nrl and soccer (clocks that count up), + baseball (its games carry no `period`, so the old rule was dormant) and + ufc (a bout ends only on ESPN's final status, which also closes the ~1 s + window at the horn when the ticking clock reads `0:00`; ESPN's round-break + displayClock `-` was never a zero clock, ledmatrix-plugins#580). Only a + non-empty clock string counts (the baseball/ufc copy read a missing clock + as `0:00`). A score level at 0:00 is not over: the game stays live through + the break before overtime, and one that really ends tied ends on its final + status. Baseball keeps its postponed/suspended override in `BaseballLive`. - **6, favourite matching.** NRL keeps matching favourites by team id (abbreviations collide: NEW, CAN), through `_favorite_key` rather than its own copies of the selection methods. Six plugins log the recent-games diff --git a/mypy-clean.txt b/mypy-clean.txt index 63f6f5bc..ffc7a6c5 100644 --- a/mypy-clean.txt +++ b/mypy-clean.txt @@ -38,6 +38,7 @@ src/common/sports_celebration.py src/common/sports_display_rules.py src/common/sports_fetch.py src/common/sports_font_path.py +src/common/sports_game_over.py src/common/sports_live_scroll.py src/common/sports_plugin_host.py src/common/sports_scroll.py diff --git a/src/common/README.md b/src/common/README.md index a0f46287..b84198c7 100644 --- a/src/common/README.md +++ b/src/common/README.md @@ -46,6 +46,7 @@ Rules for the package: | [`sports_display_rules`](#sports_display_rules) | Which games a scoreboard shows, for how long, and its scorebug date line | Yes (scoreboards) | 3.8.0 | | [`sports_fetch`](#sports_fetch) | Scoreboard season fetch, lookback and live-odds decisions | Yes (scoreboards) | 3.7.0 | | [`sports_font_path`](#sports_font_path) | Find a scoreboard's bundled font whatever the cwd | Yes (scoreboards) | 3.8.0 | +| [`sports_game_over`](#sports_game_over) | Whether a game ESPN still lists as live has ended | Yes (scoreboards) | next release | | [`sports_game_renderer`](#sports_game_renderer) | Scoreboard scroll/Vegas card geometry | Yes (scoreboards) | 3.3.0 | | [`sports_helpers`](#sports_helpers) | Small helpers every scoreboard `sports.py` copies | Yes (scoreboards) | 3.5.0 | | [`sports_live_scroll`](#sports_live_scroll) | Rebuild a live scroll strip mid-cycle without moving it | Yes (scoreboards) | 3.8.0 | @@ -294,6 +295,16 @@ path as given when it exists (relative to the cwd), else `font_layout.resolve_asset_path(path)`. What the scoreboards' `_resolve_font_path` copies return on a core that ships it. +### sports_game_over + +[`sports_game_over.py`](sports_game_over.py). `SportsGameOverMixin`: +`_is_game_really_over(game)`, the `SportsLive` check that drops a game ESPN +still lists as live (`SportsLiveSharedMixin._detect_stale_games` calls it). +Over on a final period text, or on a 0:00 clock from period `FINAL_PERIOD` +on unless the score is level. `FINAL_PERIOD` is a class attribute the host +sets per sport; the default `None` means the clock never ends a game. List +it before `SportsLiveSharedMixin`. + ### sports_game_renderer [`sports_game_renderer.py`](sports_game_renderer.py). diff --git a/src/common/sports_game_over.py b/src/common/sports_game_over.py new file mode 100644 index 00000000..3288af7e --- /dev/null +++ b/src/common/sports_game_over.py @@ -0,0 +1,125 @@ +"""Whether a game ESPN still lists as live has in fact ended (sports family 5). + +``SportsGameOverMixin._is_game_really_over`` is the scoreboards' +``SportsLive._is_game_really_over``, reconciled in ledmatrix-plugins +#625 from five bodies into one and copied here under +its existing name. ``SportsLiveSharedMixin._detect_stale_games`` +(``src.common.sports_shared``) calls it on every live game, and the plugins' +live-priority filters call it too, to drop a game ESPN still reports as +in progress. + +A game is over when its period text says final. From period ``FINAL_PERIOD`` +on, a clock reading 0:00 ends it too, unless the score is level: a tie at the +end of regulation goes to overtime (or a shootout), and a game that does end +tied says final. Only a clock *string* is read ("0:00" and ":00" are zero; +":40", "0.0" and ESPN's "-" between MMA rounds are not), and a missing or +unreadable score leaves the decision to the clock. + +``FINAL_PERIOD`` is the one per-sport fact, a class attribute rather than a +sport-name branch. The scoreboards declare it on their ``SportsLive``: + +- 3: hockey; +- 4: basketball, football, lacrosse; +- ``None`` (this default; the clock never ends a game): afl, nrl and soccer, + whose clocks count up; baseball, which has innings; ufc, whose bouts end + only on ESPN's final status. + +A sport can still override the method and defer to it, as baseball's +``BaseballLive`` does to end postponed and suspended games first. + +A new module rather than another method on ``sports_shared``, for the reason +``sports_helpers`` gives: a missing module fails at load, where the version +checks see it; a missing method fails mid-update. + +WHAT A HOST MUST PROVIDE +------------------------ +Derived by walking every ``self.`` the mixin reads; the host-contract +test in ``test/test_sports_game_over.py`` fails if a read is added without +being listed here. + +- ``logger`` -- a ``logging.Logger``; the method logs its verdict at DEBUG. +- ``FINAL_PERIOD`` -- defaulted here to ``None``; set it on the host class. + +The method reads the game dict's ``away_abbr``, ``home_abbr``, +``period_text``, ``period``, ``clock``, ``away_score`` and ``home_score`` +(``_extract_game_details_common``'s keys); any of them may be missing or +null. + +BASE ORDER +---------- +List the mixin before ``SportsLiveSharedMixin`` -- +``class SportsLive(SportsGameOverMixin, SportsLiveSharedMixin, SportsCore)`` -- +so the shared mixin's ``_detect_stale_games`` finds this method through the +MRO. Neither shared mixin defines it, so the order does not change which body +runs today; it keeps the method next to its caller should one ever be added +there. A method on the plugin's own class still wins, and its ``super()`` +reaches this one. The mixin has no ``__init__`` and no state. +""" + +import logging +from typing import Dict, Optional + + +class SportsGameOverMixin: + """The live manager's "is this game really over?" check. See module docstring.""" + + # The host contract, declared for type checking only. + logger: logging.Logger + + #: Period from which a 0:00 clock ends a game; None: the clock never does. + FINAL_PERIOD: Optional[int] = None + + def _is_game_really_over(self, game: Dict) -> bool: + """Whether a game ESPN still lists as live has in fact ended. + + It has when its period text says final. From period ``FINAL_PERIOD`` + on, a clock at 0:00 ends it too, unless the score is level: a tie at + the end of regulation goes to overtime, and a game that does end tied + says final. With ``FINAL_PERIOD = None`` the clock never ends a game. + """ + game_str = f"{game.get('away_abbr')}@{game.get('home_abbr')}" + + # ESPN can send the key as null, and .get()'s default only covers a + # missing key, so a None here crashed the whole live update. + raw_period_text = game.get("period_text") + period_text = raw_period_text.lower() if isinstance(raw_period_text, str) else "" + if "final" in period_text: + self.logger.debug( + f"_is_game_really_over({game_str}): " + f"returning True - 'final' in period_text='{period_text}'" + ) + return True + + # Same for a null or non-numeric period: treat it as period 0. + try: + period = int(game.get("period") or 0) + except (TypeError, ValueError, OverflowError): + period = 0 + # Only a clock string is read: "0:00" and ":00" are zero; ":40" is not. + clock = game.get("clock") + clock_at_zero = isinstance(clock, str) and clock.replace(":", "").strip() in ("000", "00") + + if self.FINAL_PERIOD is not None and period >= self.FINAL_PERIOD and clock_at_zero: + try: + tied = int(game["away_score"]) == int(game["home_score"]) + except (KeyError, TypeError, ValueError, OverflowError): + tied = False # a missing or unreadable score leaves it to the clock + if not tied: + self.logger.debug( + f"_is_game_really_over({game_str}): " + f"returning True - clock at 0:00 (clock='{clock}', period={period})" + ) + return True + self.logger.debug( + f"_is_game_really_over({game_str}): " + f"returning False - tied at 0:00 (period={period}), overtime next" + ) + return False + + self.logger.debug( + f"_is_game_really_over({game_str}): returning False" + ) + return False + + +__all__ = ["SportsGameOverMixin"] diff --git a/src/common/sports_shared.py b/src/common/sports_shared.py index 954a9b1f..f1efbbd7 100644 --- a/src/common/sports_shared.py +++ b/src/common/sports_shared.py @@ -57,7 +57,9 @@ Methods that stay per-plugin, because they are not identical across the eight ``_get_layout_offset``, ``_by_importance``, ``_other_games_window``, ``_upcoming_date_and_time_text``, ``_extract_game_details_common``, ``_load_division_team_ids``, ``_get_timezone``, ``_is_favorite_game``, -``_is_game_really_over``, ``_is_ranked_game``, ``_passes_other_filters``. +``_is_ranked_game``, ``_passes_other_filters``. (``_is_game_really_over``, +which ``_detect_stale_games`` below calls, was here too until the plugins +reconciled it; it is now ``src.common.sports_game_over``.) Of the fourteen shared class constants, thirteen are identical everywhere and live here. Only ``_SCORE_PROBE_TEXT`` varies -- afl and basketball reach three digits diff --git a/test/test_sports_game_over.py b/test/test_sports_game_over.py new file mode 100644 index 00000000..4e83e75f --- /dev/null +++ b/test/test_sports_game_over.py @@ -0,0 +1,275 @@ +"""src.common.sports_game_over: behaviour, host contract and base order. + +The matrix is ledmatrix-plugins' ``scripts/test_game_over_check.py`` (the +table the family 5 reconcile was checked against) folded to the three +``FINAL_PERIOD`` values the nine scoreboards declare: None (afl, baseball, +nrl, soccer, ufc), 4 (basketball, football, lacrosse) and 3 (hockey). +Baseball's postponed/suspended override stays in its plugin and is not here. +""" + +import ast +import logging +import time +from pathlib import Path + +import pytest + +from src.common import sports_game_over +from src.common.sports_game_over import SportsGameOverMixin +from src.common.sports_shared import SportsLiveSharedMixin + +LOG = logging.getLogger("test_sports_game_over") + + +def host(final_period): + """A live manager stand-in declaring ``FINAL_PERIOD`` as a plugin does.""" + cls = type("Live", (SportsGameOverMixin,), {"FINAL_PERIOD": final_period}) + h = cls() + h.logger = LOG + return h + + +MISSING = object() # the key is absent from the game dict + + +def game(period_text="", period=MISSING, clock=MISSING, away="1", home="2"): + g = {"away_abbr": "AWY", "home_abbr": "HOM", "away_score": away, + "home_score": home, "period_text": period_text} + if period is not MISSING: + g["period"] = period + if clock is not MISSING: + g["clock"] = clock + return g + + +# --------------------------------------------------------------------------- +# The matrix: clock x period, for each FINAL_PERIOD. Scores 1-2. +# --------------------------------------------------------------------------- + +FINAL_PERIODS = (None, 4, 3) +PERIODS = (MISSING, 1, 2, 3, 4, 5, 6) +CLOCKS = {"12:00": "12:00", "0:00": "0:00", ":00": ":00", "0.0": "0.0", + "-": "-", "''": "", "None": None, "missing": MISSING} + +#: The period text each ESPN status carries. Only "Final" contains "final"; +#: the method reads no status, so every other text answers the same row. +LIVE_TEXTS = { + "in progress": lambda p: "" if p is MISSING else f"P{p}", + "end of period": lambda p: "" if p is MISSING else f"End P{p}", + "halftime": lambda p: "Halftime", + "end of round": lambda p: "" if p is MISSING else f"End R{p}", + "postponed": lambda p: "Postponed", +} + +#: clock -> one cell per period (missing, 1..6) for FINAL_PERIOD None, 4, 3. +EXPECTED_LIVE = { + "12:00": "....... ....... .......", + "0:00": "....... ....YYY ...YYYY", + ":00": "....... ....YYY ...YYYY", + "0.0": "....... ....... .......", + "-": "....... ....... .......", + "''": "....... ....... .......", + "None": "....... ....... .......", + "missing": "....... ....... .......", +} + + +def row(text_for, clock): + return " ".join( + "".join("Y" if host(fp)._is_game_really_over(game(text_for(p), p, clock)) else "." + for p in PERIODS) + for fp in FINAL_PERIODS) + + +@pytest.mark.parametrize("status", sorted(LIVE_TEXTS)) +@pytest.mark.parametrize("clock_label", sorted(CLOCKS)) +def test_a_live_period_text(status, clock_label): + assert row(LIVE_TEXTS[status], CLOCKS[clock_label]) == EXPECTED_LIVE[clock_label] + + +@pytest.mark.parametrize("clock_label", sorted(CLOCKS)) +def test_a_final_period_text_is_always_over(clock_label): + assert row(lambda p: "Final", CLOCKS[clock_label]) == "YYYYYYY YYYYYYY YYYYYYY" + + +#: label -> (game, one cell per FINAL_PERIOD None, 4, 3) +EDGES = { + "period_text None, P4 0:00": (game(None, 4, "0:00"), ".YY"), + "period None, 0:00": (game("", None, "0:00"), "..."), + "period 'OT', 0:00": (game("OT", "OT", "0:00"), "..."), + "period '4' (str), 0:00": (game("P4", "4", "0:00"), ".YY"), + "clock int 0, P4": (game("P4", 4, 0), "..."), + "clock float 0.0, P4": (game("P4", 4, 0.0), "..."), + "clock ' 0:00 ', P4": (game("P4", 4, " 0:00 "), ".YY"), + "clock '00:00', P4": (game("P4", 4, "00:00"), "..."), + "period_text 'Final/OT', P5 0:00": (game("Final/OT", 5, "0:00"), "YYY"), + "period_text 'FINAL', P1 12:00": (game("FINAL", 1, "12:00"), "YYY"), +} + + +@pytest.mark.parametrize("label", sorted(EDGES)) +def test_edge_shapes(label): + g, want = EDGES[label] + got = "".join("Y" if host(fp)._is_game_really_over(dict(g)) else "." for fp in FINAL_PERIODS) + assert got == want + + +# --------------------------------------------------------------------------- +# The tie guard: level at 0:00 is overtime, not the end. +# --------------------------------------------------------------------------- + +class TestTieGuard: + @pytest.mark.parametrize("fp,period", [(4, 4), (4, 5), (3, 3), (3, 4), (3, 5)]) + def test_level_at_zero_is_not_over(self, fp, period): + assert host(fp)._is_game_really_over(game("", period, "0:00", "2", "2")) is False + + def test_level_scores_compare_as_numbers(self): + assert host(4)._is_game_really_over(game("", 4, "0:00", 2, "2")) is False + assert host(4)._is_game_really_over(game("", 4, "0:00", " 2 ", "2")) is False + + def test_a_game_that_ends_level_ends_on_final(self): + assert host(4)._is_game_really_over(game("Final/OT", 5, "0:00", "2", "2")) is True + + def test_level_before_the_final_period_was_never_over(self): + assert host(4)._is_game_really_over(game("", 3, "0:00", "2", "2")) is False + + @pytest.mark.parametrize("away,home", [ + (MISSING, MISSING), (None, None), ("", ""), ("2", None), + ("2.0", "2.0"), ({"value": 2}, {"value": 2}), ("inf", "inf"), + ]) + def test_an_unreadable_score_leaves_it_to_the_clock(self, away, home): + g = game("", 4, "0:00") + for key, value in (("away_score", away), ("home_score", home)): + if value is MISSING: + del g[key] + else: + g[key] = value + assert host(4)._is_game_really_over(g) is True + + def test_float_infinity_does_not_raise(self): + assert host(4)._is_game_really_over( + game("", 4, "0:00", float("inf"), float("inf"))) is True + + +# --------------------------------------------------------------------------- +# ufc: ESPN MMA payloads, as ufc's _extract_game_details stores them +# (ledmatrix-plugins plugins/ufc-scoreboard/test/fixtures/espn_mma_round_states.json). +# --------------------------------------------------------------------------- + +UFC_RECORDED = { + "in_round_3_of_3": ("R3", 3, "1:21"), + "break_after_round_1": ("R1", 1, "-"), + "end_of_round_after_stoppage": ("R2", 2, "0:51"), + "walkouts_five_rounder": ("", 0, "-"), + "final_five_round_decision": ("R5", 5, "5:00"), + "final_five_round_stoppage": ("R5", 5, "1:38"), + "final_three_round_decision": ("R3", 3, "5:00"), + "final_three_round_stoppage": ("R2", 2, "4:07"), + "break_after_round_4_of_5": ("R4", 4, "-"), + "end_of_round_5_awaiting_decision": ("R5", 5, "-"), +} + + +class TestUfc: + @pytest.mark.parametrize("name", sorted(UFC_RECORDED)) + def test_no_recorded_state_is_over_here(self, name): + """A finished bout leaves the live list on is_final, before this is asked.""" + text, period, clock = UFC_RECORDED[name] + assert host(None)._is_game_really_over(game(text, period, clock, "0", "0")) is False + + @pytest.mark.parametrize("fp", FINAL_PERIODS) + def test_a_round_break_dash_is_never_a_zero_clock(self, fp): + assert host(fp)._is_game_really_over(game("R4", 4, "-", "1", "2")) is False + + @pytest.mark.parametrize("clock", ["0:00", None, MISSING]) + def test_the_horn_does_not_end_a_bout(self, clock): + assert host(None)._is_game_really_over(game("R5", 5, clock, "1", "2")) is False + + +# --------------------------------------------------------------------------- +# Wiring: the default, overrides, and the live mixin's caller. +# --------------------------------------------------------------------------- + +def test_the_default_is_no_clock_rule(): + assert SportsGameOverMixin.FINAL_PERIOD is None + + +def test_an_override_defers_through_super(): + """baseball's BaseballLive: its own check first, then the shared one.""" + + class Baseballish(SportsGameOverMixin): + logger = LOG + + def _is_game_really_over(self, game): + if game.get("status") == "status_postponed": + return True + return super()._is_game_really_over(game) + + b = Baseballish() + assert b._is_game_really_over(dict(game("", 6, "0:00"), status="status_postponed")) is True + assert b._is_game_really_over(game("", 6, "0:00")) is False + assert b._is_game_really_over(game("Final", 9, None)) is True + + +class _Live(SportsGameOverMixin, SportsLiveSharedMixin): + """A SportsLive stand-in in the documented base order.""" + + FINAL_PERIOD = 4 + + def __init__(self): + self.logger = LOG + self.stale_game_timeout = 600 + self.game_update_timestamps = {} + + +class TestBaseOrder: + def test_the_documented_order_resolves_this_method(self): + assert _Live._is_game_really_over is SportsGameOverMixin._is_game_really_over + mro = _Live.__mro__ + assert mro.index(SportsGameOverMixin) < mro.index(SportsLiveSharedMixin) + + def test_neither_shared_mixin_defines_it(self): + """So the base order cannot change which body runs.""" + from src.common.sports_shared import SportsCoreSharedMixin + for mixin in (SportsLiveSharedMixin, SportsCoreSharedMixin): + assert "_is_game_really_over" not in vars(mixin) + + def test_detect_stale_games_drops_an_over_game_through_it(self): + live = _Live() + live.game_update_timestamps = {"over": {"last_seen": time.time()}, + "on": {"last_seen": time.time()}} + games = [dict(game("", 4, "0:00"), id="over"), + dict(game("", 4, "0:00", "2", "2"), id="on")] + live._detect_stale_games(games) + assert [g["id"] for g in games] == ["on"] + assert "over" not in live.game_update_timestamps + + def test_the_class_value_wins_over_the_default(self): + assert _Live().FINAL_PERIOD == 4 + assert _Live()._is_game_really_over(game("", 4, "0:00")) is True + + +# --------------------------------------------------------------------------- +# Host contract +# --------------------------------------------------------------------------- + +def _self_reads(): + tree = ast.parse(Path(sports_game_over.__file__).read_text(encoding="utf-8")) + cls = next(n for n in tree.body + if isinstance(n, ast.ClassDef) and n.name == "SportsGameOverMixin") + return {node.attr for node in ast.walk(cls) + if isinstance(node, ast.Attribute) and isinstance(node.ctx, ast.Load) + and isinstance(node.value, ast.Name) and node.value.id == "self"} + + +class TestHostContract: + def test_every_host_read_is_documented(self): + undocumented = sorted(n for n in _self_reads() + if f"``{n}``" not in sports_game_over.__doc__) + assert undocumented == [], f"read but not in the host contract: {undocumented}" + + def test_the_mixin_creates_no_state(self): + assert "__init__" not in vars(SportsGameOverMixin) + assert not hasattr(SportsGameOverMixin, "logger") + assert sorted(n for n in vars(SportsGameOverMixin) if not n.startswith("__")) == [ + "FINAL_PERIOD", "_is_game_really_over"] diff --git a/test/test_sports_game_over_parity.py b/test/test_sports_game_over_parity.py new file mode 100644 index 00000000..8f09aaee --- /dev/null +++ b/test/test_sports_game_over_parity.py @@ -0,0 +1,123 @@ +"""sports_game_over still matches every plugin copy, and each plugin's FINAL_PERIOD. + +``SportsGameOverMixin._is_game_really_over`` was copied from the scoreboards' +``SportsLive._is_game_really_over`` once family 5 had made the nine copies one +body. The plugins delete their copies once they floor on the release that +ships this module. Until each has, a copy that changes on its own is a fix one +side has and the other lacks. + +Point LEDMATRIX_PLUGINS at a ledmatrix-plugins checkout and the method is +compared with every plugin copy using ``scripts/sports_drift_report.py``'s own +normalisation (the AST with docstrings and annotations dropped), plus the +decorators. A copy that is gone counts as adopted when the plugin's +``sports.py`` names the module. Each plugin's ``SportsLive.FINAL_PERIOD`` is +compared with the value the owner decided for its sport, which stays in the +plugin after adoption. Without the variable this skips: core CI has no plugins +checkout. +""" + +import ast +import importlib.util +import os +from pathlib import Path + +import pytest + +from src.common import sports_game_over + +REPO = Path(__file__).resolve().parents[1] + +#: The owner's decision (docs/SPORTS_UNIFICATION.md, family 5): the period +#: from which a 0:00 clock ends a game, None where the clock never does. +FINAL_PERIOD = { + "afl": None, "baseball": None, "basketball": 4, "football": 4, + "hockey": 3, "lacrosse": 4, "nrl": None, "soccer": None, "ufc": None, +} +NAME = "_is_game_really_over" + + +def _drift_report(): + """scripts/sports_drift_report.py, loaded by path (scripts/ is no package).""" + spec = importlib.util.spec_from_file_location( + "sports_drift_report", REPO / "scripts" / "sports_drift_report.py") + module = importlib.util.module_from_spec(spec) + spec.loader.exec_module(module) + return module + + +DRIFT = _drift_report() + + +def _plugins_root(): + root = DRIFT.resolve_plugins_dir(os.environ.get("LEDMATRIX_PLUGINS")) + if root is None: + pytest.skip("set LEDMATRIX_PLUGINS to a ledmatrix-plugins checkout to " + "compare this module against the plugin copies") + return root + + +def _class(tree, name): + return next(n for n in tree.body if isinstance(n, ast.ClassDef) and n.name == name) + + +def _method(cls): + return next((n for n in cls.body + if isinstance(n, ast.FunctionDef) and n.name == NAME), None) + + +def _fingerprint(node): + return (DRIFT._digest(node, DRIFT._Canonical()), + tuple(ast.unparse(d) for d in node.decorator_list)) + + +def _final_period(cls): + for node in cls.body: + if (isinstance(node, (ast.Assign, ast.AnnAssign)) and node.value is not None): + target = node.targets[0] if isinstance(node, ast.Assign) else node.target + if isinstance(target, ast.Name) and target.id == "FINAL_PERIOD": + return ast.literal_eval(node.value) + raise AssertionError("SportsLive declares no FINAL_PERIOD") + + +def _ours(): + tree = ast.parse(Path(sports_game_over.__file__).read_text(encoding="utf-8")) + return _class(tree, "SportsGameOverMixin") + + +def test_the_mixin_holds_one_method_and_the_default(): + names = sorted(n.name if isinstance(n, ast.FunctionDef) else n.target.id + for n in _ours().body if isinstance(n, (ast.FunctionDef, ast.AnnAssign)) + and (isinstance(n, ast.FunctionDef) or n.value is not None)) + assert names == ["FINAL_PERIOD", NAME] + assert _final_period(_ours()) is None + + +@pytest.mark.parametrize("sport", sorted(FINAL_PERIOD)) +def test_every_remaining_plugin_copy_matches(sport): + root = _plugins_root() + source = (root / f"{sport}-scoreboard" / "sports.py").read_text(encoding="utf-8") + live = _class(ast.parse(source), "SportsLive") + copy = _method(live) + if copy is None: + assert sports_game_over.__name__ in source, ( + f"{sport}: no {NAME} on SportsLive and no {sports_game_over.__name__} import") + else: + assert _fingerprint(copy) == _fingerprint(_method(_ours())), ( + f"{NAME} in {sport} differs from sports_game_over. " + f"Port the change to both, or stop treating it as shared.") + + +@pytest.mark.parametrize("sport", sorted(FINAL_PERIOD)) +def test_every_plugin_declares_its_final_period(sport): + root = _plugins_root() + source = (root / f"{sport}-scoreboard" / "sports.py").read_text(encoding="utf-8") + assert _final_period(_class(ast.parse(source), "SportsLive")) == FINAL_PERIOD[sport] + + +def test_the_drift_report_still_calls_it_identical(): + root = _plugins_root() + families = DRIFT.build(root, ("sports.py",)) + rows = {(r["file"], r["family"]): r + for r in (DRIFT.summarise(k, v) for k, v in families.items())} + row = rows.get(("sports.py", NAME)) + assert row is None or row["worst_class_variants"] == 1