clock-pattern 0.3.0__tar.gz → 0.5.0__tar.gz

clock_pattern-0.5.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: clock-pattern
+Version: 0.5.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
+Project-URL: Issues, https://github.com/adriamontoto/clock-pattern/issues
+Author: Adria Montoto
+License-Expression: MIT
+License-File: LICENSE.md
+Keywords: clock,dependency-injection,development,domain-driven-design,pattern,python,utilities
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: value-object-pattern>=0.6.0
+Description-Content-Type: text/markdown
+
+<a name="readme-top"></a>
+
+# 🕰️ Clock Pattern
+
+<p align="center">
+    <a href="https://github.com/adriamontoto/clock-pattern/actions/workflows/ci.yaml?event=push&branch=master" target="_blank">
+        <img src="https://github.com/adriamontoto/clock-pattern/actions/workflows/ci.yaml/badge.svg?event=push&branch=master" alt="CI Pipeline">
+    </a>
+    <a href="https://coverage-badge.samuelcolvin.workers.dev/redirect/adriamontoto/clock-pattern" target="_blank">
+        <img src="https://coverage-badge.samuelcolvin.workers.dev/adriamontoto/clock-pattern.svg" alt="Coverage Pipeline">
+    </a>
+    <a href="https://pypi.org/project/clock-pattern" target="_blank">
+        <img src="https://img.shields.io/pypi/v/clock-pattern?color=%2334D058&label=pypi%20package" alt="Package Version">
+    </a>
+    <a href="https://pypi.org/project/clock-pattern/" target="_blank">
+        <img src="https://img.shields.io/pypi/pyversions/clock-pattern.svg?color=%2334D058" alt="Supported Python Versions">
+    </a>
+    <a href="https://pepy.tech/projects/clock-pattern" target="_blank">
+        <img src="https://static.pepy.tech/badge/clock-pattern/month" alt="Package Downloads">
+    </a>
+</p>
+
+The **Clock Pattern** is a Python 🐍 package that turns time into an injectable dependency 🧩. By replacing ad-hoc datetime.now() calls with a swappable Clock interface 🕰️ you unlock deterministic tests 🧪, decouple business logic from the OS clock, and gain the freedom to swap in high-precision or logical clocks without touching domain code.
+<br><br>
+
+## Table of Contents
+
+- [📥 Installation](#installation)
+- [💻 Utilization](#utilization)
+  - [📚 Available Clocks](#available-clocks)
+  - [🎄 Real-Life Case: Christmas Detector Service](#real-life-case-christmas-detector-service)
+- [🤝 Contributing](#contributing)
+- [🔑 License](#license)
+
+<p align="right">
+    <a href="#readme-top">🔼 Back to top</a>
+</p><br><br>
+
+<a name="installation"></a>
+
+## 📥 Installation
+
+You can install **Clock Pattern** using `pip`:
+
+```bash
+pip install clock-pattern
+```
+
+<p align="right">
+    <a href="#readme-top">🔼 Back to top</a>
+</p><br><br>
+
+<a name="utilization"></a>
+
+## 💻 Utilization
+
+The **Clock Pattern** library is designed to be straightforward. Simply import the desired clock and use its `now()` or `today()` methods to get the current datetime/date. This approach allows for easy dependency injection and testing.
+
+Here is a basic example of how to use the [`SystemClock`](https://github.com/adriamontoto/clock-pattern/blob/master/clock_pattern/clocks/system_clock.py) clock:
+
+```python
+from datetime import timezone
+
+from clock_pattern import SystemClock
+
+clock = SystemClock(timezone=timezone.utc)
+print(clock.now())
+# >>> 2025-06-16 13:57:26.210964+00:00
+```
+
+<p align="right">
+    <a href="#readme-top">🔼 Back to top</a>
+</p><br><br>
+
+<a name="available-clocks"></a>
+
+## 📚 Available Clocks
+
+The package offers several clock implementations to suit different needs:
+
+- [`clock_pattern.SystemClock`](https://github.com/adriamontoto/clock-pattern/blob/master/clock_pattern/clocks/system_clock.py): The standard clock implementation that returns the system's current datetime/date with the provided timezone.
+- [`clock_pattern.UtcClock`](https://github.com/adriamontoto/clock-pattern/blob/master/clock_pattern/clocks/utc_clock.py): A clock implementation that returns the system's current datetime/date in UTC. Ideal for production environments.
+- [`clock_pattern.clocks.testing.FixedClock`](https://github.com/adriamontoto/clock-pattern/blob/master/clock_pattern/clocks/testing/fixed_clock.py): A clock that always returns a fixed, preset datetime/date. It is perfect for basic testing as it allows you to control the datetime/date within your test environment, ensuring deterministic results.
+- [`clock_pattern.clocks.testing.MockClock`](https://github.com/adriamontoto/clock-pattern/blob/master/clock_pattern/clocks/testing/mock_clock.py): A clock that allows you to mock the system clock. It is perfect for more complex testing as it allows you to control the datetime/date within your test environment and if or not the methods are called or not.
+<p align="right">
+    <a href="#readme-top">🔼 Back to top</a>
+</p><br><br>
+
+<a name="real-life-case-christmas-detector-service"></a>
+
+## 🎄 Real-Life Case: Christmas Detector Service
+
+Below is an example of a real-life scenario where Clock Pattern can create clean and testable code. We have a `ChristmasDetectorService` that checks if the curren date falls within a specific Christmas holiday range. Using the Clock Pattern, in this case [`UtcClock`](https://github.com/adriamontoto/clock-pattern/blob/master/clock_pattern/clocks/utc_clock.py) and [`MockClock`](https://github.com/adriamontoto/clock-pattern/blob/master/clock_pattern/clocks/testing/mock_clock.py), we can decouple the service from the python `datetime.now()` and `datetime.today()` functions, making it easy to test for different dates without changing the system's time.
+
+```python
+from datetime import date
+
+from clock_pattern import Clock, UtcClock
+from clock_pattern.clocks.testing import MockClock
+
+
+class ChristmasDetectorService:
+    def __init__(self, clock: Clock) -> None:
+        self.clock = clock
+        self.christmas_start = date(year=2024, month=12, day=24)
+        self.christmas_end = date(year=2025, month=1, day=6)
+
+    def is_christmas(self) -> bool:
+        return self.christmas_start <= self.clock.today() <= self.christmas_end
+
+
+clock = UtcClock()
+christmas_detector_service = ChristmasDetectorService(clock=clock)
+
+print(christmas_detector_service.is_christmas())
+# >>> False
+
+
+def test_christmas_detector_is_christmas() -> None:
+    clock = MockClock()
+    christmas_detector_service = ChristmasDetectorService(clock=clock)
+
+    today = date(year=2024, month=12, day=25)
+    clock.prepare_today_method_return_value(today=today)
+
+    assert christmas_detector_service.is_christmas() is True
+    clock.assert_today_method_was_called_once()
+
+
+def test_christmas_detector_is_not_christmas() -> None:
+    clock = MockClock()
+    christmas_detector_service = ChristmasDetectorService(clock=clock)
+
+    today = date(year=2025, month=1, day=7)
+    clock.prepare_today_method_return_value(today=today)
+
+    assert christmas_detector_service.is_christmas() is False
+    clock.assert_today_method_was_called_once()
+```
+
+<p align="right">
+    <a href="#readme-top">🔼 Back to top</a>
+</p><br><br>
+
+<a name="contributing"></a>
+
+## 🤝 Contributing
+
+We love community help! Before you open an issue or pull request, please read:
+
+- [`🤝 How to Contribute`](https://github.com/adriamontoto/clock-pattern/blob/master/.github/CONTRIBUTING.md)
+- [`🧭 Code of Conduct`](https://github.com/adriamontoto/clock-pattern/blob/master/.github/CODE_OF_CONDUCT.md)
+- [`🔐 Security Policy`](https://github.com/adriamontoto/clock-pattern/blob/master/.github/SECURITY.md)
+
+_Thank you for helping make **🕰️ Clock Pattern** package awesome! 🌟_
+
+<p align="right">
+    <a href="#readme-top">🔼 Back to top</a>
+</p><br><br>
+
+<a name="license"></a>
+
+## 🔑 License
+
+This project is licensed under the terms of the [`MIT license`](https://github.com/adriamontoto/clock-pattern/blob/master/LICENSE.md).
+
+<p align="right">
+    <a href="#readme-top">🔼 Back to top</a>
+</p>

clock_pattern-0.5.0/README.md

@@ -0,0 +1,169 @@
+<a name="readme-top"></a>
+
+# 🕰️ Clock Pattern
+
+<p align="center">
+    <a href="https://github.com/adriamontoto/clock-pattern/actions/workflows/ci.yaml?event=push&branch=master" target="_blank">
+        <img src="https://github.com/adriamontoto/clock-pattern/actions/workflows/ci.yaml/badge.svg?event=push&branch=master" alt="CI Pipeline">
+    </a>
+    <a href="https://coverage-badge.samuelcolvin.workers.dev/redirect/adriamontoto/clock-pattern" target="_blank">
+        <img src="https://coverage-badge.samuelcolvin.workers.dev/adriamontoto/clock-pattern.svg" alt="Coverage Pipeline">
+    </a>
+    <a href="https://pypi.org/project/clock-pattern" target="_blank">
+        <img src="https://img.shields.io/pypi/v/clock-pattern?color=%2334D058&label=pypi%20package" alt="Package Version">
+    </a>
+    <a href="https://pypi.org/project/clock-pattern/" target="_blank">
+        <img src="https://img.shields.io/pypi/pyversions/clock-pattern.svg?color=%2334D058" alt="Supported Python Versions">
+    </a>
+    <a href="https://pepy.tech/projects/clock-pattern" target="_blank">
+        <img src="https://static.pepy.tech/badge/clock-pattern/month" alt="Package Downloads">
+    </a>
+</p>
+
+The **Clock Pattern** is a Python 🐍 package that turns time into an injectable dependency 🧩. By replacing ad-hoc datetime.now() calls with a swappable Clock interface 🕰️ you unlock deterministic tests 🧪, decouple business logic from the OS clock, and gain the freedom to swap in high-precision or logical clocks without touching domain code.
+<br><br>
+
+## Table of Contents
+
+- [📥 Installation](#installation)
+- [💻 Utilization](#utilization)
+  - [📚 Available Clocks](#available-clocks)
+  - [🎄 Real-Life Case: Christmas Detector Service](#real-life-case-christmas-detector-service)
+- [🤝 Contributing](#contributing)
+- [🔑 License](#license)
+
+<p align="right">
+    <a href="#readme-top">🔼 Back to top</a>
+</p><br><br>
+
+<a name="installation"></a>
+
+## 📥 Installation
+
+You can install **Clock Pattern** using `pip`:
+
+```bash
+pip install clock-pattern
+```
+
+<p align="right">
+    <a href="#readme-top">🔼 Back to top</a>
+</p><br><br>
+
+<a name="utilization"></a>
+
+## 💻 Utilization
+
+The **Clock Pattern** library is designed to be straightforward. Simply import the desired clock and use its `now()` or `today()` methods to get the current datetime/date. This approach allows for easy dependency injection and testing.
+
+Here is a basic example of how to use the [`SystemClock`](https://github.com/adriamontoto/clock-pattern/blob/master/clock_pattern/clocks/system_clock.py) clock:
+
+```python
+from datetime import timezone
+
+from clock_pattern import SystemClock
+
+clock = SystemClock(timezone=timezone.utc)
+print(clock.now())
+# >>> 2025-06-16 13:57:26.210964+00:00
+```
+
+<p align="right">
+    <a href="#readme-top">🔼 Back to top</a>
+</p><br><br>
+
+<a name="available-clocks"></a>
+
+## 📚 Available Clocks
+
+The package offers several clock implementations to suit different needs:
+
+- [`clock_pattern.SystemClock`](https://github.com/adriamontoto/clock-pattern/blob/master/clock_pattern/clocks/system_clock.py): The standard clock implementation that returns the system's current datetime/date with the provided timezone.
+- [`clock_pattern.UtcClock`](https://github.com/adriamontoto/clock-pattern/blob/master/clock_pattern/clocks/utc_clock.py): A clock implementation that returns the system's current datetime/date in UTC. Ideal for production environments.
+- [`clock_pattern.clocks.testing.FixedClock`](https://github.com/adriamontoto/clock-pattern/blob/master/clock_pattern/clocks/testing/fixed_clock.py): A clock that always returns a fixed, preset datetime/date. It is perfect for basic testing as it allows you to control the datetime/date within your test environment, ensuring deterministic results.
+- [`clock_pattern.clocks.testing.MockClock`](https://github.com/adriamontoto/clock-pattern/blob/master/clock_pattern/clocks/testing/mock_clock.py): A clock that allows you to mock the system clock. It is perfect for more complex testing as it allows you to control the datetime/date within your test environment and if or not the methods are called or not.
+<p align="right">
+    <a href="#readme-top">🔼 Back to top</a>
+</p><br><br>
+
+<a name="real-life-case-christmas-detector-service"></a>
+
+## 🎄 Real-Life Case: Christmas Detector Service
+
+Below is an example of a real-life scenario where Clock Pattern can create clean and testable code. We have a `ChristmasDetectorService` that checks if the curren date falls within a specific Christmas holiday range. Using the Clock Pattern, in this case [`UtcClock`](https://github.com/adriamontoto/clock-pattern/blob/master/clock_pattern/clocks/utc_clock.py) and [`MockClock`](https://github.com/adriamontoto/clock-pattern/blob/master/clock_pattern/clocks/testing/mock_clock.py), we can decouple the service from the python `datetime.now()` and `datetime.today()` functions, making it easy to test for different dates without changing the system's time.
+
+```python
+from datetime import date
+
+from clock_pattern import Clock, UtcClock
+from clock_pattern.clocks.testing import MockClock
+
+
+class ChristmasDetectorService:
+    def __init__(self, clock: Clock) -> None:
+        self.clock = clock
+        self.christmas_start = date(year=2024, month=12, day=24)
+        self.christmas_end = date(year=2025, month=1, day=6)
+
+    def is_christmas(self) -> bool:
+        return self.christmas_start <= self.clock.today() <= self.christmas_end
+
+
+clock = UtcClock()
+christmas_detector_service = ChristmasDetectorService(clock=clock)
+
+print(christmas_detector_service.is_christmas())
+# >>> False
+
+
+def test_christmas_detector_is_christmas() -> None:
+    clock = MockClock()
+    christmas_detector_service = ChristmasDetectorService(clock=clock)
+
+    today = date(year=2024, month=12, day=25)
+    clock.prepare_today_method_return_value(today=today)
+
+    assert christmas_detector_service.is_christmas() is True
+    clock.assert_today_method_was_called_once()
+
+
+def test_christmas_detector_is_not_christmas() -> None:
+    clock = MockClock()
+    christmas_detector_service = ChristmasDetectorService(clock=clock)
+
+    today = date(year=2025, month=1, day=7)
+    clock.prepare_today_method_return_value(today=today)
+
+    assert christmas_detector_service.is_christmas() is False
+    clock.assert_today_method_was_called_once()
+```
+
+<p align="right">
+    <a href="#readme-top">🔼 Back to top</a>
+</p><br><br>
+
+<a name="contributing"></a>
+
+## 🤝 Contributing
+
+We love community help! Before you open an issue or pull request, please read:
+
+- [`🤝 How to Contribute`](https://github.com/adriamontoto/clock-pattern/blob/master/.github/CONTRIBUTING.md)
+- [`🧭 Code of Conduct`](https://github.com/adriamontoto/clock-pattern/blob/master/.github/CODE_OF_CONDUCT.md)
+- [`🔐 Security Policy`](https://github.com/adriamontoto/clock-pattern/blob/master/.github/SECURITY.md)
+
+_Thank you for helping make **🕰️ Clock Pattern** package awesome! 🌟_
+
+<p align="right">
+    <a href="#readme-top">🔼 Back to top</a>
+</p><br><br>
+
+<a name="license"></a>
+
+## 🔑 License
+
+This project is licensed under the terms of the [`MIT license`](https://github.com/adriamontoto/clock-pattern/blob/master/LICENSE.md).
+
+<p align="right">
+    <a href="#readme-top">🔼 Back to top</a>
+</p>

clock_pattern-0.5.0/clock_pattern/__init__.py

@@ -0,0 +1,10 @@
+__version__ = '0.5.0'
+
+from .clocks import SystemClock, UtcClock
+from .models import Clock
+
+__all__ = (
+    'Clock',
+    'SystemClock',
+    'UtcClock',
+)

{clock_pattern-0.3.0 → clock_pattern-0.5.0}/clock_pattern/clocks/system_clock.py

@@ -23,7 +23,7 @@ class SystemClock(Clock):
 
     Example:
     ```python
-    from clock_pattern.clocks import SystemClock
+    from clock_pattern import SystemClock
 
     clock = SystemClock()
     print(clock.now())
@@ -48,7 +48,7 @@ class SystemClock(Clock):
 
         Example:
         ```python
-        from clock_pattern.clocks import SystemClock
+        from clock_pattern import SystemClock
 
         clock = SystemClock()
         print(clock.now())
@@ -72,7 +72,7 @@ class SystemClock(Clock):
 
         Example:
         ```python
-        from clock_pattern.clocks import SystemClock
+        from clock_pattern import SystemClock
 
         clock = SystemClock()
         print(clock.now())
@@ -91,7 +91,7 @@ class SystemClock(Clock):
 
         Example:
         ```python
-        from clock_pattern.clocks import SystemClock
+        from clock_pattern import SystemClock
 
         clock = SystemClock()
         print(clock.now())
@@ -110,7 +110,7 @@ class SystemClock(Clock):
 
         Example:
         ```python
-        from clock_pattern.clocks import SystemClock
+        from clock_pattern import SystemClock
 
         clock = SystemClock()
         print(clock.timezone)

clock_pattern-0.5.0/clock_pattern/clocks/testing/__init__.py

@@ -0,0 +1,7 @@
+from .fixed_clock import FixedClock
+from .mock_clock import MockClock
+
+__all__ = (
+    'FixedClock',
+    'MockClock',
+)

clock_pattern-0.5.0/clock_pattern/clocks/testing/mock_clock.py

@@ -0,0 +1,289 @@
+"""
+MockClock module.
+"""
+
+from sys import version_info
+
+if version_info >= (3, 12):
+    from typing import override  # pragma: no cover
+else:
+    from typing_extensions import override  # pragma: no cover
+
+from datetime import UTC, date, datetime
+from unittest.mock import Mock
+
+from value_object_pattern.usables import NotNoneValueObject
+from value_object_pattern.usables.dates import DateValueObject, DatetimeValueObject
+
+from clock_pattern.models.clock import Clock
+
+
+class MockClock(Clock):
+    """
+    MockModel is responsible of mocking Clock class implementation for testing purposes.
+
+    Example:
+    ```python
+    from datetime import datetime
+
+    from clock_pattern.clocks.testing import MockClock
+
+    return_datetime = datetime(year=1999, month=1, day=1)
+    clock = MockClock()
+
+    clock.prepare_now_method_return_value(now=return_datetime)
+    print(clock.now())
+    # >>> 1999-01-01 00:00:00+00:00
+
+    clock.assert_now_method_was_called_once()
+    ```
+    """
+
+    _now_mock: Mock
+    _today_mock: Mock
+    _now_datetime: datetime | None
+    _today_date: date | None
+
+    def __init__(self) -> None:
+        """
+        MockClock constructor.
+
+        Example:
+        ```python
+        from datetime import datetime
+
+        from clock_pattern.clocks.testing import MockClock
+
+        return_datetime = datetime(year=1999, month=1, day=1)
+        clock = MockClock()
+
+        clock.prepare_now_method_return_value(now=return_datetime)
+        print(clock.now())
+        # >>> 1999-01-01 00:00:00+00:00
+
+        clock.assert_now_method_was_called_once()
+        ```
+        """
+        self._now_mock = Mock()
+        self._today_mock = Mock()
+        self._now_datetime = None
+        self._today_date = None
+
+    @override
+    def now(self) -> datetime:
+        """
+        Retrieve the current datetime (now). Use `MockClock.prepare_now_method_return_value` to prepare the return value
+        for this method.
+
+        Raises:
+            TypeError: If `now` method return value is not configured.
+
+        Returns:
+            datetime: The current datetime.
+
+        Example:
+        ```python
+        from datetime import datetime
+
+        from clock_pattern.clocks.testing import MockClock
+
+        return_datetime = datetime(year=1999, month=1, day=1)
+        clock = MockClock()
+
+        clock.prepare_now_method_return_value(now=return_datetime)
+        print(clock.now())
+        # >>> 1999-01-01 00:00:00+00:00
+
+        clock.assert_now_method_was_called_once()
+        ```
+        """
+        NotNoneValueObject(value=self._now_datetime, title='MockClock', parameter='now')
+
+        self._now_mock()
+
+        return self._now_datetime  # type: ignore[return-value]
+
+    def prepare_now_method_return_value(self, *, now: datetime) -> None:
+        """
+        Prepare now method to return the provided datetime `now`. If the provided datetime `now` has not timezone UTC
+        will be set.
+
+        Args:
+            now (datetime): Datetime to return.
+
+        Raises:
+            TypeError: If `now` is not of type datetime.
+
+        Example:
+        ```python
+        from datetime import datetime
+
+        from clock_pattern.clocks.testing import MockClock
+
+        return_datetime = datetime(year=1999, month=1, day=1)
+        clock = MockClock()
+
+        clock.prepare_now_method_return_value(now=return_datetime)
+        print(clock.now())
+        # >>> 1999-01-01 00:00:00+00:00
+
+        clock.assert_now_method_was_called_once()
+        ```
+        """
+        DatetimeValueObject(value=now, title='MockClock', parameter='now')
+
+        if now.tzinfo is None:
+            now = now.replace(tzinfo=UTC)
+
+        self._now_datetime = now
+
+    def assert_now_method_was_called_once(self) -> None:
+        """
+        Assert that the now method was called once.
+
+        Example:
+        ```python
+        from datetime import datetime
+
+        from clock_pattern.clocks.testing import MockClock
+
+        return_datetime = datetime(year=1999, month=1, day=1)
+        clock = MockClock()
+
+        clock.prepare_now_method_return_value(now=return_datetime)
+        print(clock.now())
+        # >>> 1999-01-01 00:00:00+00:00
+
+        clock.assert_now_method_was_called_once()
+        ```
+        """
+        self._now_mock.assert_called_once_with()
+
+    def assert_now_method_was_not_called(self) -> None:
+        """
+        Assert that the now method was not called.
+
+        Example:
+        ```python
+        from datetime import date
+
+        from clock_pattern.clocks.testing import MockClock
+
+        return_date = date(year=1999, month=1, day=1)
+        clock = MockClock()
+
+        clock.prepare_today_method_return_value(today=return_date)
+        print(clock.today())
+        # >>> 2025-06-16
+
+        clock.assert_now_method_was_not_called()
+        ```
+        """
+        self._now_mock.assert_not_called()
+
+    @override
+    def today(self) -> date:
+        """
+        Retrieve the current date (today). Use `MockClock.prepare_today_method_return_value` to prepare the return value
+        for this method.
+
+        Raises:
+            ValueError: If `today` method return value is not configured.
+
+        Returns:
+            date: The current date.
+
+        Example:
+        ```python
+        from datetime import date
+
+        from clock_pattern.clocks.testing import MockClock
+
+        return_date = date(year=1999, month=1, day=1)
+        clock = MockClock()
+
+        clock.prepare_today_method_return_value(today=return_date)
+        print(clock.today())
+        # >>> 2025-06-16
+
+        clock.assert_today_method_was_called_once()
+        ```
+        """
+        NotNoneValueObject(value=self._today_date, title='MockClock', parameter='today')
+
+        self._today_mock()
+
+        return self._today_date  # type: ignore[return-value]
+
+    def prepare_today_method_return_value(self, *, today: date) -> None:
+        """
+        Prepare today method to return the provided date `today`.
+
+        Args:
+            today (date): Date to return.
+
+        Raises:
+            TypeError: If `today` is not of type date.
+
+        Example:
+        ```python
+        from datetime import date
+
+        from clock_pattern.clocks.testing import MockClock
+
+        return_date = date(year=1999, month=1, day=1)
+        clock = MockClock()
+
+        clock.prepare_today_method_return_value(today=return_date)
+        print(clock.today())
+        # >>> 2025-06-16
+
+        clock.assert_today_method_was_called_once()
+        ```
+        """
+        DateValueObject(value=today, title='MockClock', parameter='today')
+        self._today_date = today
+
+    def assert_today_method_was_called_once(self) -> None:
+        """
+        Assert that the today method was called once.
+
+        Example:
+        ```python
+        from datetime import date
+
+        from clock_pattern.clocks.testing import MockClock
+
+        return_date = date(year=1999, month=1, day=1)
+        clock = MockClock()
+
+        clock.prepare_today_method_return_value(today=return_date)
+        print(clock.today())
+        # >>> 2025-06-16
+
+        clock.assert_today_method_was_called_once()
+        ```
+        """
+        self._today_mock.assert_called_once_with()
+
+    def assert_today_method_was_not_called(self) -> None:
+        """
+        Assert that the today method was not called.
+
+        Example:
+        ```python
+        from datetime import datetime
+
+        from clock_pattern.clocks.testing import MockClock
+
+        return_datetime = datetime(year=1999, month=1, day=1)
+        clock = MockClock()
+
+        clock.prepare_now_method_return_value(now=return_datetime)
+        print(clock.now())
+        # >>> 1999-01-01 00:00:00+00:00
+
+        clock.assert_today_method_was_not_called()
+        ```
+        """
+        self._today_mock.assert_not_called()

{clock_pattern-0.3.0 → clock_pattern-0.5.0}/clock_pattern/clocks/utc_clock.py

@@ -13,7 +13,7 @@ class UtcClock(SystemClock):
 
     Example:
     ```python
-    from clock_pattern.clocks import UtcClock
+    from clock_pattern import UtcClock
 
     clock = UtcClock()
     print(clock.now())
@@ -27,7 +27,7 @@ class UtcClock(SystemClock):
 
         Example:
         ```python
-        from clock_pattern.clocks import UtcClock
+        from clock_pattern import UtcClock
 
         clock = UtcClock()
         print(clock.now())

{clock_pattern-0.3.0 → clock_pattern-0.5.0}/clock_pattern/models/clock.py

@@ -14,7 +14,7 @@ class Clock(ABC):
 
     Example:
     ```python
-    from clock_pattern.clocks import SystemClock
+    from clock_pattern import SystemClock
 
     clock = SystemClock()
     print(clock.now())
@@ -32,7 +32,7 @@ class Clock(ABC):
 
         Example:
         ```python
-        from clock_pattern.clocks import SystemClock
+        from clock_pattern import SystemClock
 
         clock = SystemClock()
         print(clock.now())
@@ -50,7 +50,7 @@ class Clock(ABC):
 
         Example:
         ```python
-        from clock_pattern.clocks import SystemClock
+        from clock_pattern import SystemClock
 
         clock = SystemClock()
         print(clock.today())

{clock_pattern-0.3.0 → clock_pattern-0.5.0}/pyproject.toml

@@ -37,7 +37,7 @@ keywords = [
     'domain-driven-design',
 ]
 requires-python = '>=3.11'
-dependencies = ['value-object-pattern>=0.5.0']
+dependencies = ['value-object-pattern>=0.6.0']
 dynamic = ['version']
 
 [project.urls]

clock_pattern-0.3.0/PKG-INFO

@@ -1,95 +0,0 @@
-Metadata-Version: 2.4
-Name: clock-pattern
-Version: 0.3.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
-Project-URL: Issues, https://github.com/adriamontoto/clock-pattern/issues
-Author: Adria Montoto
-License-Expression: MIT
-License-File: LICENSE.md
-Keywords: clock,dependency-injection,development,domain-driven-design,pattern,python,utilities
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Typing :: Typed
-Requires-Python: >=3.11
-Requires-Dist: value-object-pattern>=0.5.0
-Description-Content-Type: text/markdown
-
-<a name="readme-top"></a>
-
-# 🕰️ Clock Pattern
-
-<p align="center">
-    <a href="https://github.com/adriamontoto/clock-pattern/actions/workflows/ci.yaml?event=push&branch=master" target="_blank">
-        <img src="https://github.com/adriamontoto/clock-pattern/actions/workflows/ci.yaml/badge.svg?event=push&branch=master" alt="CI Pipeline">
-    </a>
-        <a href="https://coverage-badge.samuelcolvin.workers.dev/redirect/adriamontoto/clock-pattern" target="_blank">
-        <img src="https://coverage-badge.samuelcolvin.workers.dev/adriamontoto/clock-pattern.svg" alt="Coverage Pipeline">
-    </a>
-    <a href="https://pypi.org/project/clock-pattern" target="_blank">
-        <img src="https://img.shields.io/pypi/v/clock-pattern?color=%2334D058&label=pypi%20package" alt="Package Version">
-    </a>
-    <a href="https://pypi.org/project/clock-pattern/" target="_blank">
-        <img src="https://img.shields.io/pypi/pyversions/clock-pattern.svg?color=%2334D058" alt="Supported Python Versions">
-    </a>
-</p>
-
-The **Clock Pattern** is a Python 🐍 package that turns time into an injectable dependency 🧩. By replacing ad-hoc datetime.now() calls with a swappable Clock interface 🕰️ you unlock deterministic tests 🧪, decouple business logic from the OS clock, and gain the freedom to swap in high-precision or logical clocks without touching domain code.
-<br><br>
-
-## Table of Contents
-
-- [📥 Installation](#installation)
-- [🤝 Contributing](#contributing)
-- [🔑 License](#license)
-
-<p align="right">
-    <a href="#readme-top">🔼 Back to top</a>
-</p><br><br>
-
-<a name="installation"></a>
-
-## 📥 Installation
-
-You can install **Clock Pattern** using `pip`:
-
-```bash
-pip install clock-pattern
-```
-
-<p align="right">
-    <a href="#readme-top">🔼 Back to top</a>
-</p><br><br>
-
-<a name="contributing"></a>
-
-## 🤝 Contributing
-
-We love community help! Before you open an issue or pull request, please read:
-
-- [`🤝 How to Contribute`](https://github.com/adriamontoto/clock-pattern/blob/master/.github/CONTRIBUTING.md)
-- [`🧭 Code of Conduct`](https://github.com/adriamontoto/clock-pattern/blob/master/.github/CODE_OF_CONDUCT.md)
-- [`🔐 Security Policy`](https://github.com/adriamontoto/clock-pattern/blob/master/.github/SECURITY.md)
-
-_Thank you for helping make **🕰️ Clock Pattern** package awesome! 🌟_
-
-<p align="right">
-    <a href="#readme-top">🔼 Back to top</a>
-</p><br><br>
-
-<a name="license"></a>
-
-## 🔑 License
-
-This project is licensed under the terms of the [`MIT license`](https://github.com/adriamontoto/clock-pattern/blob/master/LICENSE.md).
-
-<p align="right">
-    <a href="#readme-top">🔼 Back to top</a>
-</p>

clock_pattern-0.3.0/README.md

@@ -1,71 +0,0 @@
-<a name="readme-top"></a>
-
-# 🕰️ Clock Pattern
-
-<p align="center">
-    <a href="https://github.com/adriamontoto/clock-pattern/actions/workflows/ci.yaml?event=push&branch=master" target="_blank">
-        <img src="https://github.com/adriamontoto/clock-pattern/actions/workflows/ci.yaml/badge.svg?event=push&branch=master" alt="CI Pipeline">
-    </a>
-        <a href="https://coverage-badge.samuelcolvin.workers.dev/redirect/adriamontoto/clock-pattern" target="_blank">
-        <img src="https://coverage-badge.samuelcolvin.workers.dev/adriamontoto/clock-pattern.svg" alt="Coverage Pipeline">
-    </a>
-    <a href="https://pypi.org/project/clock-pattern" target="_blank">
-        <img src="https://img.shields.io/pypi/v/clock-pattern?color=%2334D058&label=pypi%20package" alt="Package Version">
-    </a>
-    <a href="https://pypi.org/project/clock-pattern/" target="_blank">
-        <img src="https://img.shields.io/pypi/pyversions/clock-pattern.svg?color=%2334D058" alt="Supported Python Versions">
-    </a>
-</p>
-
-The **Clock Pattern** is a Python 🐍 package that turns time into an injectable dependency 🧩. By replacing ad-hoc datetime.now() calls with a swappable Clock interface 🕰️ you unlock deterministic tests 🧪, decouple business logic from the OS clock, and gain the freedom to swap in high-precision or logical clocks without touching domain code.
-<br><br>
-
-## Table of Contents
-
-- [📥 Installation](#installation)
-- [🤝 Contributing](#contributing)
-- [🔑 License](#license)
-
-<p align="right">
-    <a href="#readme-top">🔼 Back to top</a>
-</p><br><br>
-
-<a name="installation"></a>
-
-## 📥 Installation
-
-You can install **Clock Pattern** using `pip`:
-
-```bash
-pip install clock-pattern
-```
-
-<p align="right">
-    <a href="#readme-top">🔼 Back to top</a>
-</p><br><br>
-
-<a name="contributing"></a>
-
-## 🤝 Contributing
-
-We love community help! Before you open an issue or pull request, please read:
-
-- [`🤝 How to Contribute`](https://github.com/adriamontoto/clock-pattern/blob/master/.github/CONTRIBUTING.md)
-- [`🧭 Code of Conduct`](https://github.com/adriamontoto/clock-pattern/blob/master/.github/CODE_OF_CONDUCT.md)
-- [`🔐 Security Policy`](https://github.com/adriamontoto/clock-pattern/blob/master/.github/SECURITY.md)
-
-_Thank you for helping make **🕰️ Clock Pattern** package awesome! 🌟_
-
-<p align="right">
-    <a href="#readme-top">🔼 Back to top</a>
-</p><br><br>
-
-<a name="license"></a>
-
-## 🔑 License
-
-This project is licensed under the terms of the [`MIT license`](https://github.com/adriamontoto/clock-pattern/blob/master/LICENSE.md).
-
-<p align="right">
-    <a href="#readme-top">🔼 Back to top</a>
-</p>

clock_pattern-0.3.0/clock_pattern/__init__.py

@@ -1 +0,0 @@
-__version__ = '0.3.0'

clock_pattern-0.3.0/clock_pattern/clocks/testing/__init__.py

@@ -1,3 +0,0 @@
-from .fixed_clock import FixedClock
-
-__all__ = ('FixedClock',)