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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: clock-pattern
-Version: 0.10.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,6 +20,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
+Requires-Dist: typing-extensions>=4.4.0; python_version < '3.12'
 Requires-Dist: value-object-pattern>=1.36.0
 Description-Content-Type: text/markdown
 
@@ -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
@@ -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>
@@ -214,7 +211,7 @@ Use the top-level package for contracts and production helpers, and each feature
 
 | 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 always returns the same datetime and derived date. |
+| [`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. |
@@ -223,26 +220,43 @@ Use the top-level package for contracts and production helpers, and each feature
 | `MockRetrier` / `MockRetrierAsync` | `from clock_pattern.retriers.testing import MockRetrier, MockRetrierAsync` | Retry test doubles with prepared results. |
 
 ```python
-from clock_pattern import Stopwatch, SystemDeadline, SystemMonotonicClock, SystemPoller, SystemRetrier, SystemSleeper
+from clock_pattern import Stopwatch, SystemMonotonicClock, SystemSleeper
 
 monotonic_clock = SystemMonotonicClock()
 sleeper = SystemSleeper(monotonic_clock=monotonic_clock)
-poller = SystemPoller(sleeper=sleeper, monotonic_clock=monotonic_clock)
 
 with Stopwatch(monotonic_clock=monotonic_clock) as stopwatch:
     pass
 
-with sleeper.minimum_duration(seconds=2):
+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,
 )
@@ -321,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.10.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
@@ -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>
@@ -189,7 +185,7 @@ Use the top-level package for contracts and production helpers, and each feature
 
 | 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 always returns the same datetime and derived date. |
+| [`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. |
@@ -198,26 +194,43 @@ Use the top-level package for contracts and production helpers, and each feature
 | `MockRetrier` / `MockRetrierAsync` | `from clock_pattern.retriers.testing import MockRetrier, MockRetrierAsync` | Retry test doubles with prepared results. |
 
 ```python
-from clock_pattern import Stopwatch, SystemDeadline, SystemMonotonicClock, SystemPoller, SystemRetrier, SystemSleeper
+from clock_pattern import Stopwatch, SystemMonotonicClock, SystemSleeper
 
 monotonic_clock = SystemMonotonicClock()
 sleeper = SystemSleeper(monotonic_clock=monotonic_clock)
-poller = SystemPoller(sleeper=sleeper, monotonic_clock=monotonic_clock)
 
 with Stopwatch(monotonic_clock=monotonic_clock) as stopwatch:
     pass
 
-with sleeper.minimum_duration(seconds=2):
+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,
 )
@@ -296,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.10.0 → clock_pattern-0.11.0}/clock_pattern/__init__.py

@@ -1,4 +1,4 @@
-__version__ = '0.10.0'
+__version__ = '0.11.0'
 
 from .clocks import Clock, SystemClock, UtcClock
 from .deadlines import Deadline, SystemDeadline, TimeoutExpiredError

{clock_pattern-0.10.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.10.0 → clock_pattern-0.11.0}/clock_pattern/deadlines/models/deadline.py

@@ -11,7 +11,7 @@ class Deadline(AbstractContextManager['Deadline']):
     Define the interface for injectable deadlines.
 
     Example:
-    ```python
+    ```python unix
     from clock_pattern import SystemDeadline, SystemMonotonicClock
 
     with SystemDeadline(seconds=1, monotonic_clock=SystemMonotonicClock()) as deadline:
@@ -101,6 +101,5 @@ class Deadline(AbstractContextManager['Deadline']):
         monotonic_clock = MockMonotonicClock()
         deadline = SystemDeadline(seconds=1, monotonic_clock=monotonic_clock)
         monotonic_clock.advance(seconds=1)
-        deadline.raise_if_expired()
         ```
         """

{clock_pattern-0.10.0 → clock_pattern-0.11.0}/clock_pattern/deadlines/system_deadline.py

@@ -30,7 +30,7 @@ class SystemDeadline(Deadline):
     Expose monotonic deadline state and enforce Unix main-thread context timeouts.
 
     Example:
-    ```python
+    ```python unix
     from clock_pattern import SystemDeadline, SystemMonotonicClock
 
     with SystemDeadline(seconds=1, monotonic_clock=SystemMonotonicClock()) as deadline:
@@ -160,7 +160,6 @@ class SystemDeadline(Deadline):
         monotonic_clock = MockMonotonicClock()
         deadline = SystemDeadline(seconds=1, monotonic_clock=monotonic_clock)
         monotonic_clock.advance(seconds=1)
-        deadline.raise_if_expired()
         ```
         """
         elapsed_seconds = self.elapsed_seconds
@@ -183,7 +182,7 @@ class SystemDeadline(Deadline):
             Self: This deadline instance.
 
         Example:
-        ```python
+        ```python unix
         from clock_pattern import SystemDeadline, SystemMonotonicClock
 
         with SystemDeadline(seconds=1, monotonic_clock=SystemMonotonicClock()) as deadline:
@@ -252,7 +251,7 @@ class SystemDeadline(Deadline):
             bool | None: `None`, so exceptions from the managed block are not suppressed.
 
         Example:
-        ```python
+        ```python unix
         from clock_pattern import SystemDeadline, SystemMonotonicClock
 
         with SystemDeadline(seconds=1, monotonic_clock=SystemMonotonicClock()) as deadline:

{clock_pattern-0.10.0 → clock_pattern-0.11.0}/clock_pattern/deadlines/testing/mock_deadline.py

@@ -138,7 +138,6 @@ class MockDeadline(Deadline):
 
         deadline = MockDeadline(seconds=1)
         deadline.advance(seconds=1)
-        deadline.raise_if_expired()
         ```
         """
         self._raise_if_expired_mock()

