clock-pattern 0.1.0__py3-none-any.whl

clock_pattern/__init__.py

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

clock_pattern/clocks/__init__.py

@@ -0,0 +1,3 @@
+from .system_clock import SystemClock
+
+__all__ = ('SystemClock',)

clock_pattern/clocks/system_clock.py

@@ -0,0 +1,120 @@
+"""
+SystemClock 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, tzinfo
+from zoneinfo import ZoneInfo
+
+from value_object_pattern.usables.dates import StringTimezoneValueObject, TimezoneValueObject
+
+from clock_pattern.models.clock import Clock
+
+
+class SystemClock(Clock):
+    """
+    SystemClock class is responsible of retrieving the current date/datetime with the provided timezone.
+
+    Example:
+    ```python
+    from clock_pattern.clocks import SystemClock
+
+    clock = SystemClock()
+    print(clock.now())
+    # >>> 2025-06-16 13:57:26.210964+00:00
+    ```
+    """
+
+    _timezone: tzinfo
+
+    def __init__(self, *, timezone: str | tzinfo = UTC) -> None:
+        """
+        SystemClock constructor is responsible to store which `timezone` the user wants to use when retrieving the
+        current date/datetime.
+
+        Args:
+            timezone: (str | tzinfo, optional): Timezone of the date/datetime to retrieve. Default to UTC.
+
+        Raises:
+            TypeError: If `timezone` is not of type tzinfo.
+            TypeError: If `timezone` is not of type string.
+            ValueError: If `timezone` is not a valid timezone.
+
+        Example:
+        ```python
+        from clock_pattern.clocks import SystemClock
+
+        clock = SystemClock()
+        print(clock.now())
+        # >>> 2025-06-16 13:57:26.210964+00:00
+        ```
+        """
+        if isinstance(timezone, tzinfo):
+            timezone = str(TimezoneValueObject(value=timezone, title='SystemClock', parameter='timezone'))
+
+        StringTimezoneValueObject(value=timezone, title='SystemClock', parameter='timezone')
+
+        self._timezone = ZoneInfo(timezone)
+
+    @override
+    def now(self) -> datetime:
+        """
+        Retrieve the current datetime (now).
+
+        Returns:
+            datetime: The current datetime.
+
+        Example:
+        ```python
+        from clock_pattern.clocks import SystemClock
+
+        clock = SystemClock()
+        print(clock.now())
+        # >>> 2025-06-16 13:57:26.210964+00:00
+        ```
+        """
+        return datetime.now(tz=self._timezone)
+
+    @override
+    def today(self) -> date:
+        """
+        Retrieve the current date (today).
+
+        Returns:
+            date: The current date.
+
+        Example:
+        ```python
+        from clock_pattern.clocks import SystemClock
+
+        clock = SystemClock()
+        print(clock.now())
+        # >>> 2025-06-16
+        ```
+        """
+        return datetime.now(tz=self._timezone).date()
+
+    @property
+    def timezone(self) -> tzinfo:
+        """
+        Retrieve the timezone of the clock.
+
+        Returns:
+            tzinfo: The timezone of the clock.
+
+        Example:
+        ```python
+        from clock_pattern.clocks import SystemClock
+
+        clock = SystemClock()
+        print(clock.timezone)
+        # >>> UTC
+        ```
+        """
+        return self._timezone

clock_pattern/models/__init__.py

@@ -0,0 +1,3 @@
+from .clock import Clock
+
+__all__ = ('Clock',)

clock_pattern/models/clock.py

@@ -0,0 +1,59 @@
+"""
+Clock module.
+"""
+
+from abc import ABC, abstractmethod
+from datetime import date, datetime
+
+
+class Clock(ABC):
+    """
+    Clock class.
+
+    ***This class is abstract and should not be instantiated directly***.
+
+    Example:
+    ```python
+    from clock_pattern.clocks import SystemClock
+
+    clock = SystemClock()
+    print(clock.now())
+    # >>> 2025-06-16 13:57:26.210964+00:00
+    ```
+    """
+
+    @abstractmethod
+    def now(self) -> datetime:
+        """
+        Retrieve the current datetime (now).
+
+        Returns:
+            datetime: The current datetime.
+
+        Example:
+        ```python
+        from clock_pattern.clocks import SystemClock
+
+        clock = SystemClock()
+        print(clock.now())
+        # >>> 2025-06-16 13:57:26.210964+00:00
+        ```
+        """
+
+    @abstractmethod
+    def today(self) -> date:
+        """
+        Retrieve the current date (today).
+
+        Returns:
+            date: The current date.
+
+        Example:
+        ```python
+        from clock_pattern.clocks import SystemClock
+
+        clock = SystemClock()
+        print(clock.today())
+        # >>> 2025-06-16
+        ```
+        """

clock_pattern-0.1.0.dist-info/METADATA

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: clock-pattern
+Version: 0.1.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.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+clock_pattern/__init__.py,sha256=IMjkMO3twhQzluVTo8Z6rE7Eg-9U79_LGKMcsWLKBkY,22
+clock_pattern/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+clock_pattern/clocks/__init__.py,sha256=5D4k3fSqGGN_cvIXHs4lqL7pMItbeIMDKQ930nz9ztk,66
+clock_pattern/clocks/system_clock.py,sha256=JmUdwVu9gAfH84-JY-suQUClvR8JMuujF84lccJ-BP0,3055
+clock_pattern/models/__init__.py,sha256=Q3O6MR-aEh4SeDQY4Tgsy24i-Ne4ZSQL4HY5rIhOCe8,47
+clock_pattern/models/clock.py,sha256=RUb2TNy4BAOne1GdAZ4DlTRhfGzjco6E9NY-u-O654o,1147
+clock_pattern-0.1.0.dist-info/METADATA,sha256=ww1foUF6BP19i7W1jfrZMjZY_cJv_Z-92Rz5JwE068A,3723
+clock_pattern-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+clock_pattern-0.1.0.dist-info/licenses/LICENSE.md,sha256=k3Sxbijlj46RildqRYKoeS0MNBAMcIOMdlixIyMxZ74,1071
+clock_pattern-0.1.0.dist-info/RECORD,,

clock_pattern-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

clock_pattern-0.1.0.dist-info/licenses/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) (2025) adriamontoto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.