supercontest.core.scores

Logic for fetching NFL scores and committing them to the database.

Module Attributes

PERIOD_ABBVS	Maps the quarter reported by ESPN to the matching espn_abbv in the statuses table.
KICKOFF_WINDOW_MINUTES	Minutes before and after a kickoff that scores are fetched regardless of status: is_around_kickoff()'s window.
MAX_IDLE	The longest the job stays idle without looking at the database again.

Functions

commit_scores	Wrapper for all score committing functionality.
fetch_scores_json	Hits the ESPN scoreboard JSON API for live score updates and the time status of the game.
get_scoreboard	Reads ESPN's scoreboard.
is_idle	Whether the scores job can answer "nothing to do" without the database.
match_scoreboard	Matches ESPN's events to our games by the pair of team names.
next_check	When the scores job next needs to look, given the week's kickoffs.

supercontest.core.scores.KICKOFF_WINDOW_MINUTES = 30

Minutes before and after a kickoff that scores are fetched regardless of status: is_around_kickoff()’s window.

supercontest.core.scores.MAX_IDLE = datetime.timedelta(seconds=21600)

The longest the job stays idle without looking at the database again. Lines for a new week, or a moved kickoff, are seen within this, and both land days before the game. Far longer than Aurora’s hour-long pause timer.

supercontest.core.scores.PERIOD_ABBVS = {1: '1ST', 2: '2ND', 3: '3RD', 4: '4TH'}

Maps the quarter reported by ESPN to the matching espn_abbv in the statuses table.

async supercontest.core.scores.commit_scores(session: AsyncSession, verify: bool = True, on_final: Callable[[], Awaitable[None]] | None = None) → bool

Wrapper for all score committing functionality.

The logic for is-offseason and is-score-day is checked here, since that’s fundamental to all cases of scoring. The other case of “did the user request an old week/season” is handled in the view logic, naturally.

Parameters:

• session – The session to read through.

• verify – Whether or not to check if there’s an active game, skipping if not.

• on_final – Awaited once if this run finished any game – the caller’s hook for what a final changes, such as the all-time table’s cache.

Returns:

Whether or not scores were committed.

async supercontest.core.scores.fetch_scores_json(sbsc_games: list[Game], season: int | None, week: int | None) → tuple[list[Game], list[ScoresFetch]]

Hits the ESPN scoreboard JSON API for live score updates and the time status of the game.

This returns the team nickname (eg "Seahawks") directly, which maps one-to-one onto teams.name. So there is no city lookup, and no need to disambiguate the two Los Angeles teams.

Parameters:

• sbsc_games – The Game objects of the current week, to match fetched scores against.

• season – The current season, or None outside one.

• week – The current week, or None outside one.

Returns:

The SBSC Game objects and ESPN score objects, in the same order.

async supercontest.core.scores.get_scoreboard(season: int | None, week: int | None) → list[dict[str, Any]]

Reads ESPN’s scoreboard.

Parameters:

• season – The season to pin the request to, or None for ESPN’s own default.

• week – The week to pin the request to, or None for ESPN’s own default.

Returns:

Its events.

supercontest.core.scores.is_idle() → bool

Whether the scores job can answer “nothing to do” without the database.

Returns:

True until the next check this process scheduled.

supercontest.core.scores.match_scoreboard(events: list[dict[str, Any]], sbsc_games: list[Game]) → tuple[list[Game], list[ScoresFetch]]

Matches ESPN’s events to our games by the pair of team names.

Parameters:

• events – ESPN’s scoreboard events.

• sbsc_games – The Game objects of the current week.

Returns:

The SBSC Game objects and ESPN score objects, in the same order.

supercontest.core.scores.next_check(kickoffs: list[datetime], now: datetime) → datetime

When the scores job next needs to look, given the week’s kickoffs.

The start of the next kickoff’s window, or MAX_IDLE from now if that is later or there is none (the week is over, or the offseason).

Parameters:

• kickoffs – The week’s kickoff instants.

• now – The current instant.

Returns:

The instant to look again.