{clock_pattern-0.10.0 → clock_pattern-0.11.0}/clock_pattern/pollers/models/poller.py

@@ -41,6 +41,9 @@ class Poller(ABC):
         """
         Poll a condition until it succeeds or the timeout expires.
 
+        Timeout checks are cooperative: conditions are not interrupted. Success at the boundary is accepted;
+        success after a positive timeout is rejected. A zero timeout evaluates the condition once.
+
         Args:
             condition (Callable[[], bool]): Condition checked until it returns `True`.
             timeout_seconds (float): Maximum duration to wait.

{clock_pattern-0.10.0 → clock_pattern-0.11.0}/clock_pattern/pollers/models/poller_async.py

@@ -41,6 +41,10 @@ class PollerAsync(ABC):
         """
         Poll a condition until it succeeds or the timeout expires.
 
+        The timeout covers condition evaluation and sleeping. Overdue awaits are cancelled; synchronous blocking code
+        cannot be interrupted. Conditions must propagate cancellation. Injected-clock checks reject success after a
+        positive timeout. A zero timeout permits one evaluation only if it completes without suspending.
+
         Args:
             condition (Callable[[], bool | Awaitable[bool]]): Sync or async condition checked until it succeeds.
             timeout_seconds (float): Maximum duration to wait.

{clock_pattern-0.10.0 → clock_pattern-0.11.0}/clock_pattern/pollers/system_poller.py

@@ -69,6 +69,9 @@ class SystemPoller(Poller):
         """
         Poll `condition` until it returns `True`.
 
+        Conditions run cooperatively and are not interrupted. A successful result at the timeout boundary is
+        accepted, but a result after a positive timeout raises. A zero timeout evaluates the condition once.
+
         Args:
             condition (Callable[[], bool]): Condition checked until it returns `True`.
             timeout_seconds (float): Maximum duration to wait.
@@ -101,6 +104,9 @@ class SystemPoller(Poller):
         deadline = SystemDeadline(seconds=timeout_seconds, monotonic_clock=self._monotonic_clock)
         while True:
             condition_result = BooleanValueObject(value=condition(), title='SystemPoller', parameter='condition').value
+            if timeout_seconds > 0 and deadline.elapsed_seconds > timeout_seconds:
+                deadline.raise_if_expired()
+
             if condition_result:
                 return
 

{clock_pattern-0.10.0 → clock_pattern-0.11.0}/clock_pattern/pollers/system_poller_async.py

@@ -9,12 +9,13 @@ if version_info >= (3, 12):
 else:
     from typing_extensions import override  # pragma: no cover
 
+from asyncio import timeout
 from collections.abc import Awaitable, Callable
 from inspect import isawaitable
 
 from value_object_pattern.usables import BooleanValueObject, PositiveNumberValueObject, PositiveOrZeroNumberValueObject
 
-from clock_pattern.deadlines import SystemDeadline
+from clock_pattern.deadlines import SystemDeadline, TimeoutExpiredError
 from clock_pattern.monotonic_clocks.models import MonotonicClock
 from clock_pattern.pollers.models import PollerAsync
 from clock_pattern.sleepers.models import SleeperAsync
@@ -70,6 +71,11 @@ class SystemPollerAsync(PollerAsync):
         """
         Poll `condition` until it returns or awaits to `True`.
 
+        The timeout covers condition evaluation and sleeping, cancelling overdue awaits through asyncio. Blocking
+        synchronous code and coroutines that suppress cancellation cannot be forcibly interrupted. Injected-clock checks
+        also reject results after a positive timeout. A zero timeout allows one immediate evaluation, but cancels it if
+        it suspends. External cancellation and condition exceptions propagate.
+
         Args:
             condition (Callable[[], bool | Awaitable[bool]]): Sync or async condition checked until it is true.
             timeout_seconds (float): Maximum duration to wait.
@@ -100,6 +106,44 @@ class SystemPollerAsync(PollerAsync):
         PositiveNumberValueObject(value=interval_seconds, title='SystemPollerAsync', parameter='interval_seconds')
 
         deadline = SystemDeadline(seconds=timeout_seconds, monotonic_clock=self._monotonic_clock)
+
+        timeout_context = timeout(timeout_seconds)
+        try:
+            async with timeout_context:
+                await self._poll_until(
+                    condition=condition,
+                    deadline=deadline,
+                    timeout_seconds=timeout_seconds,
+                    interval_seconds=interval_seconds,
+                )
+
+        except TimeoutError as error:
+            if timeout_context.expired():
+                raise TimeoutExpiredError(elapsed_seconds=deadline.elapsed_seconds) from error
+
+            raise
+
+    async def _poll_until(
+        self,
+        *,
+        condition: Callable[[], bool | Awaitable[bool]],
+        deadline: SystemDeadline,
+        timeout_seconds: float,
+        interval_seconds: float,
+    ) -> None:
+        """
+        Poll using the injected clock while the enclosing asyncio timeout bounds awaits.
+
+        Args:
+            condition (Callable[[], bool | Awaitable[bool]]): Sync or async condition checked until it is true.
+            deadline (SystemDeadline): Deadline used to check for timeout expiration.
+            timeout_seconds (float): Maximum duration to wait.
+            interval_seconds (float): Duration between condition checks.
+
+        Raises:
+            TypeError: If `condition` does not return a boolean.
+            TimeoutExpiredError: If the timeout expires before `condition` returns `True`.
+        """
         while True:
             condition_result = condition()
 
