clock-pattern 0.4.0__tar.gz → 0.6.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (18) hide show
  1. clock_pattern-0.6.0/PKG-INFO +208 -0
  2. clock_pattern-0.6.0/README.md +183 -0
  3. clock_pattern-0.6.0/clock_pattern/__init__.py +10 -0
  4. {clock_pattern-0.4.0 → clock_pattern-0.6.0}/clock_pattern/clocks/system_clock.py +5 -5
  5. {clock_pattern-0.4.0 → clock_pattern-0.6.0}/clock_pattern/clocks/utc_clock.py +2 -2
  6. {clock_pattern-0.4.0 → clock_pattern-0.6.0}/clock_pattern/models/clock.py +3 -3
  7. {clock_pattern-0.4.0 → clock_pattern-0.6.0}/pyproject.toml +1 -0
  8. clock_pattern-0.4.0/PKG-INFO +0 -95
  9. clock_pattern-0.4.0/README.md +0 -71
  10. clock_pattern-0.4.0/clock_pattern/__init__.py +0 -1
  11. {clock_pattern-0.4.0 → clock_pattern-0.6.0}/.gitignore +0 -0
  12. {clock_pattern-0.4.0 → clock_pattern-0.6.0}/LICENSE.md +0 -0
  13. {clock_pattern-0.4.0 → clock_pattern-0.6.0}/clock_pattern/clocks/__init__.py +0 -0
  14. {clock_pattern-0.4.0 → clock_pattern-0.6.0}/clock_pattern/clocks/testing/__init__.py +0 -0
  15. {clock_pattern-0.4.0 → clock_pattern-0.6.0}/clock_pattern/clocks/testing/fixed_clock.py +0 -0
  16. {clock_pattern-0.4.0 → clock_pattern-0.6.0}/clock_pattern/clocks/testing/mock_clock.py +0 -0
  17. {clock_pattern-0.4.0 → clock_pattern-0.6.0}/clock_pattern/models/__init__.py +0 -0
  18. {clock_pattern-0.4.0 → clock_pattern-0.6.0}/clock_pattern/py.typed +0 -0
