supercontest.util.timing

Time, date, timezone, conversion - all timing related utilities.

Module Attributes

`PACIFIC`	The league's zone.
`WESTGATE_FORMATS`	How Westgate prints a kickoff: `"THURSDAY, NOVEMBER 9, 2017 5:25 PM"`.

Functions

`convert_utc_to_pt`	I have timezone explicitly set True in sqlalchemy, a session's queries and `psql` queries both return UTC datetimes.
`convert_westgate_datetime_to_utc`	Properly formats the strings for datetime in the database into python datetime objects, including tzinfo.
`get_dow`	Takes a datetime (like the `game.datetime` col from the db) and returns the day of the week.
`get_utc_now`	Now, aware in UTC.
`hours_since`	Calculates the number of hours since a certain time.
`is_around_kickoff`	Checks if you are in a window around a kickoff time (set by lines), before or after, to force the score fetch.
`localize_pacific`	A Pacific wall-clock time made aware, refusing the two DST edge cases.
`pacific_midnight`	The instant a Pacific calendar day begins, in UTC.

Exceptions

`AmbiguousTimeError`	A wall-clock time that happens twice, on the day DST ends.
`NonExistentTimeError`	A wall-clock time that never happens, on the day DST starts.

exception supercontest.util.timing.AmbiguousTimeError

Bases: ValueError

A wall-clock time that happens twice, on the day DST ends.

exception supercontest.util.timing.NonExistentTimeError

Bases: ValueError

A wall-clock time that never happens, on the day DST starts.

supercontest.util.timing.PACIFIC = zoneinfo.ZoneInfo(key='America/Los_Angeles'): The league’s zone. Westgate prints Pacific wall-clock times (Vegas and LA are both Pacific and both observe DST), and pages display in it. Named here once so nothing depends on the container’s TZ.

supercontest.util.timing.WESTGATE_FORMATS = ('%A, %B %d, %Y %I:%M %p', '%A, %b %d, %Y %I:%M %p'): How Westgate prints a kickoff: "THURSDAY, NOVEMBER 9, 2017 5:25 PM". The month is sometimes abbreviated, so both forms are tried.

supercontest.util.timing.convert_utc_to_pt(datetime_obj: datetime) → datetime

I have timezone explicitly set True in sqlalchemy, a session’s queries and psql queries both return UTC datetimes. This function converts them to pacific time.

Parameters:: datetime_obj – A datetime object aware in the utc timezone.
Returns:: A datetime object aware in the pacific timezone.

supercontest.util.timing.convert_westgate_datetime_to_utc(date_str: str) → datetime

Properly formats the strings for datetime in the database into python datetime objects, including tzinfo.

Westgate returns a date string like this: "THURSDAY, NOVEMBER 9, 2017 5:25 PM". It is in the pacific timezone.

Parameters:: date_str – The westgate datetime string (pacific).
Returns:: The python standard datetime object (in UTC) for that westgate string.

supercontest.util.timing.get_dow(datetime_obj: datetime) → str

Takes a datetime (like the game.datetime col from the db) and returns the day of the week. Specifically ignores year, week, etc - this just categorizes along weekday. Times are cast to PT. This is obviously for statistical analysis (bucketing).

Parameters:: datetime_obj – A datetime object.
Returns:: Eg "Sun".

supercontest.util.timing.get_utc_now() → datetime

Now, aware in UTC. Every timestamp in postgres is stored as UTC, so every comparison against one starts here.

Returns:: The datetime obj for NOW, aware in the UTC timezone.

supercontest.util.timing.hours_since(start: datetime, now: datetime | None = None) → float

Calculates the number of hours since a certain time.

Parameters:

start – Datetime, aware in UTC timezone.
now – The instant to measure to; the clock when omitted.

Returns:

Number of hours since the start time.

supercontest.util.timing.is_around_kickoff(datetimes: list[datetime], within: int = 30, now: datetime | None = None) → bool

Checks if you are in a window around a kickoff time (set by lines), before or after, to force the score fetch.

Parameters:

datetimes – The datetime cols (just vals) of the games table.
within – Number of minutes (before AND after) around kickoff to check within.
now – The instant to check; the clock when omitted.

Returns:

True if around kickoff (fetch scores), False if not around kickoff (don’t fetch).

supercontest.util.timing.localize_pacific(naive: datetime) → datetime

A Pacific wall-clock time made aware, refusing the two DST edge cases.

zoneinfo silently resolves both by fold; a kickoff there is a data error, and guessing would put the game an hour off.

Parameters:

naive – The wall-clock time.

Returns:

It, aware in PACIFIC.

Raises:

AmbiguousTimeError – If it happens twice (fall back).
NonExistentTimeError – If it never happens (spring forward).

supercontest.util.timing.pacific_midnight(day: date) → datetime

The instant a Pacific calendar day begins, in UTC.

Midnight is never in a DST gap or overlap in this zone (the shifts happen at 2am), so there is exactly one.

Parameters:: day – The day.
Returns:: Its first instant, aware in UTC.