data_updater_v2.data_clients.times

times.py — the time helpers the runner and RawResponse need, on the standard library.

Taken from nc-feeds, where the runner speaks the package’s own Time contract; here the same moves are done with datetime alone. A walk speaks ONE unit end to end (TimeUnit): a "date" value is a datetime.date; "datetime", "epoch" and "epoch_ms" values are timezone-aware datetime.datetime. Arithmetic on instants is done in UTC, so a shift is exact elapsed time whatever wall clock the vendor writes in.

parse    a vendor's value, in the declared unit and zone
render   back into the vendor's unit for a request parameter
shift_by forward or back by a span
coerce   any date-like value, unit unknown (a ``RawResponse`` coverage edge)
day      the calendar day of a value
iso      one ISO string, for messages

Functions

coerce

coerce(value: Any) -> TimeValue

A date-like value with no declared unit: a date or an instant as given, or ISO text — a bare YYYY-MM-DD is a date, anything longer an instant (UTC when naive).

day

day(value: TimeValue) -> dt.date

The calendar day of a value (an instant’s own wall-clock day).

iso

iso(value: TimeValue) -> str

parse

parse(value: Any, unit: TimeUnit, zone: str | None = None) -> TimeValue

A vendor’s time value in the declared unit: a date for "date", an aware instant otherwise. Epoch units read numbers (and digit strings) as seconds or milliseconds.

render

render(value: TimeValue, unit: TimeUnit, zone: str | None = None) -> Any

A time value back into the vendor’s unit, for a request parameter.

shift_by

shift_by(value: TimeValue, unit: TimeUnit, delta: dt.timedelta) -> TimeValue

Forward or back by delta: calendar days for dates, exact elapsed time for instants.