clock-pattern 0.1.0__tar.gz

clock_pattern-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+# linting files
+.coverage
+
+# cache files/folders
+**cache**
+
+# build and distribution files/folders
+**dist**
+**build**
+
+# environment folders
+**.venv**

clock_pattern-0.1.0/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.

clock_pattern-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,71 @@
+<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/clock_pattern/__init__.py

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

clock_pattern-0.1.0/clock_pattern/clocks/__init__.py

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

clock_pattern-0.1.0/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-0.1.0/clock_pattern/models/__init__.py

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

clock_pattern-0.1.0/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/pyproject.toml

@@ -0,0 +1,208 @@
+[build-system]
+requires = ['hatchling']
+build-backend = 'hatchling.build'
+
+
+[tool.hatch.version]
+path = 'clock_pattern/__init__.py'
+
+[tool.hatch.build.targets.sdist]
+include = ['clock_pattern/']
+
+
+[project]
+name = 'clock-pattern'
+description = 'The Clock Pattern is a Python package that turns time into an injectable dependency.'
+readme = './README.md'
+authors = [{ name = 'Adria Montoto' }]
+license = 'MIT'
+classifiers = [
+    'License :: OSI Approved :: MIT License',
+    'Intended Audience :: Developers',
+    'Operating System :: OS Independent',
+    'Typing :: Typed',
+    'Programming Language :: Python',
+    'Programming Language :: Python :: 3',
+    'Programming Language :: Python :: 3.11',
+    'Programming Language :: Python :: 3.12',
+    'Programming Language :: Python :: 3.13',
+]
+keywords = [
+    'python',
+    'development',
+    'utilities',
+    'clock',
+    'pattern',
+    'dependency-injection',
+    'domain-driven-design',
+]
+requires-python = '>=3.11'
+dependencies = ['value-object-pattern>=0.5.0']
+dynamic = ['version']
+
+[project.urls]
+Homepage = 'https://github.com/adriamontoto/clock-pattern'
+Repository = 'https://github.com/adriamontoto/clock-pattern'
+Issues = 'https://github.com/adriamontoto/clock-pattern/issues'
+
+
+[dependency-groups]
+audit = ['pip-audit>=2.9.0']
+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', 'mypy[reports]>=1.0.0', { include-group = 'test' }]
+release = ['build>=1.2.2', 'python-semantic-release>=10.0.2']
+test = [
+    'pytest>=8.0.0',
+    'pytest-randomly>=3.0.0',
+    'object-mother-pattern>=2.1.0',
+    { include-group = 'coverage' },
+]
+all = [
+    { include-group = 'audit' },
+    { include-group = 'coverage' },
+    { include-group = 'develop' },
+    { include-group = 'format' },
+    { include-group = 'lint' },
+    { include-group = 'release' },
+    { include-group = 'test' },
+]
+
+
+[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
+]
+markers = ['unit_testing: Check a unique functionality']
+xfail_strict = true
+
+
+[tool.coverage.run]
+source = ['clock_pattern']
+parallel = true
+branch = true
+relative_files = true
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = true
+precision = 2
+exclude_lines = [
+    'pragma: no cover',
+    'raise NotImplementedError',
+    'if TYPE_CHECKING:',
+    'if typing.TYPE_CHECKING:',
+    '@overload',
+    '@typing.overload',
+    'typing.assert_never',
+    'assert_never',
+]
+
+[tool.coverage.paths]
+source = ['clock_pattern']
+
+
+[tool.ruff]
+indent-width = 4
+line-length = 120
+target-version = 'py313'
+output-format = 'grouped'
+
+[tool.ruff.format]
+docstring-code-format = true
+docstring-code-line-length = 120
+indent-style = 'space'
+quote-style = 'single'
+skip-magic-trailing-comma = false
+
+[tool.ruff.lint]
+select = [
+    'F',    # pyflakes
+    'S',    # flake8-bandit
+    'B',    # flake8-bugbear
+    'DTZ',  # flake8-datetimez
+    'C4',   # flake8-comprehensions
+    'SIM',  # flake8-simplify
+    'I',    # isort
+    'C90',  # mccabe
+    'N',    # pep8-naming
+    'PERF', # perflint
+    'E',    # pycodestyle
+    'W',    # pycodestyle
+    'D',    # pydocstyle
+    'UP',   # pyupgrade
+    'RUF',  # ruff
+]
+ignore = [
+    'UP035',  # Checks for uses of deprecated imports based on the minimum supported Python version.
+    'UP036',  # Checks for conditional blocks gated on sys.version_info comparisons that are outdated for the minimum supported Python version.
+    'E111',   # Checks for indentation with a non-multiple of 4 spaces.
+    'E114',   # Checks for indentation of comments with a non-multiple of 4 spaces.
+    'E117',   # Checks for over-indented code.
+    'W191',   # Checks for indentation that uses tabs.
+    'D200',   # Checks for single-line docstrings that are broken across multiple lines.
+    'D205',   # 1 blank line required between summary line and description.
+    'D206',   # Checks for docstrings that are indented with tabs.
+    'D212',   # Checks for docstring summary lines that are not positioned on the first physical line of the docstring.
+    'D401',   # First line of docstring should be in imperative mood.
+    'D300',   # Checks for docstrings that use '''triple single quotes''' instead of 'triple double quotes'.
+    'RUF100', # Checks for unused noqa directives.
+]
+
+[tool.ruff.lint.per-file-ignores]
+'__init__.py' = [
+    'F401', # Checks for unused imports.
+    'D104', # Checks for undocumented public package definitions.
+]
+'**test**.py' = [
+    'S101', # Use of `assert` detected.
+]
+
+[tool.ruff.lint.mccabe]
+max-complexity = 10
+
+[tool.ruff.lint.pydocstyle]
+convention = 'pep257'
+
+[tool.ruff.lint.isort]
+case-sensitive = true
+known-first-party = ['clock_pattern']
+combine-as-imports = true
+
+
+[tool.mypy]
+strict = true
+warn_unreachable = true
+enable_error_code = [
+    'redundant-expr',
+    'possibly-undefined',
+    'truthy-bool',
+    'explicit-override',
+]
+
+
+[tool.semantic_release]
+allow_zero_version = true
+commit_message = 'bump: new version {version} released'
+commit_parser = 'conventional'
+major_on_zero = true
+no_git_verify = false
+tag_format = 'v{version}'
+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']
+default_bump_level = 0
+parse_squash_commits = false
+ignore_merge_commits = true
+
+[tool.semantic_release.changelog]
+template_dir = 'docs/changelog_template'
+mode = 'update'
+exclude_commit_patterns = ['''Merged? .*''']