clock_pattern-0.6.0/PKG-INFO ADDED
@@ -0,0 +1,208 @@
1
+ Metadata-Version: 2.4
2
+ Name: clock-pattern
3
+ Version: 0.6.0
4
+ Summary: The Clock Pattern is a Python package that turns time into an injectable dependency.
5
+ Project-URL: Homepage, https://github.com/adriamontoto/clock-pattern
6
+ Project-URL: Repository, https://github.com/adriamontoto/clock-pattern
7
+ Project-URL: Issues, https://github.com/adriamontoto/clock-pattern/issues
8
+ Author: Adria Montoto
9
+ License-Expression: MIT
10
+ License-File: LICENSE.md
11
+ Keywords: clock,dependency-injection,development,domain-driven-design,pattern,python,utilities
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: License :: OSI Approved :: MIT License
14
+ Classifier: Operating System :: OS Independent
15
+ Classifier: Programming Language :: Python
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Programming Language :: Python :: 3.14
21
+ Classifier: Typing :: Typed
22
+ Requires-Python: >=3.11
23
+ Requires-Dist: value-object-pattern>=0.6.0
24
+ Description-Content-Type: text/markdown
25
+
26
+ <a name="readme-top"></a>
27
+
28
+ # 🕰️ Clock Pattern
29
+
30
+ <p align="center">
31
+ <a href="https://github.com/adriamontoto/clock-pattern/actions/workflows/ci.yaml?event=push&branch=master" target="_blank">
32
+ <img src="https://github.com/adriamontoto/clock-pattern/actions/workflows/ci.yaml/badge.svg?event=push&branch=master" alt="CI Pipeline">
33
+ </a>
34
+ <a href="https://coverage-badge.samuelcolvin.workers.dev/redirect/adriamontoto/clock-pattern" target="_blank">
35
+ <img src="https://coverage-badge.samuelcolvin.workers.dev/adriamontoto/clock-pattern.svg" alt="Coverage Pipeline">
36
+ </a>
37
+ <a href="https://pypi.org/project/clock-pattern" target="_blank">
38
+ <img src="https://img.shields.io/pypi/v/clock-pattern?color=%2334D058&label=pypi%20package" alt="Package Version">
39
+ </a>
40
+ <a href="https://pypi.org/project/clock-pattern/" target="_blank">
41
+ <img src="https://img.shields.io/pypi/pyversions/clock-pattern.svg?color=%2334D058" alt="Supported Python Versions">
42
+ </a>
43
+ <a href="https://pepy.tech/projects/clock-pattern" target="_blank">
44
+ <img src="https://static.pepy.tech/badge/clock-pattern/month" alt="Package Downloads">
45
+ </a>
46
+ <a href="https://deepwiki.com/adriamontoto/clock-pattern" target="_blank">
47
+ <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">
48
+ </a>
49
+ </p>
50
+
51
+ 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.
52
+ <br><br>
53
+
54
+ ## Table of Contents
55
+
56
+ - [📥 Installation](#installation)
57
+ - [📚 Documentation](#documentation)
58
+ - [💻 Utilization](#utilization)
59
+ - [📚 Available Clocks](#available-clocks)
60
+ - [🎄 Real-Life Case: Christmas Detector Service](#real-life-case-christmas-detector-service)
61
+ - [🤝 Contributing](#contributing)
62
+ - [🔑 License](#license)
63
+
64
+ <p align="right">
65
+ <a href="#readme-top">🔼 Back to top</a>
66
+ </p><br><br>
67
+
68
+ <a name="installation"></a>
69
+
70
+ ## 📥 Installation
71
+
72
+ You can install **Clock Pattern** using `pip`:
73
+
74
+ ```bash
75
+ pip install clock-pattern
76
+ ```
77
+
78
+ <p align="right">
79
+ <a href="#readme-top">🔼 Back to top</a>
80
+ </p><br><br>
81
+
82
+ <a name="documentation"></a>
83
+
84
+ ## 📚 Documentation
85
+
86
+ This [project's documentation](https://deepwiki.com/adriamontoto/clock-pattern) is powered by DeepWiki, which provides a comprehensive overview of the **Clock Pattern** and its usage.
87
+
88
+ <p align="right">
89
+ <a href="#readme-top">🔼 Back to top</a>
90
+ </p><br><br>
91
+
92
+ <a name="utilization"></a>
93
+
94
+ ## 💻 Utilization
95
+
96
+ 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.
97
+
98
+ 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:
99
+
100
+ ```python
101
+ from datetime import timezone
102
+
103
+ from clock_pattern import SystemClock
104
+
105
+ clock = SystemClock(timezone=timezone.utc)
106
+ print(clock.now())
107
+ # >>> 2025-06-16 13:57:26.210964+00:00
108
+ ```
109
+
110
+ <p align="right">
111
+ <a href="#readme-top">🔼 Back to top</a>
112
+ </p><br><br>
113
+
114
+ <a name="available-clocks"></a>
115
+
116
+ ## 📚 Available Clocks
117
+
118
+ The package offers several clock implementations to suit different needs:
119
+
120
+ - [`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.
121
+ - [`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.
122
+ - [`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.
123
+ - [`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.
124
+ <p align="right">
125
+ <a href="#readme-top">🔼 Back to top</a>
126
+ </p><br><br>
127
+
128
+ <a name="real-life-case-christmas-detector-service"></a>
129
+
130
+ ## 🎄 Real-Life Case: Christmas Detector Service
131
+
132
+ 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.
133
+
134
+ ```python
135
+ from datetime import date
136
+
137
+ from clock_pattern import Clock, UtcClock
138
+ from clock_pattern.clocks.testing import MockClock
139
+
140
+
141
+ class ChristmasDetectorService:
142
+ def __init__(self, clock: Clock) -> None:
143
+ self.clock = clock
144
+ self.christmas_start = date(year=2024, month=12, day=24)
145
+ self.christmas_end = date(year=2025, month=1, day=6)
146
+
147
+ def is_christmas(self) -> bool:
148
+ return self.christmas_start <= self.clock.today() <= self.christmas_end
149
+
150
+
151
+ clock = UtcClock()
152
+ christmas_detector_service = ChristmasDetectorService(clock=clock)
153
+
154
+ print(christmas_detector_service.is_christmas())
155
+ # >>> False
156
+
157
+
158
+ def test_christmas_detector_is_christmas() -> None:
159
+ clock = MockClock()
160
+ christmas_detector_service = ChristmasDetectorService(clock=clock)
161
+
162
+ today = date(year=2024, month=12, day=25)
163
+ clock.prepare_today_method_return_value(today=today)
164
+
165
+ assert christmas_detector_service.is_christmas() is True
166
+ clock.assert_today_method_was_called_once()
167
+
168
+
169
+ def test_christmas_detector_is_not_christmas() -> None:
170
+ clock = MockClock()
171
+ christmas_detector_service = ChristmasDetectorService(clock=clock)
172
+
173
+ today = date(year=2025, month=1, day=7)
174
+ clock.prepare_today_method_return_value(today=today)
175
+
176
+ assert christmas_detector_service.is_christmas() is False
177
+ clock.assert_today_method_was_called_once()
178
+ ```
179
+
180
+ <p align="right">
181
+ <a href="#readme-top">🔼 Back to top</a>
182
+ </p><br><br>
183
+
184
+ <a name="contributing"></a>
185
+
186
+ ## 🤝 Contributing
187
+
188
+ We love community help! Before you open an issue or pull request, please read:
189
+
190
+ - [`🤝 How to Contribute`](https://github.com/adriamontoto/clock-pattern/blob/master/.github/CONTRIBUTING.md)
191
+ - [`🧭 Code of Conduct`](https://github.com/adriamontoto/clock-pattern/blob/master/.github/CODE_OF_CONDUCT.md)
192
+ - [`🔐 Security Policy`](https://github.com/adriamontoto/clock-pattern/blob/master/.github/SECURITY.md)
193
+
194
+ _Thank you for helping make **🕰️ Clock Pattern** package awesome! 🌟_
195
+
196
+ <p align="right">
197
+ <a href="#readme-top">🔼 Back to top</a>
198
+ </p><br><br>
199
+
200
+ <a name="license"></a>
201
+
202
+ ## 🔑 License
203
+
204
+ This project is licensed under the terms of the [`MIT license`](https://github.com/adriamontoto/clock-pattern/blob/master/LICENSE.md).
205
+
206
+ <p align="right">
207
+ <a href="#readme-top">🔼 Back to top</a>
208
+ </p>
clock_pattern-0.6.0/README.md ADDED
@@ -0,0 +1,183 @@
1
+ <a name="readme-top"></a>
2
+
3
+ # 🕰️ Clock Pattern
4
+
5
+ <p align="center">
6
+ <a href="https://github.com/adriamontoto/clock-pattern/actions/workflows/ci.yaml?event=push&branch=master" target="_blank">
7
+ <img src="https://github.com/adriamontoto/clock-pattern/actions/workflows/ci.yaml/badge.svg?event=push&branch=master" alt="CI Pipeline">
8
+ </a>
9
+ <a href="https://coverage-badge.samuelcolvin.workers.dev/redirect/adriamontoto/clock-pattern" target="_blank">
10
+ <img src="https://coverage-badge.samuelcolvin.workers.dev/adriamontoto/clock-pattern.svg" alt="Coverage Pipeline">
11
+ </a>
12
+ <a href="https://pypi.org/project/clock-pattern" target="_blank">
13
+ <img src="https://img.shields.io/pypi/v/clock-pattern?color=%2334D058&label=pypi%20package" alt="Package Version">
14
+ </a>
15
+ <a href="https://pypi.org/project/clock-pattern/" target="_blank">
16
+ <img src="https://img.shields.io/pypi/pyversions/clock-pattern.svg?color=%2334D058" alt="Supported Python Versions">
17
+ </a>
18
+ <a href="https://pepy.tech/projects/clock-pattern" target="_blank">
19
+ <img src="https://static.pepy.tech/badge/clock-pattern/month" alt="Package Downloads">
20
+ </a>
21
+ <a href="https://deepwiki.com/adriamontoto/clock-pattern" target="_blank">
22
+ <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">
23
+ </a>
24
+ </p>
25
+
26
+ 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.
27
+ <br><br>
28
+
29
+ ## Table of Contents
30
+
31
+ - [📥 Installation](#installation)
32
+ - [📚 Documentation](#documentation)
33
+ - [💻 Utilization](#utilization)
34
+ - [📚 Available Clocks](#available-clocks)
35
+ - [🎄 Real-Life Case: Christmas Detector Service](#real-life-case-christmas-detector-service)
36
+ - [🤝 Contributing](#contributing)
37
+ - [🔑 License](#license)
38
+
39
+ <p align="right">
40
+ <a href="#readme-top">🔼 Back to top</a>
41
+ </p><br><br>
42
+
43
+ <a name="installation"></a>
44
+
45
+ ## 📥 Installation
46
+
47
+ You can install **Clock Pattern** using `pip`:
48
+
49
+ ```bash
50
+ pip install clock-pattern
51
+ ```
52
+
53
+ <p align="right">
54
+ <a href="#readme-top">🔼 Back to top</a>
55
+ </p><br><br>
56
+
57
+ <a name="documentation"></a>
58
+
59
+ ## 📚 Documentation
60
+
61
+ This [project's documentation](https://deepwiki.com/adriamontoto/clock-pattern) is powered by DeepWiki, which provides a comprehensive overview of the **Clock Pattern** and its usage.
62
+
63
+ <p align="right">
64
+ <a href="#readme-top">🔼 Back to top</a>
65
+ </p><br><br>
66
+
67
+ <a name="utilization"></a>
68
+
69
+ ## 💻 Utilization
70
+
71
+ 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.
72
+
73
+ 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:
74
+
75
+ ```python
76
+ from datetime import timezone
77
+
78
+ from clock_pattern import SystemClock
79
+
80
+ clock = SystemClock(timezone=timezone.utc)
81
+ print(clock.now())
82
+ # >>> 2025-06-16 13:57:26.210964+00:00
83
+ ```
84
+
85
+ <p align="right">
86
+ <a href="#readme-top">🔼 Back to top</a>
87
+ </p><br><br>
88
+
89
+ <a name="available-clocks"></a>
90
+
91
+ ## 📚 Available Clocks
92
+
93
+ The package offers several clock implementations to suit different needs:
94
+
95
+ - [`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.
96
+ - [`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.
97
+ - [`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.
98
+ - [`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.
99
+ <p align="right">
100
+ <a href="#readme-top">🔼 Back to top</a>
101
+ </p><br><br>
102
+
103
+ <a name="real-life-case-christmas-detector-service"></a>
104
+
105
+ ## 🎄 Real-Life Case: Christmas Detector Service
106
+
107
+ 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.
108
+
109
+ ```python
110
+ from datetime import date
111
+
112
+ from clock_pattern import Clock, UtcClock
113
+ from clock_pattern.clocks.testing import MockClock
114
+
115
+
116
+ class ChristmasDetectorService:
117
+ def __init__(self, clock: Clock) -> None:
118
+ self.clock = clock
119
+ self.christmas_start = date(year=2024, month=12, day=24)
120
+ self.christmas_end = date(year=2025, month=1, day=6)
121
+
122
+ def is_christmas(self) -> bool:
123
+ return self.christmas_start <= self.clock.today() <= self.christmas_end
124
+
125
+
126
+ clock = UtcClock()
127
+ christmas_detector_service = ChristmasDetectorService(clock=clock)
128
+
129
+ print(christmas_detector_service.is_christmas())
130
+ # >>> False
131
+
132
+
133
+ def test_christmas_detector_is_christmas() -> None:
134
+ clock = MockClock()
135
+ christmas_detector_service = ChristmasDetectorService(clock=clock)
136
+
137
+ today = date(year=2024, month=12, day=25)
138
+ clock.prepare_today_method_return_value(today=today)
139
+
140
+ assert christmas_detector_service.is_christmas() is True
141
+ clock.assert_today_method_was_called_once()
142
+
143
+
144
+ def test_christmas_detector_is_not_christmas() -> None:
145
+ clock = MockClock()
146
+ christmas_detector_service = ChristmasDetectorService(clock=clock)
147
+
148
+ today = date(year=2025, month=1, day=7)
149
+ clock.prepare_today_method_return_value(today=today)
150
+
151
+ assert christmas_detector_service.is_christmas() is False
152
+ clock.assert_today_method_was_called_once()
153
+ ```
154
+
155
+ <p align="right">
156
+ <a href="#readme-top">🔼 Back to top</a>
157
+ </p><br><br>
158
+
159
+ <a name="contributing"></a>
160
+
161
+ ## 🤝 Contributing
162
+
163
+ We love community help! Before you open an issue or pull request, please read:
164
+
165
+ - [`🤝 How to Contribute`](https://github.com/adriamontoto/clock-pattern/blob/master/.github/CONTRIBUTING.md)
166
+ - [`🧭 Code of Conduct`](https://github.com/adriamontoto/clock-pattern/blob/master/.github/CODE_OF_CONDUCT.md)
167
+ - [`🔐 Security Policy`](https://github.com/adriamontoto/clock-pattern/blob/master/.github/SECURITY.md)
168
+
169
+ _Thank you for helping make **🕰️ Clock Pattern** package awesome! 🌟_
170
+
171
+ <p align="right">
172
+ <a href="#readme-top">🔼 Back to top</a>
173
+ </p><br><br>
174
+
175
+ <a name="license"></a>
176
+
177
+ ## 🔑 License
178
+
179
+ This project is licensed under the terms of the [`MIT license`](https://github.com/adriamontoto/clock-pattern/blob/master/LICENSE.md).
180
+
181
+ <p align="right">
182
+ <a href="#readme-top">🔼 Back to top</a>
183
+ </p>
clock_pattern-0.6.0/clock_pattern/__init__.py ADDED
@@ -0,0 +1,10 @@
1
+ __version__ = '0.6.0'
2
+
3
+ from .clocks import SystemClock, UtcClock
4
+ from .models import Clock
5
+
6
+ __all__ = (
7
+ 'Clock',
8
+ 'SystemClock',
9
+ 'UtcClock',
10
+ )
{clock_pattern-0.4.0 → clock_pattern-0.6.0}/clock_pattern/clocks/system_clock.py RENAMED
@@ -23,7 +23,7 @@ class SystemClock(Clock):
23
23
 
24
24
  Example:
25
25
  ```python
26
- from clock_pattern.clocks import SystemClock
26
+ from clock_pattern import SystemClock
27
27
 
28
28
  clock = SystemClock()
29
29
  print(clock.now())
@@ -48,7 +48,7 @@ class SystemClock(Clock):
48
48
 
49
49
  Example:
50
50
  ```python
51
- from clock_pattern.clocks import SystemClock
51
+ from clock_pattern import SystemClock
52
52
 
53
53
  clock = SystemClock()
54
54
  print(clock.now())
@@ -72,7 +72,7 @@ class SystemClock(Clock):
72
72
 
73
73
  Example:
74
74
  ```python
75
- from clock_pattern.clocks import SystemClock
75
+ from clock_pattern import SystemClock
76
76
 
77
77
  clock = SystemClock()
78
78
  print(clock.now())
@@ -91,7 +91,7 @@ class SystemClock(Clock):
91
91
 
92
92
  Example:
93
93
  ```python
94
- from clock_pattern.clocks import SystemClock
94
+ from clock_pattern import SystemClock
95
95
 
96
96
  clock = SystemClock()
97
97
  print(clock.now())
@@ -110,7 +110,7 @@ class SystemClock(Clock):
110
110
 
111
111
  Example:
112
112
  ```python
113
- from clock_pattern.clocks import SystemClock
113
+ from clock_pattern import SystemClock
114
114
 
115
115
  clock = SystemClock()
116
116
  print(clock.timezone)
{clock_pattern-0.4.0 → clock_pattern-0.6.0}/clock_pattern/clocks/utc_clock.py RENAMED
@@ -13,7 +13,7 @@ class UtcClock(SystemClock):
13
13
 
14
14
  Example:
15
15
  ```python
16
- from clock_pattern.clocks import UtcClock
16
+ from clock_pattern import UtcClock
17
17
 
18
18
  clock = UtcClock()
19
19
  print(clock.now())
@@ -27,7 +27,7 @@ class UtcClock(SystemClock):
27
27
 
28
28
  Example:
29
29
  ```python
30
- from clock_pattern.clocks import UtcClock
30
+ from clock_pattern import UtcClock
31
31
 
32
32
  clock = UtcClock()
33
33
  print(clock.now())
{clock_pattern-0.4.0 → clock_pattern-0.6.0}/clock_pattern/models/clock.py RENAMED
@@ -14,7 +14,7 @@ class Clock(ABC):
14
14
 
15
15
  Example:
16
16
  ```python
17
- from clock_pattern.clocks import SystemClock
17
+ from clock_pattern import SystemClock
18
18
 
19
19
  clock = SystemClock()
20
20
  print(clock.now())
@@ -32,7 +32,7 @@ class Clock(ABC):
32
32
 
33
33
  Example:
34
34
  ```python
35
- from clock_pattern.clocks import SystemClock
35
+ from clock_pattern import SystemClock
36
36
 
37
37
  clock = SystemClock()
38
38
  print(clock.now())
@@ -50,7 +50,7 @@ class Clock(ABC):
50
50
 
51
51
  Example:
52
52
  ```python
53
- from clock_pattern.clocks import SystemClock
53
+ from clock_pattern import SystemClock
54
54
 
55
55
  clock = SystemClock()
56
56
  print(clock.today())
{clock_pattern-0.4.0 → clock_pattern-0.6.0}/pyproject.toml RENAMED
@@ -26,6 +26,7 @@ classifiers = [
26
26
  'Programming Language :: Python :: 3.11',
27
27
  'Programming Language :: Python :: 3.12',
28
28
  'Programming Language :: Python :: 3.13',
29
+ 'Programming Language :: Python :: 3.14',
29
30
  ]
30
31
  keywords = [
31
32
  'python',
clock_pattern-0.4.0/PKG-INFO DELETED
@@ -1,95 +0,0 @@
1
- Metadata-Version: 2.4
2
- Name: clock-pattern
3
- Version: 0.4.0
4
- Summary: The Clock Pattern is a Python package that turns time into an injectable dependency.
5
- Project-URL: Homepage, https://github.com/adriamontoto/clock-pattern
6
- Project-URL: Repository, https://github.com/adriamontoto/clock-pattern
7
- Project-URL: Issues, https://github.com/adriamontoto/clock-pattern/issues
8
- Author: Adria Montoto
9
- License-Expression: MIT
10
- License-File: LICENSE.md
11
- Keywords: clock,dependency-injection,development,domain-driven-design,pattern,python,utilities
12
- Classifier: Intended Audience :: Developers
13
- Classifier: License :: OSI Approved :: MIT License
14
- Classifier: Operating System :: OS Independent
15
- Classifier: Programming Language :: Python
16
- Classifier: Programming Language :: Python :: 3
17
- Classifier: Programming Language :: Python :: 3.11
18
- Classifier: Programming Language :: Python :: 3.12
19
- Classifier: Programming Language :: Python :: 3.13
20
- Classifier: Typing :: Typed
21
- Requires-Python: >=3.11
22
- Requires-Dist: value-object-pattern>=0.6.0
23
- Description-Content-Type: text/markdown
24
-
25
- <a name="readme-top"></a>
26
-
27
- # 🕰️ Clock Pattern
28
-
29
- <p align="center">
30
- <a href="https://github.com/adriamontoto/clock-pattern/actions/workflows/ci.yaml?event=push&branch=master" target="_blank">
31
- <img src="https://github.com/adriamontoto/clock-pattern/actions/workflows/ci.yaml/badge.svg?event=push&branch=master" alt="CI Pipeline">
32
- </a>
33
- <a href="https://coverage-badge.samuelcolvin.workers.dev/redirect/adriamontoto/clock-pattern" target="_blank">
34
- <img src="https://coverage-badge.samuelcolvin.workers.dev/adriamontoto/clock-pattern.svg" alt="Coverage Pipeline">
35
- </a>
36
- <a href="https://pypi.org/project/clock-pattern" target="_blank">
37
- <img src="https://img.shields.io/pypi/v/clock-pattern?color=%2334D058&label=pypi%20package" alt="Package Version">
38
- </a>
39
- <a href="https://pypi.org/project/clock-pattern/" target="_blank">
40
- <img src="https://img.shields.io/pypi/pyversions/clock-pattern.svg?color=%2334D058" alt="Supported Python Versions">
41
- </a>
42
- </p>
43
-
44
- 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.
45
- <br><br>
46
-
47
- ## Table of Contents
48
-
49
- - [📥 Installation](#installation)
50
- - [🤝 Contributing](#contributing)
51
- - [🔑 License](#license)
52
-
53
- <p align="right">
54
- <a href="#readme-top">🔼 Back to top</a>
55
- </p><br><br>
56
-
57
- <a name="installation"></a>
58
-
59
- ## 📥 Installation
60
-
61
- You can install **Clock Pattern** using `pip`:
62
-
63
- ```bash
64
- pip install clock-pattern
65
- ```
66
-
67
- <p align="right">
68
- <a href="#readme-top">🔼 Back to top</a>
69
- </p><br><br>
70
-
71
- <a name="contributing"></a>
72
-
73
- ## 🤝 Contributing
74
-
75
- We love community help! Before you open an issue or pull request, please read:
76
-
77
- - [`🤝 How to Contribute`](https://github.com/adriamontoto/clock-pattern/blob/master/.github/CONTRIBUTING.md)
78
- - [`🧭 Code of Conduct`](https://github.com/adriamontoto/clock-pattern/blob/master/.github/CODE_OF_CONDUCT.md)
79
- - [`🔐 Security Policy`](https://github.com/adriamontoto/clock-pattern/blob/master/.github/SECURITY.md)
80
-
81
- _Thank you for helping make **🕰️ Clock Pattern** package awesome! 🌟_
82
-
83
- <p align="right">
84
- <a href="#readme-top">🔼 Back to top</a>
85
- </p><br><br>
86
-
87
- <a name="license"></a>
88
-
89
- ## 🔑 License
90
-
91
- This project is licensed under the terms of the [`MIT license`](https://github.com/adriamontoto/clock-pattern/blob/master/LICENSE.md).
92
-
93
- <p align="right">
94
- <a href="#readme-top">🔼 Back to top</a>
95
- </p>
clock_pattern-0.4.0/README.md DELETED
@@ -1,71 +0,0 @@
1
- <a name="readme-top"></a>
2
-
3
- # 🕰️ Clock Pattern
4
-
5
- <p align="center">
6
- <a href="https://github.com/adriamontoto/clock-pattern/actions/workflows/ci.yaml?event=push&branch=master" target="_blank">
7
- <img src="https://github.com/adriamontoto/clock-pattern/actions/workflows/ci.yaml/badge.svg?event=push&branch=master" alt="CI Pipeline">
8
- </a>
9
- <a href="https://coverage-badge.samuelcolvin.workers.dev/redirect/adriamontoto/clock-pattern" target="_blank">
10
- <img src="https://coverage-badge.samuelcolvin.workers.dev/adriamontoto/clock-pattern.svg" alt="Coverage Pipeline">
11
- </a>
12
- <a href="https://pypi.org/project/clock-pattern" target="_blank">
13
- <img src="https://img.shields.io/pypi/v/clock-pattern?color=%2334D058&label=pypi%20package" alt="Package Version">
14
- </a>
15
- <a href="https://pypi.org/project/clock-pattern/" target="_blank">
16
- <img src="https://img.shields.io/pypi/pyversions/clock-pattern.svg?color=%2334D058" alt="Supported Python Versions">
17
- </a>
18
- </p>
19
-
20
- 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.
21
- <br><br>
22
-
23
- ## Table of Contents
24
-
25
- - [📥 Installation](#installation)
26
- - [🤝 Contributing](#contributing)
27
- - [🔑 License](#license)
28
-
29
- <p align="right">
30
- <a href="#readme-top">🔼 Back to top</a>
31
- </p><br><br>
32
-
33
- <a name="installation"></a>
34
-
35
- ## 📥 Installation
36
-
37
- You can install **Clock Pattern** using `pip`:
38
-
39
- ```bash
40
- pip install clock-pattern
41
- ```
42
-
43
- <p align="right">
44
- <a href="#readme-top">🔼 Back to top</a>
45
- </p><br><br>
46
-
47
- <a name="contributing"></a>
48
-
49
- ## 🤝 Contributing
50
-
51
- We love community help! Before you open an issue or pull request, please read:
52
-
53
- - [`🤝 How to Contribute`](https://github.com/adriamontoto/clock-pattern/blob/master/.github/CONTRIBUTING.md)
54
- - [`🧭 Code of Conduct`](https://github.com/adriamontoto/clock-pattern/blob/master/.github/CODE_OF_CONDUCT.md)
55
- - [`🔐 Security Policy`](https://github.com/adriamontoto/clock-pattern/blob/master/.github/SECURITY.md)
56
-
57
- _Thank you for helping make **🕰️ Clock Pattern** package awesome! 🌟_
58
-
59
- <p align="right">
60
- <a href="#readme-top">🔼 Back to top</a>
61
- </p><br><br>
62
-
63
- <a name="license"></a>
64
-
65
- ## 🔑 License
66
-
67
- This project is licensed under the terms of the [`MIT license`](https://github.com/adriamontoto/clock-pattern/blob/master/LICENSE.md).
68
-
69
- <p align="right">
70
- <a href="#readme-top">🔼 Back to top</a>
71
- </p>
clock_pattern-0.4.0/clock_pattern/__init__.py DELETED
@@ -1 +0,0 @@
1
- __version__ = '0.4.0'
{clock_pattern-0.4.0 → clock_pattern-0.6.0}/.gitignore RENAMED
File without changes
{clock_pattern-0.4.0 → clock_pattern-0.6.0}/LICENSE.md RENAMED
File without changes