README.md

Clock Pattern Documentation

Clock Pattern makes time an explicit dependency. Application code depends on Clock, production wiring chooses a real clock, and tests choose deterministic clocks.

Use this page as the documentation hub:

Guide	Purpose
Usage Guide	How to inject clocks into application services and choose now() or today().
Timezone Guide	UTC defaults, SystemClock timezone configuration, and date-boundary guidance.
Testing Guide	How to use FixedClock and MockClock for deterministic tests.

Public API

Production imports:

from clock_pattern import Clock, SystemClock, UtcClock

Testing imports:

from clock_pattern.clocks.testing import FixedClock, MockClock

Clock Contract

Every clock exposes two methods:

Method	Return type	Meaning
now()	datetime	Current or prepared datetime for the clock implementation.
today()	date	Current or prepared date for the clock implementation.

SystemClock and UtcClock read real system time. FixedClock and MockClock are test utilities and should usually stay in test code.

Recommended Flow

1. Accept Clock in domain services, application services, or use cases.
2. Wire UtcClock or SystemClock at the application boundary.
3. Use FixedClock when a test needs a stable instant.
4. Use MockClock when a test also needs to assert that time was requested.
5. Keep timezone choices explicit, especially for date-only rules around midnight.