@@ -107,6 +151,9 @@ class SystemPollerAsync(PollerAsync):
                 condition_result = await condition_result
 
             condition_result = BooleanValueObject(value=condition_result, title='SystemPollerAsync', parameter='condition').value  # noqa: E501  # fmt: skip
+            if timeout_seconds > 0 and deadline.elapsed_seconds > timeout_seconds:
+                deadline.raise_if_expired()
+
             if condition_result:
                 return
 

{clock_pattern-0.10.0 → clock_pattern-0.11.0}/clock_pattern/retriers/models/retrier.py

@@ -42,6 +42,7 @@ class Retrier(ABC):
         operation: Callable[[], T],
         attempts: int,
         delay_seconds: float = 0.0,
+        max_delay_seconds: float | None = None,
         backoff: float = 1.0,
         jitter: bool = False,
         retry_on: type[Exception] | tuple[type[Exception], ...] = Exception,
@@ -54,6 +55,8 @@ class Retrier(ABC):
             attempts (int): Maximum number of attempts, including the first call.
             delay_seconds (float, optional): Finite, non-negative initial delay between failed attempts. Defaults
             to 0.0 seconds.
+            max_delay_seconds (float | None, optional): Finite, non-negative delay cap applied before jitter. Defaults
+            to `None` (uncapped). Zero disables sleeping. Backoff grows from the capped delay.
             backoff (float, optional): Finite, positive multiplier applied to the delay after each failed attempt.
             Defaults to 1.0 (no backoff).
             jitter (bool, optional): Whether to randomize each delay. Defaults to `False`.

{clock_pattern-0.10.0 → clock_pattern-0.11.0}/clock_pattern/retriers/models/retrier_async.py

@@ -45,6 +45,7 @@ class RetrierAsync(ABC):
         operation: Callable[[], Awaitable[T]],
         attempts: int,
         delay_seconds: float = 0.0,
+        max_delay_seconds: float | None = None,
         backoff: float = 1.0,
         jitter: bool = False,
         retry_on: type[Exception] | tuple[type[Exception], ...] = Exception,
@@ -57,6 +58,8 @@ class RetrierAsync(ABC):
             attempts (int): Maximum number of attempts, including the first call.
             delay_seconds (float, optional): Finite, non-negative initial delay between failed attempts. Defaults
             to 0.0 seconds.
+            max_delay_seconds (float | None, optional): Finite, non-negative delay cap applied before jitter. Defaults
+            to `None` (uncapped). Zero disables sleeping. Backoff grows from the capped delay.
             backoff (float, optional): Finite, positive multiplier applied to the delay after each failed attempt.
             Defaults to 1.0 (no backoff).
             jitter (bool, optional): Whether to randomize each delay. Defaults to `False`.

{clock_pattern-0.10.0 → clock_pattern-0.11.0}/clock_pattern/retriers/system_retrier.py

@@ -73,6 +73,7 @@ class SystemRetrier(Retrier):
         operation: Callable[[], T],
         attempts: int,
         delay_seconds: float = 0.0,
+        max_delay_seconds: float | None = None,
         backoff: float = 1.0,
         jitter: bool = False,
         retry_on: type[Exception] | tuple[type[Exception], ...] = Exception,
@@ -85,6 +86,8 @@ class SystemRetrier(Retrier):
             attempts (int): Maximum number of attempts, including the first call.
             delay_seconds (float, optional): Finite, non-negative initial delay between failed attempts. Defaults
             to 0.0 seconds.
+            max_delay_seconds (float | None, optional): Finite, non-negative delay cap applied before jitter. Defaults
+            to `None` (uncapped). Zero disables sleeping. Backoff grows from the capped delay.
             backoff (float, optional): Finite, positive multiplier applied to the delay after each failed attempt.
             Defaults to 1.0 (no backoff).
             jitter (bool, optional): Whether to randomize each delay. Defaults to `False`.
@@ -96,6 +99,8 @@ class SystemRetrier(Retrier):
             ValueError: If the `attempts` is not a positive integer.
             TypeError: If the `delay_seconds` is not an integer or float.
             ValueError: If the `delay_seconds` is negative.
+            ValueError: If `max_delay_seconds` is negative or non-finite.
+            TypeError: If `max_delay_seconds` is neither a number nor `None`.
             TypeError: If the `backoff` is not an integer or float.
             ValueError: If the `backoff` is not positive.
             TypeError: If the `jitter` is not a boolean.
