animedex.utils.timezone

Timezone parsing helpers shared by aggregate commands and renderers.

The CLI accepts fixed offsets, IANA names, local time, and the broader set of timezone strings supported by dateutil.tz. Keeping this logic in one module avoids each command growing a slightly different timezone parser.

TimezoneResolution

class animedex.utils.timezone.TimezoneResolution(tzinfo: tzinfo, label: str)[source]

Bases: object

Resolved timezone value and display label.

Variables:

tzinfo (datetime.tzinfo) – Concrete timezone object used for datetime math.
label (str) – Stable human-readable label carried into rendered aggregate results.

tzinfo: tzinfo

label: str

now_local

animedex.utils.timezone.now_local() → datetime[source]

Return the current local aware datetime.

Returns:: Local aware datetime.
Return type:: datetime.datetime

timezone_label

animedex.utils.timezone.timezone_label(tz: tzinfo, *, sample: datetime | None = None) → str[source]

Return a stable display label for a timezone object.

Parameters:

tz (datetime.tzinfo) – Timezone object.
sample (datetime.datetime or None) – Optional datetime used for offset/name sampling.

Returns:

IANA key, "UTC", fixed offset, or timezone name.

Return type:

str

parse_timezone

animedex.utils.timezone.parse_timezone(value: str | None, *, local_now: datetime | None = None) → TimezoneResolution[source]

Parse a user-facing timezone string.

Accepted forms include local, UTC/Z/GMT, IANA names such as Asia/Tokyo, fixed offsets such as +08:00 or +8, prefixed offsets such as UTC+8 or GMT-05:00, and any additional timezone syntax understood by dateutil.tz.gettz().

Parameters:

value (str or None) – User-provided timezone value. None means local.
local_now (datetime.datetime or None) – Optional local datetime override for tests.

Returns:

Resolved timezone and display label.

Return type:

TimezoneResolution

Raises:

ValueError – If the value cannot be parsed.

selftest

animedex.utils.timezone.selftest() → bool[source]

Smoke-test broad timezone parsing.

Returns:: True when local, IANA, fixed-offset, and dateutil TZ string parsing all work.
Return type:: bool