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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: clock-pattern
-Version: 0.9.0
+Version: 0.10.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,7 @@ 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: value-object-pattern>=1.36.0
 Description-Content-Type: text/markdown
 
 <a name="readme-top"></a>
@@ -60,7 +60,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)
@@ -168,32 +168,91 @@ 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. |
+| `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 always returns the same datetime and derived date. |
 | [`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, SystemDeadline, SystemMonotonicClock, SystemPoller, SystemRetrier, 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):
+    pass
+
+with SystemDeadline(seconds=5, monotonic_clock=monotonic_clock):
+    pass
+
+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,
+    backoff=2,
+    jitter=True,
+)
+```
 
-Use the top-level package for production clocks and `clock_pattern.clocks.testing` for test-only clocks.
+`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 +262,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

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

@@ -35,7 +35,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)
@@ -143,32 +143,91 @@ 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. |
+| `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 always returns the same datetime and derived date. |
 | [`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, SystemDeadline, SystemMonotonicClock, SystemPoller, SystemRetrier, 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):
+    pass
+
+with SystemDeadline(seconds=5, monotonic_clock=monotonic_clock):
+    pass
+
+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,
+    backoff=2,
+    jitter=True,
+)
+```
 
-Use the top-level package for production clocks and `clock_pattern.clocks.testing` for test-only clocks.
+`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 +237,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

clock_pattern-0.10.0/clock_pattern/__init__.py

@@ -0,0 +1,33 @@
+__version__ = '0.10.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.10.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.10.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.10.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.10.0/clock_pattern/deadlines/errors/__init__.py

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

clock_pattern-0.10.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.10.0/clock_pattern/deadlines/models/__init__.py

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

clock_pattern-0.10.0/clock_pattern/deadlines/models/deadline.py

@@ -0,0 +1,106 @@
+"""
+Abstract deadline contract for injectable timeout state.
+"""
+
+from abc import abstractmethod
+from contextlib import AbstractContextManager
+
+
+class Deadline(AbstractContextManager['Deadline']):
+    """
+    Define the interface for injectable deadlines.
+
+    Example:
+    ```python
+    from clock_pattern import SystemDeadline, SystemMonotonicClock
+
+    with SystemDeadline(seconds=1, monotonic_clock=SystemMonotonicClock()) as deadline:
+        print(deadline.remaining_seconds)
+    ```
+    """
+
+    @property
+    @abstractmethod
+    def elapsed_seconds(self) -> float:
+        """
+        Retrieve elapsed seconds since the deadline started.
+
+        Returns:
+            float: Elapsed seconds since the deadline started.
+
+        Example:
+        ```python
+        from clock_pattern import SystemDeadline
+        from clock_pattern.monotonic_clocks.testing import MockMonotonicClock
+
+        monotonic_clock = MockMonotonicClock()
+        deadline = SystemDeadline(seconds=1, monotonic_clock=monotonic_clock)
+        monotonic_clock.advance(seconds=0.25)
+        print(deadline.elapsed_seconds)
+        # >>> 0.25
+        ```
+        """
+
+    @property
+    @abstractmethod
+    def remaining_seconds(self) -> float:
+        """
+        Retrieve remaining seconds before expiry.
+
+        Returns:
+            float: Remaining seconds, never less than zero.
+
+        Example:
+        ```python
+        from clock_pattern import SystemDeadline
+        from clock_pattern.monotonic_clocks.testing import MockMonotonicClock
+
+        monotonic_clock = MockMonotonicClock()
+        deadline = SystemDeadline(seconds=1, monotonic_clock=monotonic_clock)
+        monotonic_clock.advance(seconds=0.25)
+        print(deadline.remaining_seconds)
+        # >>> 0.75
+        ```
+        """
+
+    @property
+    @abstractmethod
+    def expired(self) -> bool:
+        """
+        Check whether the deadline has expired.
+
+        Returns:
+            bool: `True` when the configured duration has elapsed.
+
+        Example:
+        ```python
+        from clock_pattern import SystemDeadline
+        from clock_pattern.monotonic_clocks.testing import MockMonotonicClock
+
+        monotonic_clock = MockMonotonicClock()
+        deadline = SystemDeadline(seconds=1, monotonic_clock=monotonic_clock)
+        monotonic_clock.advance(seconds=1)
+        print(deadline.expired)
+        # >>> True
+        ```
+        """
+
+    @abstractmethod
+    def raise_if_expired(self) -> None:
+        """
+        Raise when the configured duration has elapsed.
+
+        Raises:
+            TimeoutExpiredError: If the deadline expired.
+
+        Example:
+        ```python
+        from clock_pattern import SystemDeadline
+        from clock_pattern.monotonic_clocks.testing import MockMonotonicClock
+
+        monotonic_clock = MockMonotonicClock()
+        deadline = SystemDeadline(seconds=1, monotonic_clock=monotonic_clock)
+        monotonic_clock.advance(seconds=1)
+        deadline.raise_if_expired()
+        ```
+        """