@@ -118,10 +123,14 @@ class SystemRetrier(Retrier):
         """
         PositiveIntegerValueObject(value=attempts, title='SystemRetrier', parameter='attempts')
         PositiveOrZeroNumberValueObject(value=delay_seconds, title='SystemRetrier', parameter='delay_seconds')
+        if max_delay_seconds is not None:
+            PositiveOrZeroNumberValueObject(value=max_delay_seconds, title='SystemRetrier', parameter='max_delay_seconds')  # noqa: E501  # fmt: skip
+
         PositiveNumberValueObject(value=backoff, title='SystemRetrier', parameter='backoff')
         BooleanValueObject(value=jitter, title='SystemRetrier', parameter='jitter')
 
-        current_delay_seconds = delay_seconds
+        delay_cap = float('inf') if max_delay_seconds is None else max_delay_seconds
+        current_delay_seconds = min(delay_seconds, delay_cap)
         for attempt_number in range(1, attempts + 1):
             try:
                 return operation()
@@ -134,6 +143,6 @@ class SystemRetrier(Retrier):
                 if sleep_seconds > 0:
                     self._sleeper.sleep(seconds=sleep_seconds)
 
-                current_delay_seconds *= backoff
+                current_delay_seconds = min(current_delay_seconds * backoff, delay_cap)
 
         raise RuntimeError('SystemRetrier attempts loop ended unexpectedly.')  # pragma: no cover

{clock_pattern-0.10.0 → clock_pattern-0.11.0}/clock_pattern/retriers/system_retrier_async.py

@@ -83,6 +83,7 @@ class SystemRetrierAsync(RetrierAsync):
         operation: Callable[[], Awaitable[T]],
         attempts: int,
         delay_seconds: float = 0.0,
+        max_delay_seconds: float | None = None,
         backoff: float = 1.0,
         jitter: bool = False,
         retry_on: type[Exception] | tuple[type[Exception], ...] = Exception,
@@ -95,6 +96,8 @@ class SystemRetrierAsync(RetrierAsync):
             attempts (int): Maximum number of attempts, including the first call.
             delay_seconds (float, optional): Finite, non-negative initial delay between failed attempts. Defaults
             to 0.0 seconds.
+            max_delay_seconds (float | None, optional): Finite, non-negative delay cap applied before jitter. Defaults
+            to `None` (uncapped). Zero disables sleeping. Backoff grows from the capped delay.
             backoff (float, optional): Finite, positive multiplier applied to the delay after each failed attempt.
             Defaults to 1.0 (no backoff).
             jitter (bool, optional): Whether to randomize each delay. Defaults to `False`.
@@ -106,6 +109,8 @@ class SystemRetrierAsync(RetrierAsync):
             ValueError: If the `attempts` is not a positive integer.
             TypeError: If the `delay_seconds` is not an integer or float.
             ValueError: If the `delay_seconds` is negative.
+            ValueError: If `max_delay_seconds` is negative or non-finite.
+            TypeError: If `max_delay_seconds` is neither a number nor `None`.
             TypeError: If the `backoff` is not an integer or float.
             ValueError: If the `backoff` is not positive.
             TypeError: If the `jitter` is not a boolean.
@@ -133,10 +138,14 @@ class SystemRetrierAsync(RetrierAsync):
         """
         PositiveIntegerValueObject(value=attempts, title='AsyncSystemRetrier', parameter='attempts')
         PositiveOrZeroNumberValueObject(value=delay_seconds, title='AsyncSystemRetrier', parameter='delay_seconds')
+        if max_delay_seconds is not None:
+            PositiveOrZeroNumberValueObject(value=max_delay_seconds, title='AsyncSystemRetrier', parameter='max_delay_seconds')  # noqa: E501  # fmt: skip
+
         PositiveNumberValueObject(value=backoff, title='AsyncSystemRetrier', parameter='backoff')
         BooleanValueObject(value=jitter, title='AsyncSystemRetrier', parameter='jitter')
 
-        current_delay_seconds = delay_seconds
+        delay_cap = float('inf') if max_delay_seconds is None else max_delay_seconds
+        current_delay_seconds = min(delay_seconds, delay_cap)
         for attempt_number in range(1, attempts + 1):
             try:
                 return await operation()
@@ -149,6 +158,6 @@ class SystemRetrierAsync(RetrierAsync):
                 if sleep_seconds > 0:
                     await self._sleeper.sleep(seconds=sleep_seconds)
 
-                current_delay_seconds *= backoff
+                current_delay_seconds = min(current_delay_seconds * backoff, delay_cap)
 
         raise RuntimeError('SystemRetrierAsync attempts loop ended unexpectedly.')  # pragma: no cover

{clock_pattern-0.10.0 → clock_pattern-0.11.0}/clock_pattern/retriers/testing/mock_retrier.py

@@ -76,6 +76,7 @@ class MockRetrier(Retrier):
         operation: Callable[[], T],
         attempts: int,
         delay_seconds: float = 0.0,
+        max_delay_seconds: float | None = None,
         backoff: float = 1.0,
         jitter: bool = False,
         retry_on: type[Exception] | tuple[type[Exception], ...] = Exception,
@@ -88,6 +89,8 @@ class MockRetrier(Retrier):
             attempts (int): Maximum number of attempts, including the first call.
             delay_seconds (float, optional): Finite, non-negative initial delay between failed attempts. Defaults
             to 0.0 seconds.
+            max_delay_seconds (float | None, optional): Finite, non-negative delay cap applied before jitter. Defaults
+            to `None` (uncapped). Zero disables sleeping. Backoff grows from the capped delay.
             backoff (float, optional): Finite, positive multiplier applied to the delay after each failed attempt.
             Defaults to 1.0 (no backoff).
             jitter (bool, optional): Whether to randomize each delay. Defaults to `False`.
