AvailableAt

class openstef_core.types.AvailableAt(day_offset: int, time_of_day: time, *, tzinfo: BaseTzInfo | timezone | None = None)

Bases: PydanticStringPrimitive

Represents a time point available relative to a reference day.

Uses a specialized string format DnTHHMM where:

• n is the day offset (negative or zero)

• HHMM is the time of day

An optional timezone suffix [Region/City] (RFC 9557 bracket notation) makes the availability time timezone-aware. Both pytz and stdlib datetime.timezone objects are accepted; they round-trip through the IANA name via str(tz) / pytz.timezone(name).

For example, D-1T0600[Europe/Amsterdam] means “6:00 Europe/Amsterdam on the previous day”. The legacy DnTHH:MM format (with colon) is also accepted by from_string().

Example

>>> from datetime import time
>>> import pytz
>>> tz_at = AvailableAt(day_offset=-1, time_of_day=time(6, 0), tzinfo=pytz.timezone('Europe/Amsterdam'))
>>> str(tz_at)
'D-1T0600[Europe/Amsterdam]'
>>> at = AvailableAt.from_string("D-1T0600")
>>> at.day_offset, at.time_of_day
(-1, datetime.time(6, 0))

Parameters:

• day_offset (int)

• time_of_day (time)

• tzinfo (BaseTzInfo | timezone | None)

__init__(day_offset: int, time_of_day: time, *, tzinfo: BaseTzInfo | timezone | None = None)

Initialise with a day offset, time of day, and optional timezone.

Parameters:

• day_offset (int) – Day offset from the reference day (must be ≤ 0). -1 means “the previous day”, 0 means “the same day”.

• time_of_day (time) – Clock time when data becomes available.

• tzinfo (BaseTzInfo | timezone | None) – Optional timezone for the availability time (e.g. pytz.timezone("Europe/Amsterdam"), pytz.UTC, or datetime.timezone.utc).

• day_offset

• time_of_day

• tzinfo

Raises:

ValueError – If day_offset is positive.

__str__() → str

Converts to string in DnTHHMM or DnTHHMM[tz] format.

Return type:

str

Returns:

String representation, with optional [timezone] suffix.

classmethod from_string(s: str) → Self

Creates an instance from a string in DnTHHMM[tz] format.

Accepts an optional [Region/City] timezone suffix. The legacy colon format DnTHH:MM is also accepted.

Parameters:

• s (str) – String to parse.

• s

Returns:

AvailableAt instance parsed from the string.

Raises:

ValueError – If the string format is invalid or day offset is positive.

Return type:

Self

apply(date: datetime) → datetime

Apply this availability offset to a reference date.

The day offset is interpreted in self.tzinfo (falls back to date.tzinfo), so “D-1” means “the previous calendar day in that timezone”. The time-of-day is also placed in that timezone. The result is returned in the reference date’s timezone, or naive when the reference date is naive.

This matches the vectorised apply_index() semantics, which converts to self.tzinfo before extracting the calendar day.

Parameters:

• date (datetime) – The reference date to apply the availability offset to.

• date

Returns:

The datetime when data is available, in the reference date’s timezone (or naive when the reference date is naive).

Return type:

datetime

apply_index(index: DatetimeIndex) → DatetimeIndex

Vectorized version of apply() for a pandas DatetimeIndex.

Same timezone logic as apply(): the time-of-day is interpreted in self.tzinfo (falls back to index.tz), then converted back to the index’s timezone.

Parameters:

• index (DatetimeIndex) – DatetimeIndex of reference dates.

• index

Returns:

DatetimeIndex of cutoff timestamps, in the same timezone as index.

Return type:

DatetimeIndex