aeat.core.time._clock module

Canonical wall-clock helpers for the AEAT domain.

A single, testable entry-point for obtaining the current UTC time. Call-sites must import now() from aeat.core.time rather than inlining datetime.now(tz=UTC) directly, so the production clock can be traced and call-sites stay uniform.

Deterministic-output seam

now() consults a context-variable frozen instant so a replay or golden-capture scope can make every call site that routes through it deterministic. The seam is DEFAULT-OFF: production never enters frozen_clock(), so now() returns real datetime.now(tz=UTC) with zero behaviour change. The seam is context-var scoped — never process-global — so it cannot leak across tasks the way freezegun / time_machine global freezing does, the pattern banned in live-marked tests by aeat-tests.conftest.BANNED_LIVE_IMPORTS. frozen_clock() additionally refuses to activate while the pytest live-read opt-in (aeat.core.config.Settings.live_tests_enabled) is set, keeping live-marked tests on real wall-clock plus explicit clock= injection exactly as today.

now()

Return the current UTC-aware datetime, or the frozen instant when the seam is active.

In production _FROZEN_INSTANT is never set, so this returns real wall-clock datetime.now(tz=UTC) with zero behaviour change. Under a frozen_clock() scope it returns the frozen instant, making every call site that routes through this function deterministic for the duration of the scope.

Return type:

datetime

Returns:

A datetime.datetime instance with datetime.UTC as its tzinfo.

clock_is_frozen()

Return whether a frozen_clock() scope is active for the current context.

Return type:

bool

frozen_clock(instant)

Freeze now() to instant for the duration of the scope.

This is the replay/golden-capture-only seam behind the deterministic-output substrate. It is DEFAULT-OFF (production never enters it) and context-var scoped (never process-global), and it refuses to activate under the pytest live-read opt-in.

Parameters:

instant (datetime) – The UTC-aware instant now() returns while active.

Yields:

The frozen instant.

Raises:

CoreValidationError – When instant is naive or not UTC, or when the pytest live-read opt-in is enabled.

Return type:

Iterator[datetime]