@@ -99,6 +102,8 @@ class MockRetrier(Retrier):
             ValueError: If the `attempts` is not a positive integer.
             TypeError: If the `delay_seconds` is not an integer or float.
             ValueError: If the `delay_seconds` is negative.
+            ValueError: If `max_delay_seconds` is negative or non-finite.
+            TypeError: If `max_delay_seconds` is neither a number nor `None`.
             TypeError: If the `backoff` is not an integer or float.
             ValueError: If the `backoff` is not positive.
             TypeError: If the `jitter` is not a boolean.
@@ -122,6 +127,9 @@ class MockRetrier(Retrier):
         """
         PositiveIntegerValueObject(value=attempts, title='MockRetrier', parameter='attempts')
         PositiveOrZeroNumberValueObject(value=delay_seconds, title='MockRetrier', parameter='delay_seconds')
+        if max_delay_seconds is not None:
+            PositiveOrZeroNumberValueObject(value=max_delay_seconds, title='MockRetrier', parameter='max_delay_seconds')
+
         PositiveNumberValueObject(value=backoff, title='MockRetrier', parameter='backoff')
         BooleanValueObject(value=jitter, title='MockRetrier', parameter='jitter')
 
@@ -129,6 +137,7 @@ class MockRetrier(Retrier):
             operation=operation,
             attempts=attempts,
             delay_seconds=delay_seconds,
+            max_delay_seconds=max_delay_seconds,
             backoff=backoff,
             jitter=jitter,
             retry_on=retry_on,
@@ -195,6 +204,7 @@ class MockRetrier(Retrier):
         operation: Callable[[], Any],
         attempts: int,
         delay_seconds: float = 0.0,
+        max_delay_seconds: float | None = None,
         backoff: float = 1.0,
         jitter: bool = False,
         retry_on: type[Exception] | tuple[type[Exception], ...] = Exception,
@@ -206,6 +216,8 @@ class MockRetrier(Retrier):
             operation (Callable[[], Any]): Expected operation callable.
             attempts (int): Expected maximum number of attempts.
             delay_seconds (float, optional): Expected finite, non-negative initial delay. Defaults to 0.0 seconds.
+            max_delay_seconds (float | None, optional): Finite, non-negative delay cap applied before jitter. Defaults
+            to `None` (uncapped). Zero disables sleeping. Backoff grows from the capped delay.
             backoff (float, optional): Expected finite, positive delay multiplier. Defaults to 1.0.
             jitter (bool, optional): Expected jitter flag. Defaults to False.
             retry_on (type[Exception] | tuple[type[Exception], ...], optional): Expected retryable exception types.
@@ -216,6 +228,8 @@ class MockRetrier(Retrier):
             ValueError: If the `attempts` is not a positive integer.
             TypeError: If the `delay_seconds` is not an integer or float.
             ValueError: If the `delay_seconds` is negative.
+            ValueError: If `max_delay_seconds` is negative or non-finite.
+            TypeError: If `max_delay_seconds` is neither a number nor `None`.
             TypeError: If the `backoff` is not an integer or float.
             ValueError: If the `backoff` is not positive.
             TypeError: If the `jitter` is not a boolean.
@@ -233,6 +247,9 @@ class MockRetrier(Retrier):
         """
         PositiveIntegerValueObject(value=attempts, title='MockRetrier', parameter='attempts')
         PositiveOrZeroNumberValueObject(value=delay_seconds, title='MockRetrier', parameter='delay_seconds')
+        if max_delay_seconds is not None:
+            PositiveOrZeroNumberValueObject(value=max_delay_seconds, title='MockRetrier', parameter='max_delay_seconds')
+
         PositiveNumberValueObject(value=backoff, title='MockRetrier', parameter='backoff')
         BooleanValueObject(value=jitter, title='MockRetrier', parameter='jitter')
 
@@ -240,6 +257,7 @@ class MockRetrier(Retrier):
             operation=operation,
             attempts=attempts,
             delay_seconds=delay_seconds,
+            max_delay_seconds=max_delay_seconds,
             backoff=backoff,
             jitter=jitter,
             retry_on=retry_on,

{clock_pattern-0.10.0 → clock_pattern-0.11.0}/clock_pattern/retriers/testing/mock_retrier_async.py

@@ -76,6 +76,7 @@ class MockRetrierAsync(RetrierAsync):
         operation: Callable[[], Awaitable[T]],
         attempts: int,
         delay_seconds: float = 0.0,
+        max_delay_seconds: float | None = None,
         backoff: float = 1.0,
         jitter: bool = False,
         retry_on: type[Exception] | tuple[type[Exception], ...] = Exception,
@@ -88,6 +89,8 @@ class MockRetrierAsync(RetrierAsync):
             attempts (int): Maximum number of attempts requested by the code under test.
             delay_seconds (float, optional): Finite, non-negative initial delay requested by the code under test.
             Defaults to 0.0 seconds.
+            max_delay_seconds (float | None, optional): Finite, non-negative delay cap applied before jitter. Defaults
+            to `None` (uncapped). Zero disables sleeping. Backoff grows from the capped delay.
             backoff (float, optional): Finite, positive delay multiplier requested by the code under test.
             Defaults to 1.0.
             jitter (bool, optional): Whether jitter was requested. Defaults to False.
@@ -99,6 +102,8 @@ class MockRetrierAsync(RetrierAsync):
             ValueError: If the `attempts` is not a positive integer.
             TypeError: If the `delay_seconds` is not an integer or float.
             ValueError: If the `delay_seconds` is negative.
