aeat.core.time._utc module¶

Canonical UTC datetime helpers.

Two semantics exist across the codebase for handling naive datetimes:

coerce_utc_aware() — coerce a naive datetime to UTC-aware by attaching UTC. Used where the source produces naive datetimes (e.g. PKCS#12 certificate timestamps).
validate_utc_aware() — reject naive datetimes or non-UTC datetimes with CoreValidationError. Used at persistence and model boundaries where a naive datetime indicates a programming error.

parse_iso_datetime() is deliberately policy-neutral: it normalises the Z suffix and returns the parsed datetime, leaving callers to choose coerce_utc_aware() or validate_utc_aware().

parse_iso_datetime(raw)[source]¶

Parse an ISO-8601 datetime string, normalising a trailing Z to +00:00.

datetime.fromisoformat() historically rejects the Z UTC suffix; this normalises it first so UTC-suffixed timestamps parse. The result may be naive or aware depending on the input — pass it through validate_utc_aware() or coerce_utc_aware() when an aware value is required.

Return type:: datetime
Parameters:: raw (str)

coerce_utc_aware(value)[source]¶

Return a UTC-aware datetime, coercing a naive one if necessary.

Naive datetimes have datetime.UTC attached. Timezone-aware datetimes whose offset differs from UTC are converted via datetime.astimezone().

Parameters:: value (datetime) – Any datetime instance, naive or aware.
Return type:: datetime
Returns:: A UTC-aware datetime instance.

validate_utc_aware(value)[source]¶

Return value unchanged if it is a UTC-aware datetime.

Raises aeat.core.errors.CoreValidationError when value is naive (no tzinfo) or when its UTC offset is not zero (i.e. not UTC).

Parameters:: value (datetime) – The datetime to validate.
Return type:: datetime
Returns:: value unchanged.
Raises:: CoreValidationError – When value is naive or not in UTC.