clock-pattern 0.9.0__tar.gz → 0.11.0__tar.gz

{clock_pattern-0.9.0 → clock_pattern-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: clock-pattern
-Version: 0.9.0
+Version: 0.11.0
 Summary: The Clock Pattern is a Python package that turns time into an injectable dependency.
 Project-URL: Homepage, https://github.com/adriamontoto/clock-pattern
 Project-URL: Repository, https://github.com/adriamontoto/clock-pattern
@@ -20,7 +20,8 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
-Requires-Dist: value-object-pattern>=1.31.0
+Requires-Dist: typing-extensions>=4.4.0; python_version < '3.12'
+Requires-Dist: value-object-pattern>=1.36.0
 Description-Content-Type: text/markdown
 
 <a name="readme-top"></a>
@@ -43,9 +44,6 @@ Description-Content-Type: text/markdown
     <a href="https://pepy.tech/projects/clock-pattern" target="_blank">
         <img src="https://static.pepy.tech/badge/clock-pattern/month" alt="Package Downloads">
     </a>
-    <a href="https://deepwiki.com/adriamontoto/clock-pattern" target="_blank">
-        <img src="https://img.shields.io/badge/DeepWiki-adriamontoto%2Fclock--pattern-blue.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACwAAAAyCAYAAAAnWDnqAAAAAXNSR0IArs4c6QAAA05JREFUaEPtmUtyEzEQhtWTQyQLHNak2AB7ZnyXZMEjXMGeK/AIi+QuHrMnbChYY7MIh8g01fJoopFb0uhhEqqcbWTp06/uv1saEDv4O3n3dV60RfP947Mm9/SQc0ICFQgzfc4CYZoTPAswgSJCCUJUnAAoRHOAUOcATwbmVLWdGoH//PB8mnKqScAhsD0kYP3j/Yt5LPQe2KvcXmGvRHcDnpxfL2zOYJ1mFwrryWTz0advv1Ut4CJgf5uhDuDj5eUcAUoahrdY/56ebRWeraTjMt/00Sh3UDtjgHtQNHwcRGOC98BJEAEymycmYcWwOprTgcB6VZ5JK5TAJ+fXGLBm3FDAmn6oPPjR4rKCAoJCal2eAiQp2x0vxTPB3ALO2CRkwmDy5WohzBDwSEFKRwPbknEggCPB/imwrycgxX2NzoMCHhPkDwqYMr9tRcP5qNrMZHkVnOjRMWwLCcr8ohBVb1OMjxLwGCvjTikrsBOiA6fNyCrm8V1rP93iVPpwaE+gO0SsWmPiXB+jikdf6SizrT5qKasx5j8ABbHpFTx+vFXp9EnYQmLx02h1QTTrl6eDqxLnGjporxl3NL3agEvXdT0WmEost648sQOYAeJS9Q7bfUVoMGnjo4AZdUMQku50McDcMWcBPvr0SzbTAFDfvJqwLzgxwATnCgnp4wDl6Aa+Ax283gghmj+vj7feE2KBBRMW3FzOpLOADl0Isb5587h/U4gGvkt5v60Z1VLG8BhYjbzRwyQZemwAd6cCR5/XFWLYZRIMpX39AR0tjaGGiGzLVyhse5C9RKC6ai42ppWPKiBagOvaYk8lO7DajerabOZP46Lby5wKjw1HCRx7p9sVMOWGzb/vA1hwiWc6jm3MvQDTogQkiqIhJV0nBQBTU+3okKCFDy9WwferkHjtxib7t3xIUQtHxnIwtx4mpg26/HfwVNVDb4oI9RHmx5WGelRVlrtiw43zboCLaxv46AZeB3IlTkwouebTr1y2NjSpHz68WNFjHvupy3q8TFn3Hos2IAk4Ju5dCo8B3wP7VPr/FGaKiG+T+v+TQqIrOqMTL1VdWV1DdmcbO8KXBz6esmYWYKPwDL5b5FA1a0hwapHiom0r/cKaoqr+27/XcrS5UwSMbQAAAABJRU5ErkJggg==" alt="Project Documentation">
-    </a>
 </p>
 
 The **Clock Pattern** is a Python 🐍 package that turns time into an injectable dependency 🧩. Instead of scattering
@@ -60,7 +58,7 @@ implementations without touching business rules.
 - [📚 Documentation](#documentation)
 - [⚡ Quick Start](#quick-start)
 - [🧩 Why Inject a Clock?](#why-inject-a-clock)
-- [📚 Available Clocks](#available-clocks)
+- [📚 Public API](#public-api)
 - [🌍 Timezone Behavior](#timezone-behavior)
 - [🧪 Testing Time-Sensitive Code](#testing-time-sensitive-code)
 - [🎄 Real-Life Case: Christmas Detector Service](#real-life-case-christmas-detector-service)
@@ -103,10 +101,9 @@ The root README is the entry point. Deeper guides live in this repository and ar
 - [`docs/README.md`](docs/README.md): Documentation hub.
 - [`docs/usage/README.md`](docs/usage/README.md): Core usage patterns and service composition.
 - [`docs/timezones/README.md`](docs/timezones/README.md): Timezone behavior, UTC defaults, and date-boundary guidance.
+- [`docs/examples/README.md`](docs/examples/README.md): Token expiration, cache TTL, polling, and retry recipes.
 - [`docs/testing/README.md`](docs/testing/README.md): `FixedClock`, `MockClock`, and deterministic test patterns.
 
-This [project's DeepWiki documentation](https://deepwiki.com/adriamontoto/clock-pattern) is also available for generated
-repository navigation.
 
 <p align="right">
     <a href="#readme-top">🔼 Back to top</a>
@@ -168,32 +165,108 @@ The package exposes two methods:
 
 | Method | Returns | Typical use |
 | --- | --- | --- |
-| `now()` | `datetime` | Timestamps, expiration windows, audit fields, elapsed-time calculations. |
+| `now()` | `datetime` | Timestamps, expiration windows, and audit fields. |
 | `today()` | `date` | Calendar rules, billing days, holiday checks, date-only decisions. |
 
+Clock Pattern also includes injectable helpers for elapsed-duration behavior: monotonic clocks, sleepers, stopwatches,
+deadlines, pollers, and retriers. These use monotonic seconds instead of wall-clock datetimes so system clock changes do
+not affect timeout or retry behavior.
+
 <p align="right">
     <a href="#readme-top">🔼 Back to top</a>
 </p><br><br>
 
-<a name="available-clocks"></a>
+<a name="public-api"></a>
+
+## 📚 Public API
 
-## 📚 Available Clocks
+Use the top-level package for contracts and production helpers, and each feature's `testing` package for test doubles.
 
-The package offers several clock implementations to suit different needs:
+### Wall-Clock API
 
-| Clock | Import path | Purpose |
+| API | Import path | Purpose |
 | --- | --- | --- |
 | [`Clock`](https://github.com/adriamontoto/clock-pattern/blob/master/clock_pattern/clocks/models/clock.py) | `from clock_pattern import Clock` | Abstract contract for code that needs `now()` or `today()`. |
 | [`SystemClock`](https://github.com/adriamontoto/clock-pattern/blob/master/clock_pattern/clocks/system_clock.py) | `from clock_pattern import SystemClock` | Production clock backed by system time in a configured timezone. |
 | [`UtcClock`](https://github.com/adriamontoto/clock-pattern/blob/master/clock_pattern/clocks/utc_clock.py) | `from clock_pattern import UtcClock` | Production clock fixed to UTC. |
+
+### Elapsed-Time API
+
+| API | Import path | Purpose |
+| --- | --- | --- |
 | `MonotonicClock` | `from clock_pattern import MonotonicClock` | Abstract contract for elapsed-time sources. |
 | `SystemMonotonicClock` | `from clock_pattern import SystemMonotonicClock` | Production monotonic clock for elapsed-time measurement. |
+| `Sleeper` / `SleeperAsync` | `from clock_pattern import Sleeper, SleeperAsync` | Abstract contracts for injectable sync and async sleeping. |
 | `SystemSleeper` / `SystemSleeperAsync` | `from clock_pattern import SystemSleeper, SystemSleeperAsync` | Injectable sync and async sleeping. |
 | `Stopwatch` | `from clock_pattern import Stopwatch` | Measure elapsed seconds with `.start()`, `.end()`, or a context manager. |
-| [`FixedClock`](https://github.com/adriamontoto/clock-pattern/blob/master/clock_pattern/clocks/testing/fixed_clock.py) | `from clock_pattern.clocks.testing import FixedClock` | Test clock that always returns the same datetime and derived date. |
+| `Deadline` | `from clock_pattern import Deadline` | Abstract contract for injectable deadline state. |
+| `SystemDeadline` | `from clock_pattern import SystemDeadline` | Monotonic deadline with an interrupting Unix main-thread context. |
+| `TimeoutExpiredError` | `from clock_pattern import TimeoutExpiredError` | Error raised when a deadline or poll timeout expires. |
+| `Poller` / `PollerAsync` | `from clock_pattern import Poller, PollerAsync` | Abstract contracts for condition polling. |
+| `SystemPoller` / `SystemPollerAsync` | `from clock_pattern import SystemPoller, SystemPollerAsync` | Production polling implementations. |
+| `Retrier` / `RetrierAsync` | `from clock_pattern import Retrier, RetrierAsync` | Abstract contracts for retrying operations. |
+| `SystemRetrier` / `SystemRetrierAsync` | `from clock_pattern import SystemRetrier, SystemRetrierAsync` | Production retry implementations. |
+
+### Test Doubles
+
+| API | Import path | Purpose |
+| --- | --- | --- |
+| [`FixedClock`](https://github.com/adriamontoto/clock-pattern/blob/master/clock_pattern/clocks/testing/fixed_clock.py) | `from clock_pattern.clocks.testing import FixedClock` | Test clock that stays fixed until explicitly set or advanced. |
 | [`MockClock`](https://github.com/adriamontoto/clock-pattern/blob/master/clock_pattern/clocks/testing/mock_clock.py) | `from clock_pattern.clocks.testing import MockClock` | Test clock with prepared return values and call assertions. |
+| `MockMonotonicClock` | `from clock_pattern.monotonic_clocks.testing import MockMonotonicClock` | Controllable elapsed-time source with call assertions. |
+| `MockDeadline` | `from clock_pattern.deadlines.testing import MockDeadline` | Controllable deadline with expiry call assertions. |
+| `MockSleeper` / `MockSleeperAsync` | `from clock_pattern.sleepers.testing import MockSleeper, MockSleeperAsync` | Sleeping test doubles that advance a mock monotonic clock. |
+| `MockPoller` / `MockPollerAsync` | `from clock_pattern.pollers.testing import MockPoller, MockPollerAsync` | Polling test doubles with call assertions. |
+| `MockRetrier` / `MockRetrierAsync` | `from clock_pattern.retriers.testing import MockRetrier, MockRetrierAsync` | Retry test doubles with prepared results. |
+
+```python
+from clock_pattern import Stopwatch, SystemMonotonicClock, SystemSleeper
+
+monotonic_clock = SystemMonotonicClock()
+sleeper = SystemSleeper(monotonic_clock=monotonic_clock)
 
-Use the top-level package for production clocks and `clock_pattern.clocks.testing` for test-only clocks.
+with Stopwatch(monotonic_clock=monotonic_clock) as stopwatch:
+    pass
+
+with sleeper.minimum_duration(seconds=0.001):
+    pass
+```
+
+The deadline context requires a Unix main thread:
+
+```python unix
+from clock_pattern import SystemDeadline, SystemMonotonicClock
+
+monotonic_clock = SystemMonotonicClock()
+with SystemDeadline(seconds=5, monotonic_clock=monotonic_clock):
+    pass
+```
+
+Continue with polling and retries on all platforms:
+
+```python
+from clock_pattern import SystemMonotonicClock, SystemPoller, SystemRetrier, SystemSleeper
+
+monotonic_clock = SystemMonotonicClock()
+sleeper = SystemSleeper(monotonic_clock=monotonic_clock)
+poller = SystemPoller(sleeper=sleeper, monotonic_clock=monotonic_clock)
+
+poller.poll_until(condition=lambda: True, timeout_seconds=5, interval_seconds=0.1)
+SystemRetrier(sleeper=sleeper).retry(
+    operation=lambda: 'done',
+    attempts=3,
+    delay_seconds=0.2,
+    max_delay_seconds=2,
+    backoff=2,
+    jitter=True,
+)
+```
+
+`SystemDeadline` context managers use `SIGALRM` to interrupt Python code and interruptible system calls. Context use is
+limited to Unix main-thread execution, cannot be nested or share an existing alarm, and may be delayed by C code that
+does not return control to the Python interpreter. Deadline properties and `raise_if_expired()` remain cooperative when
+used outside a context manager. `TimeoutExpiredError.elapsed_seconds` exposes the measured elapsed duration reported by
+either timeout path.
 
 <p align="right">
     <a href="#readme-top">🔼 Back to top</a>
@@ -203,8 +276,8 @@ Use the top-level package for production clocks and `clock_pattern.clocks.testin
 
 ## 🌍 Timezone Behavior
 
-`SystemClock` accepts either an IANA timezone string or a `tzinfo` instance. It stores the timezone with `ZoneInfo` and
-uses it for both `now()` and `today()`.
+`SystemClock` accepts either an IANA timezone string or a `tzinfo` instance. It converts strings to `ZoneInfo`, preserves
+`tzinfo` instances directly, and uses the resulting timezone for both `now()` and `today()`.
 
 ```python
 from datetime import UTC
@@ -262,6 +335,8 @@ clock.assert_today_method_was_called_once()
 clock.assert_now_method_was_not_called()
 ```
 
+`FixedClock.advance(delta=timedelta(...))` moves time forward explicitly; `set(instant=...)` replaces it, including backward jumps. Both keep `now()` and `today()` consistent.
+
 More testing recipes are available in [`docs/testing/README.md`](docs/testing/README.md).
 
 <p align="right">

{clock_pattern-0.9.0 → clock_pattern-0.11.0}/README.md

@@ -18,9 +18,6 @@
     <a href="https://pepy.tech/projects/clock-pattern" target="_blank">
         <img src="https://static.pepy.tech/badge/clock-pattern/month" alt="Package Downloads">
     </a>
-    <a href="https://deepwiki.com/adriamontoto/clock-pattern" target="_blank">
-        <img src="https://img.shields.io/badge/DeepWiki-adriamontoto%2Fclock--pattern-blue.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACwAAAAyCAYAAAAnWDnqAAAAAXNSR0IArs4c6QAAA05JREFUaEPtmUtyEzEQhtWTQyQLHNak2AB7ZnyXZMEjXMGeK/AIi+QuHrMnbChYY7MIh8g01fJoopFb0uhhEqqcbWTp06/uv1saEDv4O3n3dV60RfP947Mm9/SQc0ICFQgzfc4CYZoTPAswgSJCCUJUnAAoRHOAUOcATwbmVLWdGoH//PB8mnKqScAhsD0kYP3j/Yt5LPQe2KvcXmGvRHcDnpxfL2zOYJ1mFwrryWTz0advv1Ut4CJgf5uhDuDj5eUcAUoahrdY/56ebRWeraTjMt/00Sh3UDtjgHtQNHwcRGOC98BJEAEymycmYcWwOprTgcB6VZ5JK5TAJ+fXGLBm3FDAmn6oPPjR4rKCAoJCal2eAiQp2x0vxTPB3ALO2CRkwmDy5WohzBDwSEFKRwPbknEggCPB/imwrycgxX2NzoMCHhPkDwqYMr9tRcP5qNrMZHkVnOjRMWwLCcr8ohBVb1OMjxLwGCvjTikrsBOiA6fNyCrm8V1rP93iVPpwaE+gO0SsWmPiXB+jikdf6SizrT5qKasx5j8ABbHpFTx+vFXp9EnYQmLx02h1QTTrl6eDqxLnGjporxl3NL3agEvXdT0WmEost648sQOYAeJS9Q7bfUVoMGnjo4AZdUMQku50McDcMWcBPvr0SzbTAFDfvJqwLzgxwATnCgnp4wDl6Aa+Ax283gghmj+vj7feE2KBBRMW3FzOpLOADl0Isb5587h/U4gGvkt5v60Z1VLG8BhYjbzRwyQZemwAd6cCR5/XFWLYZRIMpX39AR0tjaGGiGzLVyhse5C9RKC6ai42ppWPKiBagOvaYk8lO7DajerabOZP46Lby5wKjw1HCRx7p9sVMOWGzb/vA1hwiWc6jm3MvQDTogQkiqIhJV0nBQBTU+3okKCFDy9WwferkHjtxib7t3xIUQtHxnIwtx4mpg26/HfwVNVDb4oI9RHmx5WGelRVlrtiw43zboCLaxv46AZeB3IlTkwouebTr1y2NjSpHz68WNFjHvupy3q8TFn3Hos2IAk4Ju5dCo8B3wP7VPr/FGaKiG+T+v+TQqIrOqMTL1VdWV1DdmcbO8KXBz6esmYWYKPwDL5b5FA1a0hwapHiom0r/cKaoqr+27/XcrS5UwSMbQAAAABJRU5ErkJggg==" alt="Project Documentation">
-    </a>
 </p>
 
 The **Clock Pattern** is a Python 🐍 package that turns time into an injectable dependency 🧩. Instead of scattering
@@ -35,7 +32,7 @@ implementations without touching business rules.
 - [📚 Documentation](#documentation)
 - [⚡ Quick Start](#quick-start)
 - [🧩 Why Inject a Clock?](#why-inject-a-clock)
-- [📚 Available Clocks](#available-clocks)
+- [📚 Public API](#public-api)
 - [🌍 Timezone Behavior](#timezone-behavior)
 - [🧪 Testing Time-Sensitive Code](#testing-time-sensitive-code)
 - [🎄 Real-Life Case: Christmas Detector Service](#real-life-case-christmas-detector-service)
@@ -78,10 +75,9 @@ The root README is the entry point. Deeper guides live in this repository and ar
 - [`docs/README.md`](docs/README.md): Documentation hub.
 - [`docs/usage/README.md`](docs/usage/README.md): Core usage patterns and service composition.
 - [`docs/timezones/README.md`](docs/timezones/README.md): Timezone behavior, UTC defaults, and date-boundary guidance.
+- [`docs/examples/README.md`](docs/examples/README.md): Token expiration, cache TTL, polling, and retry recipes.
 - [`docs/testing/README.md`](docs/testing/README.md): `FixedClock`, `MockClock`, and deterministic test patterns.
 
-This [project's DeepWiki documentation](https://deepwiki.com/adriamontoto/clock-pattern) is also available for generated
-repository navigation.
 
 <p align="right">
     <a href="#readme-top">🔼 Back to top</a>
@@ -143,32 +139,108 @@ The package exposes two methods:
 
 | Method | Returns | Typical use |
 | --- | --- | --- |
-| `now()` | `datetime` | Timestamps, expiration windows, audit fields, elapsed-time calculations. |
+| `now()` | `datetime` | Timestamps, expiration windows, and audit fields. |
 | `today()` | `date` | Calendar rules, billing days, holiday checks, date-only decisions. |
 
+Clock Pattern also includes injectable helpers for elapsed-duration behavior: monotonic clocks, sleepers, stopwatches,
+deadlines, pollers, and retriers. These use monotonic seconds instead of wall-clock datetimes so system clock changes do
+not affect timeout or retry behavior.
+
 <p align="right">
     <a href="#readme-top">🔼 Back to top</a>
 </p><br><br>
 
-<a name="available-clocks"></a>
+<a name="public-api"></a>
+
+## 📚 Public API
 
-## 📚 Available Clocks
+Use the top-level package for contracts and production helpers, and each feature's `testing` package for test doubles.
 
-The package offers several clock implementations to suit different needs:
+### Wall-Clock API
 
-| Clock | Import path | Purpose |
+| API | Import path | Purpose |
 | --- | --- | --- |
 | [`Clock`](https://github.com/adriamontoto/clock-pattern/blob/master/clock_pattern/clocks/models/clock.py) | `from clock_pattern import Clock` | Abstract contract for code that needs `now()` or `today()`. |
 | [`SystemClock`](https://github.com/adriamontoto/clock-pattern/blob/master/clock_pattern/clocks/system_clock.py) | `from clock_pattern import SystemClock` | Production clock backed by system time in a configured timezone. |
 | [`UtcClock`](https://github.com/adriamontoto/clock-pattern/blob/master/clock_pattern/clocks/utc_clock.py) | `from clock_pattern import UtcClock` | Production clock fixed to UTC. |
+
+### Elapsed-Time API
+
+| API | Import path | Purpose |
+| --- | --- | --- |
 | `MonotonicClock` | `from clock_pattern import MonotonicClock` | Abstract contract for elapsed-time sources. |
 | `SystemMonotonicClock` | `from clock_pattern import SystemMonotonicClock` | Production monotonic clock for elapsed-time measurement. |
+| `Sleeper` / `SleeperAsync` | `from clock_pattern import Sleeper, SleeperAsync` | Abstract contracts for injectable sync and async sleeping. |
 | `SystemSleeper` / `SystemSleeperAsync` | `from clock_pattern import SystemSleeper, SystemSleeperAsync` | Injectable sync and async sleeping. |
 | `Stopwatch` | `from clock_pattern import Stopwatch` | Measure elapsed seconds with `.start()`, `.end()`, or a context manager. |
-| [`FixedClock`](https://github.com/adriamontoto/clock-pattern/blob/master/clock_pattern/clocks/testing/fixed_clock.py) | `from clock_pattern.clocks.testing import FixedClock` | Test clock that always returns the same datetime and derived date. |
+| `Deadline` | `from clock_pattern import Deadline` | Abstract contract for injectable deadline state. |
+| `SystemDeadline` | `from clock_pattern import SystemDeadline` | Monotonic deadline with an interrupting Unix main-thread context. |
+| `TimeoutExpiredError` | `from clock_pattern import TimeoutExpiredError` | Error raised when a deadline or poll timeout expires. |
+| `Poller` / `PollerAsync` | `from clock_pattern import Poller, PollerAsync` | Abstract contracts for condition polling. |
+| `SystemPoller` / `SystemPollerAsync` | `from clock_pattern import SystemPoller, SystemPollerAsync` | Production polling implementations. |
+| `Retrier` / `RetrierAsync` | `from clock_pattern import Retrier, RetrierAsync` | Abstract contracts for retrying operations. |
+| `SystemRetrier` / `SystemRetrierAsync` | `from clock_pattern import SystemRetrier, SystemRetrierAsync` | Production retry implementations. |
+
+### Test Doubles
+
+| API | Import path | Purpose |
+| --- | --- | --- |
+| [`FixedClock`](https://github.com/adriamontoto/clock-pattern/blob/master/clock_pattern/clocks/testing/fixed_clock.py) | `from clock_pattern.clocks.testing import FixedClock` | Test clock that stays fixed until explicitly set or advanced. |
 | [`MockClock`](https://github.com/adriamontoto/clock-pattern/blob/master/clock_pattern/clocks/testing/mock_clock.py) | `from clock_pattern.clocks.testing import MockClock` | Test clock with prepared return values and call assertions. |
+| `MockMonotonicClock` | `from clock_pattern.monotonic_clocks.testing import MockMonotonicClock` | Controllable elapsed-time source with call assertions. |
+| `MockDeadline` | `from clock_pattern.deadlines.testing import MockDeadline` | Controllable deadline with expiry call assertions. |
+| `MockSleeper` / `MockSleeperAsync` | `from clock_pattern.sleepers.testing import MockSleeper, MockSleeperAsync` | Sleeping test doubles that advance a mock monotonic clock. |
+| `MockPoller` / `MockPollerAsync` | `from clock_pattern.pollers.testing import MockPoller, MockPollerAsync` | Polling test doubles with call assertions. |
+| `MockRetrier` / `MockRetrierAsync` | `from clock_pattern.retriers.testing import MockRetrier, MockRetrierAsync` | Retry test doubles with prepared results. |
+
+```python
+from clock_pattern import Stopwatch, SystemMonotonicClock, SystemSleeper
+
+monotonic_clock = SystemMonotonicClock()
+sleeper = SystemSleeper(monotonic_clock=monotonic_clock)
 
-Use the top-level package for production clocks and `clock_pattern.clocks.testing` for test-only clocks.
+with Stopwatch(monotonic_clock=monotonic_clock) as stopwatch:
+    pass
+
+with sleeper.minimum_duration(seconds=0.001):
+    pass
+```
+
+The deadline context requires a Unix main thread:
+
+```python unix
+from clock_pattern import SystemDeadline, SystemMonotonicClock
+
+monotonic_clock = SystemMonotonicClock()
+with SystemDeadline(seconds=5, monotonic_clock=monotonic_clock):
+    pass
+```
+
+Continue with polling and retries on all platforms:
+
+```python
+from clock_pattern import SystemMonotonicClock, SystemPoller, SystemRetrier, SystemSleeper
+
+monotonic_clock = SystemMonotonicClock()
+sleeper = SystemSleeper(monotonic_clock=monotonic_clock)
+poller = SystemPoller(sleeper=sleeper, monotonic_clock=monotonic_clock)
+
+poller.poll_until(condition=lambda: True, timeout_seconds=5, interval_seconds=0.1)
+SystemRetrier(sleeper=sleeper).retry(
+    operation=lambda: 'done',
+    attempts=3,
+    delay_seconds=0.2,
+    max_delay_seconds=2,
+    backoff=2,
+    jitter=True,
+)
+```
+
+`SystemDeadline` context managers use `SIGALRM` to interrupt Python code and interruptible system calls. Context use is
+limited to Unix main-thread execution, cannot be nested or share an existing alarm, and may be delayed by C code that
+does not return control to the Python interpreter. Deadline properties and `raise_if_expired()` remain cooperative when
+used outside a context manager. `TimeoutExpiredError.elapsed_seconds` exposes the measured elapsed duration reported by
+either timeout path.
 
 <p align="right">
     <a href="#readme-top">🔼 Back to top</a>
@@ -178,8 +250,8 @@ Use the top-level package for production clocks and `clock_pattern.clocks.testin
 
 ## 🌍 Timezone Behavior
 
-`SystemClock` accepts either an IANA timezone string or a `tzinfo` instance. It stores the timezone with `ZoneInfo` and
-uses it for both `now()` and `today()`.
+`SystemClock` accepts either an IANA timezone string or a `tzinfo` instance. It converts strings to `ZoneInfo`, preserves
+`tzinfo` instances directly, and uses the resulting timezone for both `now()` and `today()`.
 
 ```python
 from datetime import UTC
@@ -237,6 +309,8 @@ clock.assert_today_method_was_called_once()
 clock.assert_now_method_was_not_called()
 ```
 
+`FixedClock.advance(delta=timedelta(...))` moves time forward explicitly; `set(instant=...)` replaces it, including backward jumps. Both keep `now()` and `today()` consistent.
+
 More testing recipes are available in [`docs/testing/README.md`](docs/testing/README.md).
 
 <p align="right">

clock_pattern-0.11.0/clock_pattern/__init__.py

@@ -0,0 +1,33 @@
+__version__ = '0.11.0'
+
+from .clocks import Clock, SystemClock, UtcClock
+from .deadlines import Deadline, SystemDeadline, TimeoutExpiredError
+from .monotonic_clocks import MonotonicClock, SystemMonotonicClock
+from .pollers import Poller, PollerAsync, SystemPoller, SystemPollerAsync
+from .retriers import Retrier, RetrierAsync, SystemRetrier, SystemRetrierAsync
+from .sleepers import Sleeper, SleeperAsync, SystemSleeper, SystemSleeperAsync
+from .stopwatches import Stopwatch
+
+__all__ = (
+    'Clock',
+    'Deadline',
+    'MonotonicClock',
+    'Poller',
+    'PollerAsync',
+    'Retrier',
+    'RetrierAsync',
+    'Sleeper',
+    'SleeperAsync',
+    'Stopwatch',
+    'SystemClock',
+    'SystemDeadline',
+    'SystemMonotonicClock',
+    'SystemPoller',
+    'SystemPollerAsync',
+    'SystemRetrier',
+    'SystemRetrierAsync',
+    'SystemSleeper',
+    'SystemSleeperAsync',
+    'TimeoutExpiredError',
+    'UtcClock',
+)

{clock_pattern-0.9.0 → clock_pattern-0.11.0}/clock_pattern/clocks/system_clock.py

@@ -61,7 +61,9 @@ class SystemClock(Clock):
         ```
         """
         if isinstance(timezone, tzinfo):
-            timezone = str(TimezoneValueObject(value=timezone, title='SystemClock', parameter='timezone'))
+            TimezoneValueObject(value=timezone, title='SystemClock', parameter='timezone')
+            self._timezone = timezone
+            return
 
         StringTimezoneValueObject(value=timezone, title='SystemClock', parameter='timezone')
 

{clock_pattern-0.9.0 → clock_pattern-0.11.0}/clock_pattern/clocks/testing/fixed_clock.py

@@ -1,5 +1,5 @@
 """
-Deterministic clock that always returns the same instant.
+Deterministic clock that stays fixed until explicitly adjusted.
 """
 
 from sys import version_info
@@ -9,7 +9,7 @@ if version_info >= (3, 12):
 else:
     from typing_extensions import override  # pragma: no cover
 
-from datetime import UTC, date, datetime
+from datetime import UTC, date, datetime, timedelta
 
 from value_object_pattern.usables.dates import DatetimeValueObject
 
@@ -21,7 +21,8 @@ class FixedClock(Clock):
     Return a fixed datetime and the date derived from it.
 
     `FixedClock` is useful when a test only needs stable time. Naive datetimes are normalized to UTC during
-    initialization. Use `MockClock` when a test also needs to assert whether `now()` or `today()` was called.
+    initialization and `set()`. Use `advance()` to simulate elapsed time, or `set()` to choose another instant.
+    Use `MockClock` when a test also needs to assert whether `now()` or `today()` was called.
 
     Example:
     ```python
@@ -45,7 +46,7 @@ class FixedClock(Clock):
         If `instant` is naive, UTC is added as its timezone. A timezone-aware `instant` is preserved as provided.
 
         Args:
-            instant: Datetime returned by `now()` and used by `today()`.
+            instant (datetime): Datetime returned by `now()` and used by `today()`.
 
         Raises:
             TypeError: If `instant` is not a datetime.
@@ -62,6 +63,30 @@ class FixedClock(Clock):
         # >>> 1999-01-01 00:00:00+00:00
         ```
         """
+        self.set(instant=instant)
+
+    def set(self, *, instant: datetime) -> None:
+        """
+        Set the instant returned by both clock methods, allowing forward or backward jumps.
+
+        Args:
+            instant (datetime): Datetime returned by `now()` and used by `today()`.
+
+        Raises:
+            TypeError: If `instant` is not a datetime.
+
+        Example:
+        ```python
+        from datetime import UTC, datetime
+
+        from clock_pattern.clocks.testing import FixedClock
+
+        clock = FixedClock(instant=datetime(2025, 2, 1, tzinfo=UTC))
+        clock.set(instant=datetime(2025, 1, 1, tzinfo=UTC))
+        print(clock.now())
+        # >>> 2025-01-01 00:00:00+00:00
+        ```
+        """
         DatetimeValueObject(value=instant, title='FixedClock', parameter='instant')
 
         if instant.tzinfo is None:
@@ -69,6 +94,35 @@ class FixedClock(Clock):
 
         self._instant = instant
 
+    def advance(self, *, delta: timedelta) -> None:
+        """
+        Advance by a non-negative elapsed duration, preserving the clock's timezone.
+
+        Args:
+            delta (timedelta): Non-negative elapsed duration to add to the instant.
+
+        Raises:
+            ValueError: If `delta` is negative.
+            OverflowError: If the resulting instant is outside datetime's range.
+
+        Example:
+        ```python
+        from datetime import UTC, datetime, timedelta
+
+        from clock_pattern.clocks.testing import FixedClock
+
+        clock = FixedClock(instant=datetime(2025, 12, 31, 23, 59, tzinfo=UTC))
+        clock.advance(delta=timedelta(minutes=2))
+        print(clock.now())
+        # >>> 2026-01-01 00:01:00+00:00
+        ```
+        """
+        if delta < timedelta(0):
+            raise ValueError(f'FixedClock delta <<<{delta}>>> must be greater than or equal to zero.')
+
+        if delta:
+            self._instant = (self._instant.astimezone(UTC) + delta).astimezone(self._instant.tzinfo)
+
     @override
     def now(self) -> datetime:
         """

{clock_pattern-0.9.0 → clock_pattern-0.11.0}/clock_pattern/clocks/testing/mock_clock.py

@@ -106,7 +106,7 @@ class MockClock(Clock):
 
         self._now_mock()
 
-        return self._now_datetime  # type: ignore[return-value]
+        return self._now_datetime  # type: ignore[ty:invalid-return-type]
 
     def prepare_now_method_return_value(self, *, now: datetime) -> None:
         """
@@ -220,7 +220,7 @@ class MockClock(Clock):
 
         self._today_mock()
 
-        return self._today_date  # type: ignore[return-value]
+        return self._today_date  # type: ignore[ty:invalid-return-type]
 
     def prepare_today_method_return_value(self, *, today: date) -> None:
         """

clock_pattern-0.11.0/clock_pattern/deadlines/__init__.py

@@ -0,0 +1,9 @@
+from .errors import TimeoutExpiredError
+from .models import Deadline
+from .system_deadline import SystemDeadline
+
+__all__ = (
+    'Deadline',
+    'SystemDeadline',
+    'TimeoutExpiredError',
+)

clock_pattern-0.11.0/clock_pattern/deadlines/errors/__init__.py

@@ -0,0 +1,3 @@
+from .timeout_expired_error import TimeoutExpiredError
+
+__all__ = ('TimeoutExpiredError',)

clock_pattern-0.11.0/clock_pattern/deadlines/errors/timeout_expired_error.py

@@ -0,0 +1,60 @@
+"""
+Deadline exceptions.
+"""
+
+
+class TimeoutExpiredError(TimeoutError):
+    """
+    Raised when a deadline timeout expires.
+
+    Example:
+    ```python
+    from clock_pattern import TimeoutExpiredError
+
+    error = TimeoutExpiredError(elapsed_seconds=1.5)
+    print(error)
+    # >>> Deadline expired after <<<1.5>>> seconds.
+    ```
+    """
+
+    _elapsed_seconds: float
+
+    def __init__(self, *, elapsed_seconds: float) -> None:
+        """
+        Create a `TimeoutExpiredError` with the configured duration.
+
+        Args:
+            elapsed_seconds (float): Duration in seconds that expired.
+
+        Example:
+        ```python
+        from clock_pattern import TimeoutExpiredError
+
+        error = TimeoutExpiredError(elapsed_seconds=1.5)
+        print(error)
+        # >>> Deadline expired after <<<1.5>>> seconds.
+        ```
+        """
+        self._elapsed_seconds = elapsed_seconds
+
+        message = f'Deadline expired after <<<{self._elapsed_seconds}>>> seconds.'
+        super().__init__(message)
+
+    @property
+    def elapsed_seconds(self) -> float:
+        """
+        Retrieve the duration in seconds that expired.
+
+        Returns:
+            float: Duration in seconds that expired.
+
+        Example:
+        ```python
+        from clock_pattern import TimeoutExpiredError
+
+        error = TimeoutExpiredError(elapsed_seconds=1.5)
+        print(error.elapsed_seconds)
+        # >>> 1.5
+        ```
+        """
+        return self._elapsed_seconds

clock_pattern-0.11.0/clock_pattern/deadlines/models/__init__.py

@@ -0,0 +1,3 @@
+from .deadline import Deadline
+
+__all__ = ('Deadline',)