xtr-clock 2.0.0__tar.gz → 4.0.2__tar.gz

{xtr_clock-2.0.0 → xtr_clock-4.0.2}/LICENSE

@@ -1,6 +1,7 @@
 MIT License
 
 Copyright (c) 2026 xterr
+Copyright (c) 2022-present Fabien Potencier
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{xtr_clock-2.0.0 → xtr_clock-4.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xtr-clock
-Version: 2.0.0
+Version: 4.0.2
 Summary: Decouples an application from the system clock: an injectable clock, a timezone-aware instant, and a frozen clock for tests.
 Keywords: clock,time,datetime,timezone,testing,freeze-time,monotonic
 Author: Xterr
@@ -15,8 +15,9 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Testing
 Classifier: Typing :: Typed
+Requires-Dist: anyio>=4.0
 Requires-Dist: typing-extensions>=4.4 ; extra == 'di'
-Requires-Dist: xtr-dependency-injection>=2.0,<3 ; extra == 'di'
+Requires-Dist: xtr-dependency-injection>=4.0,<5 ; extra == 'di'
 Requires-Dist: tzdata>=2024.1 ; extra == 'tzdata'
 Requires-Python: >=3.11
 Provides-Extra: di
@@ -30,8 +31,8 @@ Description-Content-Type: text/markdown
 **A clock an application can be handed, instead of the one it is standing on.**
 
 <img alt="python 3.11+" src="https://img.shields.io/badge/python-%E2%89%A5%203.11-3776AB?logo=python&logoColor=white">
-<img alt="core dependencies: 0" src="https://img.shields.io/badge/core%20deps-0-3FB950">
-<img alt="coverage 100%" src="https://img.shields.io/badge/coverage-100%25-3FB950">
+<img alt="core dependencies: anyio" src="https://img.shields.io/badge/core%20deps-anyio-3FB950">
+<img alt="statements 100%" src="https://img.shields.io/badge/statements-100%25-3FB950">
 <img alt="typed" src="https://img.shields.io/badge/typed-ty%20%2B%20basedpyright-1f6feb">
 <img alt="license MIT" src="https://img.shields.io/badge/license-MIT-blue">
 
@@ -49,7 +50,8 @@ Take a **clock** as a constructor argument and the choice becomes configuration:
 clock in production, a frozen one in a test. What comes back is a **`DatePoint`** — a
 `datetime`, so nothing downstream has to change.
 
-- 🪶 **No dependencies.** Not one. `zoneinfo`, `contextvars` and `datetime` are already there.
+- 🪶 **One dependency.** `anyio`, so an awaitable wait is not tied to one async backend.
+  `zoneinfo`, `contextvars` and `datetime` are already there.
 - 🕐 **A `DatePoint` is a `datetime`.** It drops into an ORM column, a serializer, a comparison,
   an existing signature. Adopting this library changes no type you already have.
 - 🧭 **Always timezone-aware.** There is no such thing here as an instant whose offset is
@@ -57,7 +59,8 @@ clock in production, a frozen one in a test. What comes back is a **`DatePoint`*
 - ⏱️ **Frozen time costs nothing.** `clock.sleep(86400)` returns immediately and the clock is a
   day later.
 - 🔀 **Blocking or awaiting.** `sleep()` and `sleep_async()` on the same clock, so one contract
-  serves a worker and a web handler.
+  serves a worker and a web handler — and the awaitable one waits through anyio, so asyncio and
+  trio both get a clock they can use.
 - 🧩 **Protocol-based.** Every collaborator is a constructor argument, so a DI container can own
   the graph — and a clock from another library satisfies `SupportsNow` as it is.
 
@@ -76,7 +79,7 @@ uv add "xtr-clock[tzdata]"       # + a timezone database, where the system has n
 
 | Extra | Brings | For |
 | --- | --- | --- |
-| *(none)* | — | The whole library |
+| *(none)* | `anyio` | The whole library |
 | `tzdata` | `tzdata` | Windows, and slim containers that ship no zone database |
 
 Requires Python 3.11+.
@@ -376,6 +379,9 @@ Everything adding this package to an application on
 [xtr-dependency-injection](../xtr-dependency-injection) takes — and, read backwards, what removing it undoes.
 
 - **Install** — `uv add "xtr-clock[di]"`; add `tzdata` on Windows or a slim container.
+- **Recipe** — `uv run xtr-recipes recipes:sync` does the *Activate* step below: it lists
+  `ClockBundle`, or leaves it out when another bundle requires it (the logging bundle does). There
+  is no config file, environment or ignore line to write.
 - **Activate** — usually nothing to do: the logging bundle requires this one. Otherwise
   `ClockBundle: {"all": True}` in `BUNDLES` in `<app>/bundles.py`, imported from
   `xtr_clock.bundle`.
@@ -434,6 +440,9 @@ class TokenIssuer:
 | --- | --- |
 | `timezone` | The zone `Clock.now()` reports in. `None` follows the machine's own zone |
 
+A zone this system cannot resolve is refused by `ClockConfig` itself, so a typo fails the build
+with an `InvalidTimezoneError` naming it rather than the first reading taken at runtime.
+
 A test freezes time by replacing the `Clock` service — the one both `ClockInterface` and
 `Clock.get()` answer with once the kernel boots:
 
@@ -522,11 +531,8 @@ read-only copy, so send issues and pull requests to the monorepo.
 
 ```sh
 uv sync --all-extras
-uv run ruff check src tests
-uv run ruff format --check src tests
-uv run ty check
-uv run basedpyright
-uv run coverage run -m pytest && uv run coverage report
+uv run ruff check && uv run ruff format --check && uv run basedpyright && uv run ty check && uv run pytest
+uv run coverage run -m pytest && uv run coverage report  # statements 100%; the total adds branches
 ```
 
 Two type checkers on purpose — they disagree often enough to be worth both. Both run strict on
@@ -535,8 +541,10 @@ the tests too, with nothing suppressed.
 The suite mirrors the source tree: `tests/unit/` holds a `test_<module>.py` for each module,
 testing it alone; `tests/integration/` holds what needs a fresh interpreter — that the fixture
 is invisible until a suite opts in, and that importing the library pulls in nothing but the
-standard library. Statement and branch coverage are both 100%, measured with `coverage run`
-rather than `pytest --cov`, which starts too late to see a module's import.
+standard library and `anyio`. The awaitable waits run on asyncio and, when the checkout has it,
+on trio. Statement coverage is 100% — the figure the badge shows — measured with `coverage run`
+rather than `pytest --cov`, which starts too late to see a module's import. The report's own
+total reads 99%, since it counts branches too and one of them stays partial.
 
 ## License
 

{xtr_clock-2.0.0 → xtr_clock-4.0.2}/README.md

@@ -5,8 +5,8 @@
 **A clock an application can be handed, instead of the one it is standing on.**
 
 <img alt="python 3.11+" src="https://img.shields.io/badge/python-%E2%89%A5%203.11-3776AB?logo=python&logoColor=white">
-<img alt="core dependencies: 0" src="https://img.shields.io/badge/core%20deps-0-3FB950">
-<img alt="coverage 100%" src="https://img.shields.io/badge/coverage-100%25-3FB950">
+<img alt="core dependencies: anyio" src="https://img.shields.io/badge/core%20deps-anyio-3FB950">
+<img alt="statements 100%" src="https://img.shields.io/badge/statements-100%25-3FB950">
 <img alt="typed" src="https://img.shields.io/badge/typed-ty%20%2B%20basedpyright-1f6feb">
 <img alt="license MIT" src="https://img.shields.io/badge/license-MIT-blue">
 
@@ -24,7 +24,8 @@ Take a **clock** as a constructor argument and the choice becomes configuration:
 clock in production, a frozen one in a test. What comes back is a **`DatePoint`** — a
 `datetime`, so nothing downstream has to change.
 
-- 🪶 **No dependencies.** Not one. `zoneinfo`, `contextvars` and `datetime` are already there.
+- 🪶 **One dependency.** `anyio`, so an awaitable wait is not tied to one async backend.
+  `zoneinfo`, `contextvars` and `datetime` are already there.
 - 🕐 **A `DatePoint` is a `datetime`.** It drops into an ORM column, a serializer, a comparison,
   an existing signature. Adopting this library changes no type you already have.
 - 🧭 **Always timezone-aware.** There is no such thing here as an instant whose offset is
@@ -32,7 +33,8 @@ clock in production, a frozen one in a test. What comes back is a **`DatePoint`*
 - ⏱️ **Frozen time costs nothing.** `clock.sleep(86400)` returns immediately and the clock is a
   day later.
 - 🔀 **Blocking or awaiting.** `sleep()` and `sleep_async()` on the same clock, so one contract
-  serves a worker and a web handler.
+  serves a worker and a web handler — and the awaitable one waits through anyio, so asyncio and
+  trio both get a clock they can use.
 - 🧩 **Protocol-based.** Every collaborator is a constructor argument, so a DI container can own
   the graph — and a clock from another library satisfies `SupportsNow` as it is.
 
@@ -51,7 +53,7 @@ uv add "xtr-clock[tzdata]"       # + a timezone database, where the system has n
 
 | Extra | Brings | For |
 | --- | --- | --- |
-| *(none)* | — | The whole library |
+| *(none)* | `anyio` | The whole library |
 | `tzdata` | `tzdata` | Windows, and slim containers that ship no zone database |
 
 Requires Python 3.11+.
@@ -351,6 +353,9 @@ Everything adding this package to an application on
 [xtr-dependency-injection](../xtr-dependency-injection) takes — and, read backwards, what removing it undoes.
 
 - **Install** — `uv add "xtr-clock[di]"`; add `tzdata` on Windows or a slim container.
+- **Recipe** — `uv run xtr-recipes recipes:sync` does the *Activate* step below: it lists
+  `ClockBundle`, or leaves it out when another bundle requires it (the logging bundle does). There
+  is no config file, environment or ignore line to write.
 - **Activate** — usually nothing to do: the logging bundle requires this one. Otherwise
   `ClockBundle: {"all": True}` in `BUNDLES` in `<app>/bundles.py`, imported from
   `xtr_clock.bundle`.
@@ -409,6 +414,9 @@ class TokenIssuer:
 | --- | --- |
 | `timezone` | The zone `Clock.now()` reports in. `None` follows the machine's own zone |
 
+A zone this system cannot resolve is refused by `ClockConfig` itself, so a typo fails the build
+with an `InvalidTimezoneError` naming it rather than the first reading taken at runtime.
+
 A test freezes time by replacing the `Clock` service — the one both `ClockInterface` and
 `Clock.get()` answer with once the kernel boots:
 
@@ -497,11 +505,8 @@ read-only copy, so send issues and pull requests to the monorepo.
 
 ```sh
 uv sync --all-extras
-uv run ruff check src tests
-uv run ruff format --check src tests
-uv run ty check
-uv run basedpyright
-uv run coverage run -m pytest && uv run coverage report
+uv run ruff check && uv run ruff format --check && uv run basedpyright && uv run ty check && uv run pytest
+uv run coverage run -m pytest && uv run coverage report  # statements 100%; the total adds branches
 ```
 
 Two type checkers on purpose — they disagree often enough to be worth both. Both run strict on
@@ -510,8 +515,10 @@ the tests too, with nothing suppressed.
 The suite mirrors the source tree: `tests/unit/` holds a `test_<module>.py` for each module,
 testing it alone; `tests/integration/` holds what needs a fresh interpreter — that the fixture
 is invisible until a suite opts in, and that importing the library pulls in nothing but the
-standard library. Statement and branch coverage are both 100%, measured with `coverage run`
-rather than `pytest --cov`, which starts too late to see a module's import.
+standard library and `anyio`. The awaitable waits run on asyncio and, when the checkout has it,
+on trio. Statement coverage is 100% — the figure the badge shows — measured with `coverage run`
+rather than `pytest --cov`, which starts too late to see a module's import. The report's own
+total reads 99%, since it counts branches too and one of them stays partial.
 
 ## License
 

{xtr_clock-2.0.0 → xtr_clock-4.0.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "xtr-clock"
-version = "2.0.0"
+version = "4.0.2"
 description = "Decouples an application from the system clock: an injectable clock, a timezone-aware instant, and a frozen clock for tests."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -25,7 +25,7 @@ classifiers = [
     "Topic :: Software Development :: Testing",
     "Typing :: Typed",
 ]
-dependencies = []
+dependencies = ["anyio>=4.0"]
 
 [[project.authors]]
 name = "Xterr"
@@ -35,21 +35,24 @@ email = "me@xterr.dev"
 tzdata = ["tzdata>=2024.1"]
 di = [
     "typing-extensions>=4.4",
-    "xtr-dependency-injection>=2.0,<3",
+    "xtr-dependency-injection>=4.0,<5",
 ]
 
 [project.entry-points."xtr_dependency_injection.bundles"]
 clock = "xtr_clock.bundle:ClockBundle"
 
+[project.entry-points.xtr_recipes]
+clock = "xtr_clock.recipe"
+
 [dependency-groups]
 dev = [
     "basedpyright>=1.21",
     "ruff>=0.8",
     "pytest>=8",
     "pytest-cov>=5",
-    "anyio>=4.0",
+    "trio>=0.27",
     "ty>=0.0.83",
-    "xtr-dependency-injection>=2.0,<3",
+    "xtr-dependency-injection>=4.0,<5",
 ]
 
 [build-system]

{xtr_clock-2.0.0 → xtr_clock-4.0.2}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "xtr-clock"
-version = "2.0.0"
+version = "4.0.2"
 description = "Decouples an application from the system clock: an injectable clock, a timezone-aware instant, and a frozen clock for tests."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -20,7 +20,9 @@ classifiers = [
     "Topic :: Software Development :: Testing",
     "Typing :: Typed",
 ]
-dependencies = []
+dependencies = [
+    "anyio>=4.0",
+]
 
 [project.optional-dependencies]
 tzdata = [
@@ -28,7 +30,7 @@ tzdata = [
 ]
 di = [
     "typing-extensions>=4.4",
-    "xtr-dependency-injection>=2.0,<3",
+    "xtr-dependency-injection>=4.0,<5",
 ]
 
 # No `pytest11` entry point on purpose. The `clock` fixture is opted into with
@@ -41,15 +43,19 @@ di = [
 [project.entry-points."xtr_dependency_injection.bundles"]
 clock = "xtr_clock.bundle:ClockBundle"
 
+# Advertises the recipe — what *Use in an application* takes — for recipes:sync.
+[project.entry-points."xtr_recipes"]
+clock = "xtr_clock.recipe"
+
 [dependency-groups]
 dev = [
     "basedpyright>=1.21",
     "ruff>=0.8",
     "pytest>=8",
     "pytest-cov>=5",
-    "anyio>=4.0",
+    "trio>=0.27",
     "ty>=0.0.83",
-    "xtr-dependency-injection>=2.0,<3",
+    "xtr-dependency-injection>=4.0,<5",
 ]
 
 [build-system]

xtr_clock-4.0.2/src/xtr_clock/.agents/skills/xtr-clock/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: xtr-clock
+description: How to read, inject and freeze time with xtr-clock. Use when code needs the current time, timestamps, expiry or durations, timezone handling, relative dates such as "+1 day", or a test that must freeze or advance time; also when adding ClockBundle to an application on xtr-dependency-injection.
+---
+
+# xtr-clock
+
+Time is an input. Code takes a clock, the application decides which one, and a test hands it a
+frozen one. Every reading is a `DatePoint` — a timezone-aware `datetime` subclass, so it goes
+anywhere a `datetime` goes.
+
+## Quick reference
+
+- Take a `ClockInterface` as a constructor argument; call `clock.now()`. Never call
+  `datetime.now()`, `datetime.utcnow()` or `time.time()` in code that should be testable.
+- Production: `SystemClock()`. Durations and timeouts: `MonotonicClock()`. Tests: `MockClock(...)`.
+- Code that cannot be handed a clock (module helpers, validators): `from xtr_clock import now`.
+- Relative times: `clock.now().modify("+1 hour")`, `now("tomorrow")`, `DatePoint.parse("+1 day UTC")`.
+- Freeze for a block: `from xtr_clock.testing import mock_time`.
+- In an application: activate `ClockBundle`, inject `ClockInterface`.
+
+## Inject a clock
+
+```python
+from dataclasses import dataclass
+
+from xtr_clock import ClockInterface, DatePoint
+
+
+@dataclass(frozen=True, slots=True)
+class TokenIssuer:
+    clock: ClockInterface
+
+    def issue(self) -> DatePoint:
+        return self.clock.now().modify("+1 hour")
+```
+
+Every clock answers the same four calls:
+
+```python
+clock.now()  # DatePoint, always aware
+clock.sleep(2.5)  # MockClock returns at once and moves 2.5s forward
+await clock.sleep_async(2.5)  # same, without blocking; waits through anyio, so any backend works
+clock.with_timezone("Europe/Paris")  # a copy; the original is unchanged
+```
+
+Pick the clock by question:
+
+| Clock | Use for |
+| --- | --- |
+| `SystemClock` | Recording *when* something happened |
+| `MonotonicClock` | Measuring *how long* something took — never for stored timestamps |
+| `MockClock` | Tests; freezes in UTC unless given a zone |
+| `Clock` | The clock in force, or an adapter around any object with `now()` (`SupportsNow`) |
+
+## Relative times
+
+The modifier grammar accepts five shapes; anything else raises `InvalidModifierError`:
+
+| Written | Means |
+| --- | --- |
+| `now` | Unchanged |
+| `+1 day`, `-2 hours 30 minutes`, `2 days ago` | An offset; units chain |
+| `today`, `tomorrow`, `yesterday`, `midnight`, `noon` | A day boundary |
+| `2024-04-09`, `2024-04-09 15:00` | An absolute ISO-8601 datetime |
+| `Europe/Paris`, `UTC`, `+02:00` | The same instant in another zone |
+
+- Single-letter units (`m`, `h`) are refused — write `min`, `hr`, `hours`.
+- A trailing zone is applied **first**: `"+1 day Europe/Paris"` moves to Paris, then adds a day.
+- Calendar units keep the wall clock (`+1 day` across a DST change is "same time tomorrow");
+  durations keep elapsed time (`+24 hours`).
+- Months clamp: January 31 `+1 month` is February 28/29.
+- Stepping through a calendar in code: `shift_calendar(moment, months=1)`.
+
+## Code that cannot take a clock
+
+```python
+from xtr_clock import now
+
+expires = now("+1 hour")  # reads the clock in force, not the OS
+```
+
+The clock in force lives in a `ContextVar`. Install one with:
+
+- `Clock.set(clock)` — for good, at application startup only.
+- `with Clock.using(clock):` — for a block; restored even on error. Prefer this.
+- `restore = Clock.install(clock)` — until `restore()` is called, for lifetimes that are not a block.
+
+A class that cannot take a constructor argument mixes in `ClockAwareMixin` and calls `self.now()`;
+`set_clock(...)` replaces its clock.
+
+## Testing
+
+```python
+from xtr_clock import MockClock
+from xtr_clock.testing import mock_time
+
+
+def test_issue() -> None:
+    issuer = TokenIssuer(MockClock("2024-04-09 12:00:00"))
+    assert issuer.issue().isoformat() == "2024-04-09T13:00:00+00:00"
+
+
+def test_helper_code() -> None:
+    with mock_time("2024-04-09 12:00:00") as clock:
+        clock.sleep(3600)  # an hour passes instantly
+        assert now().hour == 13
+```
+
+- A `clock` fixture is available after opting in from `conftest.py`:
+  `pytest_plugins = ["xtr_clock.pytest_plugin"]`. It is never registered automatically.
+- In async tests, call `mock_time` inside the coroutine so the block and the code share a context.
+
+## Use in an application
+
+`uv run xtr-recipes recipes:sync` applies the recipe shipped with this package: it lists
+`ClockBundle`, or leaves it out when another bundle requires it (the logging bundle does). That is
+the steps below a recipe can do; the others it prints for you to make.
+
+1. **Install** — `uv add "xtr-clock[di]"`; add the `tzdata` extra on Windows or slim containers.
+2. **Activate** — usually nothing: the logging bundle requires it. Otherwise add
+   `ClockBundle: {"all": True}` to `BUNDLES` in `<app>/bundles.py`
+   (`from xtr_clock.bundle import ClockBundle`).
+3. **Configure** — optional; with no configuration it reports in the machine's zone:
+
+   ```python
+   # <app>/config/clock.py
+   from xtr_dependency_injection import configure
+   from xtr_clock.bundle import ClockConfig
+
+
+   @configure
+   def clock() -> ClockConfig:
+       return ClockConfig(timezone="UTC")
+   ```
+
+   `ClockConfig` resolves the zone as it is built, so an unknown one raises
+   `InvalidTimezoneError` at build time rather than on the first reading.
+
+4. **Use** — inject `ClockInterface`. The bundle also installs the same clock as the clock in
+   force, so `now()` and the injected clock agree.
+5. **Test** — replace the `Clock` service:
+   `boot_for_test(kernel, overrides={Clock: Clock(MockClock("2026-01-01"), "UTC")})`.
+6. **Check** — `debug:bundles` shows `clock` as `active`.
+7. **Remove** — drop the `BUNDLES` entry and `<app>/config/clock.py`, then `uv remove xtr-clock`,
+   unless xtr-logging is installed (it depends on this package).
+
+## Errors
+
+Both derive from `ClockError` and from `ValueError`:
+
+- `InvalidModifierError` — unreadable modifier (`.modifier`, `.reason`).
+- `InvalidTimezoneError` — unknown zone (`.timezone`); install the `tzdata` extra if the system has no zone database.
+
+## Do not
+
+- Do not use naive datetimes; a `DatePoint` is always aware, and comparing aware with naive fails.
+- Do not call `Clock.set()` in tests — it never ends; use `mock_time` or `Clock.using`.
+- Do not use `MonotonicClock` for timestamps you store or show.
+- Do not patch `datetime` or the interpreter to freeze time.

{xtr_clock-2.0.0 → xtr_clock-4.0.2}/src/xtr_clock/bundle/clock_config.py

@@ -4,6 +4,8 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 
+from xtr_clock.timezone import resolve_timezone
+
 __all__ = ["ClockConfig"]
 
 
@@ -17,3 +19,13 @@ class ClockConfig:
     """
 
     timezone: str | None = None
+
+    def __post_init__(self) -> None:
+        """Resolve the zone now, so a typo fails the build and not the first reading.
+
+        Raises:
+            InvalidTimezoneError: When ``timezone`` names no zone this
+                system knows.
+        """
+        if self.timezone is not None:
+            _ = resolve_timezone(self.timezone)

{xtr_clock-2.0.0 → xtr_clock-4.0.2}/src/xtr_clock/calendar_shift.py

@@ -24,7 +24,13 @@ def shift_calendar(moment: _DateT, /, *, months: int = 0, days: int = 0) -> _Dat
     24 hours later. A wall clock the zone skipped over (the hour lost as the
     clocks go forward) is read as the instant it names, shown on the hour
     that replaced it, so the result always really existed.
+
+    Asked for no shift at all — a scheduler stepping a calendar by zero —
+    it hands back what it was given, rather than resolving an instant it
+    never moved.
     """
+    if not months and not days:
+        return moment
     if months:
         position = moment.month - 1 + months
         year = moment.year + position // _MONTHS_PER_YEAR

{xtr_clock-2.0.0 → xtr_clock-4.0.2}/src/xtr_clock/clock_interface.py

@@ -64,7 +64,9 @@ class ClockInterface(SupportsNow, Protocol):
     async def sleep_async(self, seconds: float) -> None:
         """Wait ``seconds`` without blocking the event loop.
 
-        A value of zero or less returns immediately.
+        A value of zero or less returns immediately. Implementations wait
+        through anyio, so a clock is usable on whichever async backend the
+        application runs on.
         """
         ...
 

{xtr_clock-2.0.0 → xtr_clock-4.0.2}/src/xtr_clock/date_point.py

@@ -113,30 +113,30 @@ class DatePoint(datetime):
     @classmethod
     def parse(
         cls,
-        spec: str,
+        modifier: str,
         timezone: str | tzinfo | None = None,
         *,
         reference: datetime | None = None,
     ) -> Self:
-        """Return the instant ``spec`` describes.
+        """Return the instant ``modifier`` describes.
 
-        ``spec`` is read by the grammar documented on
+        ``modifier`` is read by the grammar documented on
         :mod:`xtr_clock.modifier`: an offset like ``'+1 day'``, a keyword
         like ``'tomorrow'``, an ISO-8601 datetime, a timezone name, or any
         of them with a zone trailing.
 
         Args:
-            spec: The modifier to read.
+            modifier: The modifier to read.
             timezone: The zone to read the reference in before applying
-                ``spec``. A zone named inside ``spec`` wins over this one.
-            reference: The instant ``spec`` is relative to. Defaults to
+                ``modifier``. A zone named inside it wins over this one.
+            reference: The instant ``modifier`` is relative to. Defaults to
                 whatever the clock in force says now is.
 
         Returns:
             The instant described.
 
         Raises:
-            InvalidModifierError: When the grammar cannot read ``spec``.
+            InvalidModifierError: When the grammar cannot read ``modifier``.
             InvalidTimezoneError: When ``timezone`` names no known zone.
         """
         if reference is None:
@@ -148,7 +148,7 @@ class DatePoint(datetime):
         if timezone is not None:
             base = base.with_timezone(timezone)
 
-        return cls.from_datetime(apply_modifier(base, spec))
+        return cls.from_datetime(apply_modifier(base, modifier))
 
     @classmethod
     def from_datetime(cls, value: datetime) -> Self:

{xtr_clock-2.0.0 → xtr_clock-4.0.2}/src/xtr_clock/mock_clock.py

@@ -2,10 +2,11 @@
 
 from __future__ import annotations
 
-import asyncio
 from datetime import UTC, datetime, timedelta
 from typing import TYPE_CHECKING, Self, final
 
+from anyio.lowlevel import checkpoint
+
 from .date_point import DatePoint
 from .timezone import resolve_timezone
 
@@ -99,11 +100,14 @@ class MockClock:
         Nothing is waited for, but control is handed back once so the tasks
         that were waiting on this clock get their turn — which is the whole
         behaviour a test of concurrent code is trying to observe.
+
+        The yield goes through anyio, so this works on whichever async
+        backend the test runs on rather than only on asyncio.
         """
         if seconds > 0:
             self._advance(seconds)
 
-        await asyncio.sleep(0)
+        await checkpoint()
 
     def modify(self, modifier: str) -> None:
         """Move to wherever ``modifier`` points, relative to right here.

{xtr_clock-2.0.0 → xtr_clock-4.0.2}/src/xtr_clock/modifier.py

@@ -132,11 +132,11 @@ def apply_modifier(reference: datetime, modifier: str) -> datetime:
     Raises:
         InvalidModifierError: When the grammar cannot read ``modifier``.
     """
-    spec = modifier.strip()
-    if not spec:
+    text = modifier.strip()
+    if not text:
         raise InvalidModifierError(modifier, "it is empty")
 
-    moment, rest = _split_timezone(reference, spec)
+    moment, rest = _split_timezone(reference, text)
     if not rest or rest.lower() == "now":
         return moment
 
@@ -156,17 +156,17 @@ def apply_modifier(reference: datetime, modifier: str) -> datetime:
     )
 
 
-def _split_timezone(reference: datetime, spec: str) -> tuple[datetime, str]:
-    """Split a trailing timezone off ``spec``, moving ``reference`` into it.
+def _split_timezone(reference: datetime, text: str) -> tuple[datetime, str]:
+    """Split a trailing timezone off ``text``, moving ``reference`` into it.
 
     The zone is applied before anything else, so an offset in the rest of
     the modifier is counted in the zone the caller asked for.
     """
-    tokens = spec.split()
+    tokens = text.split()
     try:
         zone = resolve_timezone(tokens[-1])
     except InvalidTimezoneError:
-        return reference, spec
+        return reference, text
 
     return reference.astimezone(zone), " ".join(tokens[:-1])
 

{xtr_clock-2.0.0 → xtr_clock-4.0.2}/src/xtr_clock/monotonic_clock.py

@@ -2,12 +2,13 @@
 
 from __future__ import annotations
 
-import asyncio
 import time
 from copy import copy
 from datetime import UTC, datetime, timedelta
 from typing import TYPE_CHECKING, Final, Self, final
 
+import anyio
+
 from .date_point import DatePoint
 from .timezone import local_timezone, resolve_timezone
 
@@ -62,8 +63,8 @@ class MonotonicClock:
 
     def now(self) -> DatePoint:
         """Return the current instant, truncated to the microsecond."""
-        elapsed = self._anchor_ns + time.monotonic_ns()
-        moment = _EPOCH + timedelta(microseconds=elapsed // _NANOSECONDS_PER_MICROSECOND)
+        since_epoch_ns = self._anchor_ns + time.monotonic_ns()
+        moment = _EPOCH + timedelta(microseconds=since_epoch_ns // _NANOSECONDS_PER_MICROSECOND)
 
         return DatePoint.from_datetime(moment.astimezone(self._timezone))
 
@@ -73,8 +74,12 @@ class MonotonicClock:
             time.sleep(seconds)
 
     async def sleep_async(self, seconds: float) -> None:
-        """Wait ``seconds`` without blocking the event loop."""
-        await asyncio.sleep(max(seconds, 0.0))
+        """Wait ``seconds`` without blocking the event loop.
+
+        The wait goes through anyio, so the clock works on whichever async
+        backend the application runs on rather than only on asyncio.
+        """
+        await anyio.sleep(max(seconds, 0.0))
 
     def with_timezone(self, timezone: str | tzinfo) -> Self:
         """Return the same clock reporting in ``timezone``.

xtr_clock-4.0.2/src/xtr_clock/recipe/__init__.py

@@ -0,0 +1,15 @@
+"""This directory holds the package's recipe: its manifest.
+
+The recipe is what *Use in an application* in the README lists, written as
+data: the bundle to list — usually left out, because the logging bundle
+requires it — and the step only a person can take. An application applies it
+with ``xtr-recipes recipes:sync``, which finds this module through the
+``xtr_recipes`` entry point.
+
+Nothing is importable from here. The manifest is read as a file, so a recipe
+is the same from a wheel as from a working tree.
+"""
+
+from __future__ import annotations
+
+__all__: list[str] = []

xtr_clock-4.0.2/src/xtr_clock/recipe/manifest.toml

@@ -0,0 +1,19 @@
+# The recipe for xtr-clock: what *Use in an application* in the README takes,
+# as data. Keep the two in step — the README is the source.
+
+[bundles]
+# "<module>:<class>" = the environments it is listed with, exactly as in BUNDLES.
+# Usually nothing is written: a sync leaves out a bundle another active one
+# requires, and the logging bundle requires this one.
+"xtr_clock.bundle:ClockBundle" = { all = true }
+
+# No [files]: configuring is optional. With none the clock reports in the
+# machine's own zone; an application fixing one writes config/clock.py itself.
+
+# No [env], and nothing to ignore.
+
+[gitignore]
+lines = []
+
+[notes]
+check = ["<script> debug:bundles — clock is listed or required, and active"]

{xtr_clock-2.0.0 → xtr_clock-4.0.2}/src/xtr_clock/system_clock.py

@@ -2,11 +2,12 @@
 
 from __future__ import annotations
 
-import asyncio
 import time
 from datetime import datetime
 from typing import TYPE_CHECKING, Self, final
 
+import anyio
+
 from .date_point import DatePoint
 from .timezone import local_timezone, resolve_timezone
 
@@ -59,8 +60,12 @@ class SystemClock:
             time.sleep(seconds)
 
     async def sleep_async(self, seconds: float) -> None:
-        """Wait ``seconds`` without blocking the event loop."""
-        await asyncio.sleep(max(seconds, 0.0))
+        """Wait ``seconds`` without blocking the event loop.
+
+        The wait goes through anyio, so the clock works on whichever async
+        backend the application runs on rather than only on asyncio.
+        """
+        await anyio.sleep(max(seconds, 0.0))
 
     def with_timezone(self, timezone: str | tzinfo) -> Self:
         """Return the same clock reporting in ``timezone``.