+            ValueError: If `max_delay_seconds` is negative or non-finite.
+            TypeError: If `max_delay_seconds` is neither a number nor `None`.
             TypeError: If the `backoff` is not an integer or float.
             ValueError: If the `backoff` is not positive.
             TypeError: If the `jitter` is not a boolean.
@@ -126,6 +131,9 @@ class MockRetrierAsync(RetrierAsync):
         """
         PositiveIntegerValueObject(value=attempts, title='MockRetrierAsync', parameter='attempts')
         PositiveOrZeroNumberValueObject(value=delay_seconds, title='MockRetrierAsync', parameter='delay_seconds')
+        if max_delay_seconds is not None:
+            PositiveOrZeroNumberValueObject(value=max_delay_seconds, title='MockRetrierAsync', parameter='max_delay_seconds')  # noqa: E501  # fmt: skip
+
         PositiveNumberValueObject(value=backoff, title='MockRetrierAsync', parameter='backoff')
         BooleanValueObject(value=jitter, title='MockRetrierAsync', parameter='jitter')
 
@@ -133,6 +141,7 @@ class MockRetrierAsync(RetrierAsync):
             operation=operation,
             attempts=attempts,
             delay_seconds=delay_seconds,
+            max_delay_seconds=max_delay_seconds,
             backoff=backoff,
             jitter=jitter,
             retry_on=retry_on,
@@ -204,6 +213,7 @@ class MockRetrierAsync(RetrierAsync):
         operation: Callable[[], Awaitable[Any]],
         attempts: int,
         delay_seconds: float = 0.0,
+        max_delay_seconds: float | None = None,
         backoff: float = 1.0,
         jitter: bool = False,
         retry_on: type[Exception] | tuple[type[Exception], ...] = Exception,
@@ -215,6 +225,8 @@ class MockRetrierAsync(RetrierAsync):
             operation (Callable[[], Awaitable[Any]]): Expected async operation callable.
             attempts (int): Expected maximum number of attempts.
             delay_seconds (float, optional): Expected finite, non-negative initial delay. Defaults to 0.0 seconds.
+            max_delay_seconds (float | None, optional): Finite, non-negative delay cap applied before jitter. Defaults
+            to `None` (uncapped). Zero disables sleeping. Backoff grows from the capped delay.
             backoff (float, optional): Expected finite, positive delay multiplier. Defaults to 1.0.
             jitter (bool, optional): Expected jitter flag. Defaults to False.
             retry_on (type[Exception] | tuple[type[Exception], ...], optional): Expected retryable exception types.
@@ -225,6 +237,8 @@ class MockRetrierAsync(RetrierAsync):
             ValueError: If the `attempts` is not a positive integer.
             TypeError: If the `delay_seconds` is not an integer or float.
             ValueError: If the `delay_seconds` is negative.
+            ValueError: If `max_delay_seconds` is negative or non-finite.
+            TypeError: If `max_delay_seconds` is neither a number nor `None`.
             TypeError: If the `backoff` is not an integer or float.
             ValueError: If the `backoff` is not positive.
             TypeError: If the `jitter` is not a boolean.
@@ -246,6 +260,9 @@ class MockRetrierAsync(RetrierAsync):
         """
         PositiveIntegerValueObject(value=attempts, title='MockRetrierAsync', parameter='attempts')
         PositiveOrZeroNumberValueObject(value=delay_seconds, title='MockRetrierAsync', parameter='delay_seconds')
+        if max_delay_seconds is not None:
+            PositiveOrZeroNumberValueObject(value=max_delay_seconds, title='MockRetrierAsync', parameter='max_delay_seconds')  # noqa: E501  # fmt: skip
+
         PositiveNumberValueObject(value=backoff, title='MockRetrierAsync', parameter='backoff')
         BooleanValueObject(value=jitter, title='MockRetrierAsync', parameter='jitter')
 
@@ -253,6 +270,7 @@ class MockRetrierAsync(RetrierAsync):
             operation=operation,
             attempts=attempts,
             delay_seconds=delay_seconds,
+            max_delay_seconds=max_delay_seconds,
             backoff=backoff,
             jitter=jitter,
             retry_on=retry_on,

{clock_pattern-0.10.0 → clock_pattern-0.11.0}/clock_pattern/sleepers/models/sleeper.py

@@ -16,7 +16,7 @@ class Sleeper(ABC):
     from clock_pattern.monotonic_clocks import SystemMonotonicClock
 
     sleeper = SystemSleeper(monotonic_clock=SystemMonotonicClock())
-    sleeper.sleep(seconds=1)
+    sleeper.sleep(seconds=0.001)
     ```
     """
 
@@ -34,7 +34,7 @@ class Sleeper(ABC):
         from clock_pattern.monotonic_clocks import SystemMonotonicClock
 
         sleeper = SystemSleeper(monotonic_clock=SystemMonotonicClock())
-        sleeper.sleep(seconds=1)
+        sleeper.sleep(seconds=0.001)
         ```
         """
 
@@ -56,7 +56,7 @@ class Sleeper(ABC):
 
         sleeper = SystemSleeper(monotonic_clock=SystemMonotonicClock())
 
-        with sleeper.minimum_duration(seconds=1):
+        with sleeper.minimum_duration(seconds=0.001):
             pass
         ```
         """

{clock_pattern-0.10.0 → clock_pattern-0.11.0}/clock_pattern/sleepers/models/sleeper_async.py

@@ -16,7 +16,7 @@ class SleeperAsync(ABC):
     from clock_pattern.monotonic_clocks import SystemMonotonicClock
 
     sleeper = SystemSleeperAsync(monotonic_clock=SystemMonotonicClock())
-    await sleeper.sleep(seconds=1)
+    await sleeper.sleep(seconds=0.001)
     ```
     """
 
@@ -34,7 +34,7 @@ class SleeperAsync(ABC):
         from clock_pattern.monotonic_clocks import SystemMonotonicClock
 
         sleeper = SystemSleeperAsync(monotonic_clock=SystemMonotonicClock())
-        await sleeper.sleep(seconds=0.1)
+        await sleeper.sleep(seconds=0.001)
         ```
         """
 
@@ -43,6 +43,8 @@ class SleeperAsync(ABC):
         """
         Create an async context manager that ensures the enclosed work takes at least `seconds`.
 
+        Cancellation propagates without padding the duration. Other body errors still pad the duration.
+
         Args:
             seconds (float): The minimum duration the enclosed work should take.
 
@@ -56,7 +58,7 @@ class SleeperAsync(ABC):
 
         sleeper = SystemSleeperAsync(monotonic_clock=SystemMonotonicClock())
 
-        async with sleeper.minimum_duration(seconds=1):
+        async with sleeper.minimum_duration(seconds=0.001):
             pass
         ```
         """

{clock_pattern-0.10.0 → clock_pattern-0.11.0}/clock_pattern/sleepers/system_sleeper.py

@@ -29,7 +29,7 @@ class SystemSleeper(Sleeper):
     from clock_pattern.monotonic_clocks import SystemMonotonicClock
 
     sleeper = SystemSleeper(monotonic_clock=SystemMonotonicClock())
-    sleeper.sleep(seconds=1)
+    sleeper.sleep(seconds=0.001)
     ```
     """
 
@@ -48,7 +48,7 @@ class SystemSleeper(Sleeper):
         from clock_pattern.monotonic_clocks import SystemMonotonicClock
 
         sleeper = SystemSleeper(monotonic_clock=SystemMonotonicClock())
-        sleeper.sleep(seconds=1)
+        sleeper.sleep(seconds=0.001)
         ```
         """
         self._monotonic_clock = monotonic_clock
@@ -71,7 +71,7 @@ class SystemSleeper(Sleeper):
         from clock_pattern.monotonic_clocks import SystemMonotonicClock
 
         sleeper = SystemSleeper(monotonic_clock=SystemMonotonicClock())
-        sleeper.sleep(seconds=1)
+        sleeper.sleep(seconds=0.001)
         ```
         """
         PositiveOrZeroNumberValueObject(value=seconds, title='SystemSleeper', parameter='seconds')
@@ -102,7 +102,7 @@ class SystemSleeper(Sleeper):
 
         sleeper = SystemSleeper(monotonic_clock=SystemMonotonicClock())
 
-        with sleeper.minimum_duration(seconds=1):
+        with sleeper.minimum_duration(seconds=0.001):
             pass
         ```
         """

{clock_pattern-0.10.0 → clock_pattern-0.11.0}/clock_pattern/sleepers/system_sleeper_async.py

@@ -9,7 +9,7 @@ if version_info >= (3, 12):
 else:
     from typing_extensions import override  # pragma: no cover
 
-from asyncio import sleep
+from asyncio import CancelledError, sleep
 from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager
 
@@ -29,7 +29,7 @@ class SystemSleeperAsync(SleeperAsync):
     from clock_pattern.monotonic_clocks import SystemMonotonicClock
 
     sleeper = SystemSleeperAsync(monotonic_clock=SystemMonotonicClock())
-    await sleeper.sleep(seconds=1)
+    await sleeper.sleep(seconds=0.001)
     ```
     """
 
@@ -48,7 +48,7 @@ class SystemSleeperAsync(SleeperAsync):
         from clock_pattern.monotonic_clocks import SystemMonotonicClock
 
         sleeper = SystemSleeperAsync(monotonic_clock=SystemMonotonicClock())
-        await sleeper.sleep(seconds=1)
+        await sleeper.sleep(seconds=0.001)
         ```
         """
         self._monotonic_clock = monotonic_clock
@@ -71,7 +71,7 @@ class SystemSleeperAsync(SleeperAsync):
         from clock_pattern.monotonic_clocks import SystemMonotonicClock
 
         sleeper = SystemSleeperAsync(monotonic_clock=SystemMonotonicClock())
-        await sleeper.sleep(seconds=1)
+        await sleeper.sleep(seconds=0.001)
         ```
         """
         PositiveOrZeroNumberValueObject(value=seconds, title='SystemSleeperAsync', parameter='seconds')
@@ -84,6 +84,9 @@ class SystemSleeperAsync(SleeperAsync):
         """
         Create an async context manager that ensures the enclosed work takes at least `seconds`.
 
+        Cancellation propagates immediately without padding the duration. Other body errors still wait out
+        the remaining duration before propagating.
+
         Args:
             seconds (float): The minimum elapsed duration for the enclosed asynchronous work.
 
@@ -102,19 +105,23 @@ class SystemSleeperAsync(SleeperAsync):
 
         sleeper = SystemSleeperAsync(monotonic_clock=SystemMonotonicClock())
 
-        async with sleeper.minimum_duration(seconds=1):
+        async with sleeper.minimum_duration(seconds=0.001):
             pass
         ```
         """
         PositiveOrZeroNumberValueObject(value=seconds, title='SystemSleeperAsync', parameter='seconds')
 
         started_time = self._monotonic_clock.current_seconds()
+        cancelled = False
         try:
             yield
 
+        except CancelledError:
+            cancelled = True
+            raise
+
         finally:
-            elapsed_seconds = self._monotonic_clock.current_seconds() - started_time
-            remaining_seconds = seconds - elapsed_seconds
+            remaining_seconds = 0.0 if cancelled else seconds - (self._monotonic_clock.current_seconds() - started_time)
 
             if remaining_seconds > 0:
                 await self.sleep(seconds=remaining_seconds)

{clock_pattern-0.10.0 → clock_pattern-0.11.0}/clock_pattern/sleepers/testing/mock_sleeper_async.py

@@ -9,6 +9,7 @@ if version_info >= (3, 12):
 else:
     from typing_extensions import override  # pragma: no cover
 
+from asyncio import CancelledError
 from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager
 from unittest.mock import AsyncMock
@@ -138,6 +139,8 @@ class MockSleeperAsync(SleeperAsync):
         """
         Create an async context manager that ensures the enclosed work takes at least `seconds`.
 
+        Cancellation propagates without recording sleep or advancing time. Other body errors still pad the duration.
+
         Args:
             seconds (float): The minimum elapsed duration for the enclosed asynchronous work.
 
@@ -162,12 +165,16 @@ class MockSleeperAsync(SleeperAsync):
         PositiveOrZeroNumberValueObject(value=seconds, title='MockSleeperAsync', parameter='seconds')
 
         started_time = self._monotonic_clock.current_seconds()
+        cancelled = False
         try:
             yield
 
+        except CancelledError:
+            cancelled = True
+            raise
+
         finally:
-            elapsed_seconds = self._monotonic_clock.current_seconds() - started_time
-            remaining_seconds = seconds - elapsed_seconds
+            remaining_seconds = 0.0 if cancelled else seconds - (self._monotonic_clock.current_seconds() - started_time)
 
             if remaining_seconds > 0:
                 await self.sleep(seconds=remaining_seconds)

{clock_pattern-0.10.0 → clock_pattern-0.11.0}/pyproject.toml

@@ -38,7 +38,10 @@ keywords = [
     'domain-driven-design',
 ]
 requires-python = '>=3.11'
-dependencies = ['value-object-pattern>=1.36.0']
+dependencies = [
+    'value-object-pattern>=1.36.0',
+    'typing-extensions>=4.4.0; python_version < "3.12"',
+]
 dynamic = ['version']
 
 [project.urls]
@@ -52,11 +55,13 @@ coverage = ['coverage[toml]>=7.0.0', 'smokeshow>=0.5.0']
 develop = ['pre-commit>=3.0.0']
 format = ['ruff>=0.11.10']
 lint = ['ruff>=0.11.10', 'ty>=0.0.77', { include-group = 'test' }]
-release = ['build>=1.2.2', 'python-semantic-release>=10.0.2']
+# TODO: Remove the pin when python-semantic-release supports click>=8.3.3 (PYSEC-2026-2132).
+release = ['build>=1.2.2', 'python-semantic-release==10.6.1']
 test = [
     'pytest>=8.0.0',
     'pytest-asyncio>=1.3.0',
     'pytest-randomly>=3.0.0',
+    'sybil[pytest]>=10.1.0',
     'object-mother-pattern>=2.1.0',
     { include-group = 'coverage' },
 ]
@@ -68,18 +73,13 @@ all = [
     { include-group = 'release' },
     { include-group = 'test' },
 ]
-
-
-[tool.uv]
-constraint-dependencies = ['click>=8.3.3'] # PYSEC-2026-2132
-
-
 [tool.pytest.ini_options]
 pythonpath = '.'
 addopts = [
-    '--strict-config',  # fail if an unregistered option is used
-    '--strict-markers', # fail if an unregistered marker is used
-    '--color=yes',      # color the output
+    '--strict-config',          # fail if an unregistered option is used
+    '--strict-markers',         # fail if an unregistered marker is used
+    '--color=yes',              # color the output
+    '-p tests.test_docstrings',
 ]
 markers = ['unit_testing: Check a unique functionality']
 xfail_strict = true
@@ -113,7 +113,7 @@ source = ['clock_pattern']
 [tool.ruff]
 indent-width = 4
 line-length = 120
-target-version = 'py314'
+target-version = 'py311'
 output-format = 'grouped'
 
 [tool.ruff.format]
@@ -199,8 +199,18 @@ version_variables = ['clock_pattern/__init__.py:__version__']
 
 [tool.semantic_release.commit_parser_options]
 minor_tags = ['feat']
-patch_tags = ['fix', 'perf', 'build']
-allowed_tags = ['feat', 'fix', 'perf', 'build']
+patch_tags = ['fix', 'perf']
+allowed_tags = [
+    'feat',
+    'fix',
+    'perf',
+    'build',
+    'refactor',
+    'test',
+    'docs',
+    'ci',
+    'chore',
+]
 default_bump_level = 0
 parse_squash_commits = false
 ignore_merge_commits = true