xtr-clock 1.0.0__py3-none-any.whl

xtr_clock/__init__.py

@@ -0,0 +1,61 @@
+"""A clock an application can be handed, instead of the one it is standing on.
+
+Reading the time is an input like any other, and code that reaches for the
+operating system to get it cannot be told what time it is. That is what makes
+a test about expiry, backoff or a billing period slow, flaky, or quietly
+wrong every March.
+
+Depend on :class:`~xtr_clock.clock_interface.ClockInterface` and the choice
+becomes a constructor argument:
+:class:`~xtr_clock.system_clock.SystemClock` in production,
+:class:`~xtr_clock.monotonic_clock.MonotonicClock` where a duration must be
+trusted, :class:`~xtr_clock.mock_clock.MockClock` in a test. What comes back
+is always a :class:`~xtr_clock.date_point.DatePoint`: a
+:class:`~datetime.datetime` that is always timezone-aware and stays itself
+through every operation.
+
+Code that cannot be handed anything asks :meth:`~xtr_clock.clock.Clock.get`,
+and a test answers with :func:`~xtr_clock.testing.mock_time`.
+
+Nothing here depends on anything outside the standard library.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .clock import Clock
+from .clock_aware_mixin import ClockAwareMixin
+from .clock_interface import ClockInterface, SupportsNow
+from .date_point import DatePoint
+from .exception import ClockError, InvalidModifierError, InvalidTimezoneError
+from .mock_clock import MockClock
+from .modifier import apply_modifier
+from .monotonic_clock import MonotonicClock
+from .now import now
+from .system_clock import SystemClock
+from .timezone import local_timezone, resolve_timezone
+
+try:
+    __version__ = version("xtr-clock")
+except PackageNotFoundError:  # pragma: no cover
+    # Running from a source tree or a vendored copy, with no installed
+    # metadata to read. Having no version is better than refusing to import.
+    __version__ = "0+unknown"
+
+__all__ = [
+    "Clock",
+    "ClockAwareMixin",
+    "ClockError",
+    "ClockInterface",
+    "DatePoint",
+    "InvalidModifierError",
+    "InvalidTimezoneError",
+    "MockClock",
+    "MonotonicClock",
+    "SupportsNow",
+    "SystemClock",
+    "__version__",
+    "apply_modifier",
+    "local_timezone",
+    "now",
+    "resolve_timezone",
+]

xtr_clock/clock.py

@@ -0,0 +1,198 @@
+"""The clock in force, and the adapter that makes a foreign one fit.
+
+Injecting a clock is the honest way to make a class testable, and most of
+this library exists to support it. But some code cannot be handed anything —
+a module-level helper, a validator called by a framework, a function three
+libraries deep. That code asks :meth:`Clock.get`, and a test answers by
+installing another clock with :meth:`Clock.using`.
+
+The clock in force is held in a :class:`~contextvars.ContextVar`, so a
+scope that installs one does not leak into a concurrent task that did not,
+and two tests running side by side cannot see each other's. Installing also
+updates a process-wide fallback, so a thread started later — which begins
+with a fresh context — still sees the clock the application chose.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from contextvars import ContextVar
+from typing import TYPE_CHECKING, ClassVar, Self, final
+
+from .clock_interface import ClockInterface, SupportsNow
+from .date_point import DatePoint
+from .system_clock import SystemClock
+from .timezone import resolve_timezone
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+    from datetime import tzinfo
+
+__all__ = ["Clock"]
+
+
+@final
+class Clock:
+    """The clock in force, and a clock that reads it.
+
+    As a class it is the registry: :meth:`get` answers with whatever clock
+    is in force, :meth:`set` installs one for good, :meth:`using` installs
+    one for a scope.
+
+    As an instance it is a clock in its own right, and a useful one twice
+    over. Built around an object that can only say :meth:`~SupportsNow.now`,
+    it fills in the rest of the contract. Built around nothing, it forwards
+    to whatever is in force at the moment each question is asked — so a
+    class handed one at startup reads a clock a test installs later.
+
+    Prefer taking a :class:`~xtr_clock.clock_interface.ClockInterface` as a
+    constructor argument. Reach for this only where nothing can be handed
+    in.
+    """
+
+    _current: ClassVar[ContextVar[ClockInterface | None]] = ContextVar(
+        "xtr_clock_current",
+        default=None,
+    )
+    _fallback: ClassVar[ClockInterface | None] = None
+
+    __slots__ = ("_clock", "_timezone")
+
+    _clock: SupportsNow | None
+    _timezone: tzinfo | None
+
+    def __init__(
+        self,
+        clock: SupportsNow | None = None,
+        timezone: str | tzinfo | None = None,
+    ) -> None:
+        """Wrap ``clock``, or the clock in force when none is given.
+
+        Args:
+            clock: The clock to read. ``None`` reads whichever clock is in
+                force each time a question is asked, rather than the one in
+                force now.
+            timezone: A zone to pin every reading to. ``None`` reports
+                instants in whatever zone the wrapped clock used.
+
+        Raises:
+            InvalidTimezoneError: When ``timezone`` names no known zone.
+        """
+        self._clock = clock
+        self._timezone = resolve_timezone(timezone) if timezone is not None else None
+
+    @classmethod
+    def get(cls) -> ClockInterface:
+        """Return the clock in force.
+
+        A scope opened by :meth:`using` wins; otherwise whatever :meth:`set`
+        installed; otherwise a :class:`~xtr_clock.system_clock.SystemClock`,
+        built once and kept.
+        """
+        if (scoped := Clock._current.get()) is not None:
+            return scoped
+
+        if Clock._fallback is None:
+            Clock._fallback = SystemClock()
+
+        return Clock._fallback
+
+    @classmethod
+    def set(cls, clock: SupportsNow) -> None:
+        """Install ``clock`` as the clock in force, until something replaces it.
+
+        An object that only answers :meth:`~SupportsNow.now` is wrapped so
+        it satisfies the whole contract.
+
+        Prefer :meth:`using` in a test: this one has no end, and a test that
+        forgets to undo it hands the next one a clock it never asked for.
+        """
+        Clock._fallback = _adapt(clock)
+        _ = Clock._current.set(Clock._fallback)
+
+    @classmethod
+    @contextmanager
+    def using(cls, clock: SupportsNow) -> Generator[ClockInterface, None, None]:
+        """Install ``clock`` for the duration of a ``with`` block.
+
+        The previous clock comes back on the way out, including when the
+        block raises.
+
+        Args:
+            clock: The clock to install. An object that only answers
+                :meth:`~SupportsNow.now` is wrapped.
+
+        Yields:
+            The clock as installed, which is ``clock`` itself unless it had
+            to be wrapped.
+        """
+        resolved = _adapt(clock)
+        previous = Clock._fallback
+        token = Clock._current.set(resolved)
+        Clock._fallback = resolved
+        try:
+            yield resolved
+        finally:
+            Clock._current.reset(token)
+            Clock._fallback = previous
+
+    @property
+    def timezone(self) -> tzinfo | None:
+        """The zone readings are pinned to, or ``None`` to follow the clock read."""
+        return self._timezone
+
+    def now(self) -> DatePoint:
+        """Return the current instant, as the clock being read tells it."""
+        moment = DatePoint.from_datetime(self._target().now())
+
+        return moment.with_timezone(self._timezone) if self._timezone is not None else moment
+
+    def sleep(self, seconds: float) -> None:
+        """Block for ``seconds``, the way the clock being read does.
+
+        A clock that only answers :meth:`~SupportsNow.now` cannot say how to
+        wait, so real time is what passes.
+        """
+        target = self._target()
+        if isinstance(target, ClockInterface):
+            target.sleep(seconds)
+        else:
+            SystemClock().sleep(seconds)
+
+    async def sleep_async(self, seconds: float) -> None:
+        """Wait ``seconds`` the way the clock being read does, without blocking."""
+        target = self._target()
+        if isinstance(target, ClockInterface):
+            await target.sleep_async(seconds)
+        else:
+            await SystemClock().sleep_async(seconds)
+
+    def with_timezone(self, timezone: str | tzinfo) -> Self:
+        """Return the same clock pinning every reading to ``timezone``.
+
+        Raises:
+            InvalidTimezoneError: When ``timezone`` names no known zone.
+        """
+        return type(self)(self._clock, timezone)
+
+    def _target(self) -> SupportsNow:
+        """Return the clock to read: the wrapped one, or the one in force."""
+        if self._clock is not None:
+            return self._clock
+
+        current = Clock.get()
+
+        # An empty Clock installed as the clock in force would otherwise ask
+        # itself what time it is, and never come back.
+        return SystemClock() if current is self else current
+
+    def __repr__(self) -> str:
+        """Return a reading that names what is wrapped and any pinned zone."""
+        pinned = f", {self._timezone!s}" if self._timezone is not None else ""
+
+        return f"{type(self).__name__}({self._clock!r}{pinned})"
+
+
+def _adapt(clock: SupportsNow) -> ClockInterface:
+    """Return ``clock`` as a full contract, wrapping it only if it is not one."""
+    return clock if isinstance(clock, ClockInterface) else Clock(clock)

xtr_clock/clock_aware_mixin.py

@@ -0,0 +1,58 @@
+"""A mixin for a class that needs to know what time it is."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, ClassVar
+
+from .clock import Clock
+
+if TYPE_CHECKING:
+    from .clock_interface import ClockInterface
+    from .date_point import DatePoint
+
+__all__ = ["ClockAwareMixin"]
+
+
+class ClockAwareMixin:
+    """Gives a class a clock it can be handed, and a default until it is.
+
+    Taking a :class:`~xtr_clock.clock_interface.ClockInterface` as a
+    constructor argument is still the clearest thing to do. This is for the
+    case where you cannot: a class whose constructor is already spoken for
+    by a framework, or a long-lived one you are making testable without
+    rewriting every place that builds it.
+
+    It defines no ``__init__``, so it composes with any class — including a
+    dataclass — and reads the clock in force until :meth:`set_clock` says
+    otherwise.
+
+    ```python
+    class TokenIssuer(ClockAwareMixin):
+        def issue(self) -> Token:
+            return Token(expires_at=self.now().modify("+1 hour"))
+
+
+    issuer = TokenIssuer()
+    issuer.set_clock(MockClock("2024-04-09 12:00:00"))
+    ```
+    """
+
+    __slots__: ClassVar[tuple[str, ...]] = ("_clock",)
+
+    _clock: ClockInterface
+
+    def set_clock(self, clock: ClockInterface) -> None:
+        """Read time from ``clock`` from now on."""
+        self._clock = clock
+
+    @property
+    def clock(self) -> ClockInterface:
+        """The clock this object reads: the one it was given, or the one in force."""
+        try:
+            return self._clock
+        except AttributeError:
+            return Clock.get()
+
+    def now(self) -> DatePoint:
+        """Return the current instant, according to this object's clock."""
+        return self.clock.now()

xtr_clock/clock_interface.py

@@ -0,0 +1,80 @@
+"""What a clock answers to.
+
+Two contracts, because two different things depend on a clock.
+
+:class:`SupportsNow` is the smaller one — a single ``now()`` — and exists so
+a clock from somewhere else can be adopted without implementing anything.
+:class:`ClockInterface` is what this library's own clocks satisfy and what
+application code should ask for, because reading the time is rarely the only
+thing a time-sensitive class needs to do with it.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, Self, runtime_checkable
+
+if TYPE_CHECKING:
+    from datetime import datetime, tzinfo
+
+    from .date_point import DatePoint
+
+__all__ = ["ClockInterface", "SupportsNow"]
+
+
+@runtime_checkable
+class SupportsNow(Protocol):
+    """Anything that can say what time it is.
+
+    Deliberately structural and deliberately minimal: a clock written
+    against some other library, or a two-line stub in a test, satisfies it
+    without importing anything from here. Hand one to
+    :class:`~xtr_clock.clock.Clock` to get the full contract back.
+    """
+
+    def now(self) -> datetime:
+        """Return the current instant."""
+        ...
+
+
+@runtime_checkable
+class ClockInterface(SupportsNow, Protocol):
+    """The contract time-sensitive code should depend on.
+
+    Depend on this rather than on a concrete clock and the choice between
+    reading the operating system, counting monotonically, and standing still
+    for a test becomes a constructor argument.
+
+    Both a blocking and an awaitable wait live here rather than on separate
+    contracts, because a clock that can only do one of them is a clock half
+    the application cannot use — and the two cannot share a name, since one
+    returns and the other is awaited.
+    """
+
+    def now(self) -> DatePoint:
+        """Return the current instant, always timezone-aware."""
+        ...
+
+    def sleep(self, seconds: float) -> None:
+        """Block for ``seconds``, which a frozen clock does instantly.
+
+        A value of zero or less returns immediately.
+        """
+        ...
+
+    async def sleep_async(self, seconds: float) -> None:
+        """Wait ``seconds`` without blocking the event loop.
+
+        A value of zero or less returns immediately.
+        """
+        ...
+
+    def with_timezone(self, timezone: str | tzinfo) -> Self:
+        """Return the same clock reading its instants in another zone.
+
+        This one is left alone, so a class that pins a zone for itself does
+        not change the time anybody else reads.
+
+        Raises:
+            InvalidTimezoneError: When ``timezone`` names no known zone.
+        """
+        ...

xtr_clock/date_point.py

@@ -0,0 +1,250 @@
+"""An instant that stays aware, and stays a ``DatePoint``.
+
+``DatePoint`` is a :class:`~datetime.datetime`, so everything already
+written against one keeps working: comparison, subtraction, formatting,
+``strftime``, ``isoformat``, sorting, a database driver. It adds two
+guarantees the standard library leaves to the caller.
+
+**It is always timezone-aware.** A naive reading is taken as local time, the
+same way the standard library reads one when it converts. There is therefore
+no such thing as a ``DatePoint`` whose offset is unknown, which is what makes
+comparing two of them always meaningful.
+
+**It stays a ``DatePoint``.** ``replace``, ``astimezone``, adding a
+:class:`~datetime.timedelta`, ``fromisoformat``, ``strptime`` — each answers
+with a ``DatePoint``, so the type survives a chain of operations and the
+guarantee above survives with it.
+
+``now()`` reads the clock in force rather than the operating system, so a
+frozen clock in a test reaches code that never heard of this library's
+interfaces.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import TYPE_CHECKING, ClassVar, Self, TypeVar
+
+from .modifier import apply_modifier
+from .timezone import local_timezone, resolve_timezone
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from datetime import tzinfo
+    from typing import SupportsIndex
+
+__all__ = ["DatePoint"]
+
+_DatePointT = TypeVar("_DatePointT", bound="DatePoint")
+
+
+class DatePoint(datetime):
+    """A timezone-aware instant that survives every operation as itself."""
+
+    __slots__: ClassVar[tuple[str, ...]] = ()
+
+    def __new__(
+        cls,
+        year: int,
+        month: int,
+        day: int,
+        hour: int = 0,
+        minute: int = 0,
+        second: int = 0,
+        microsecond: int = 0,
+        tzinfo: tzinfo | None = None,
+        *,
+        fold: int = 0,
+    ) -> Self:
+        """Build an instant, attaching the local zone when none is given.
+
+        Args:
+            year: The year.
+            month: The month, 1 to 12.
+            day: The day of the month.
+            hour: The hour, 0 to 23.
+            minute: The minute.
+            second: The second.
+            microsecond: The microsecond.
+            tzinfo: The zone these fields are read in. ``None`` means local,
+                which is the reading the standard library gives a naive
+                datetime whenever it has to pick one.
+            fold: Which of two identical wall clocks is meant, when a
+                daylight saving change produced the same one twice.
+        """
+        return super().__new__(
+            cls,
+            year,
+            month,
+            day,
+            hour,
+            minute,
+            second,
+            microsecond,
+            tzinfo if tzinfo is not None else local_timezone(),
+            fold=fold,
+        )
+
+    @classmethod
+    def now(cls, tz: tzinfo | None = None) -> Self:
+        """Return the current instant, read from the clock in force.
+
+        This is the one method that departs from
+        :meth:`datetime.datetime.now`: it asks
+        :meth:`~xtr_clock.clock.Clock.get` rather than the operating system,
+        so freezing the clock in a test reaches code that calls
+        ``DatePoint.now()`` without having been handed a clock.
+
+        Args:
+            tz: The zone to read the instant in. ``None`` keeps whichever
+                zone the clock answers in.
+        """
+        from .clock import Clock  # noqa: PLC0415 — deferred: Clock answers in DatePoint
+
+        moment = Clock.get().now()
+
+        return cls.from_datetime(moment if tz is None else moment.astimezone(tz))
+
+    @classmethod
+    def parse(
+        cls,
+        spec: str,
+        timezone: str | tzinfo | None = None,
+        *,
+        reference: datetime | None = None,
+    ) -> Self:
+        """Return the instant ``spec`` describes.
+
+        ``spec`` 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.
+            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
+                whatever the clock in force says now is.
+
+        Returns:
+            The instant described.
+
+        Raises:
+            InvalidModifierError: When the grammar cannot read ``spec``.
+            InvalidTimezoneError: When ``timezone`` names no known zone.
+        """
+        if reference is None:
+            from .clock import Clock  # noqa: PLC0415 — deferred: Clock answers in DatePoint
+
+            reference = Clock.get().now()
+
+        base = cls.from_datetime(reference)
+        if timezone is not None:
+            base = base.with_timezone(timezone)
+
+        return cls.from_datetime(apply_modifier(base, spec))
+
+    @classmethod
+    def from_datetime(cls, value: datetime) -> Self:
+        """Return ``value`` as a ``DatePoint``.
+
+        A ``DatePoint`` is returned unchanged, so adopting one that already
+        is costs nothing. A naive datetime is read as local time.
+
+        Args:
+            value: The datetime to adopt.
+        """
+        if isinstance(value, cls):
+            return value
+
+        return cls(
+            value.year,
+            value.month,
+            value.day,
+            value.hour,
+            value.minute,
+            value.second,
+            value.microsecond,
+            value.tzinfo,
+            fold=value.fold,
+        )
+
+    def modify(self, modifier: str) -> Self:
+        """Return the instant ``modifier`` describes, relative to this one.
+
+        Args:
+            modifier: A modifier the grammar on :mod:`xtr_clock.modifier`
+                can read.
+
+        Returns:
+            A new instant; this one is unchanged.
+
+        Raises:
+            InvalidModifierError: When the grammar cannot read ``modifier``.
+        """
+        return type(self).from_datetime(apply_modifier(self, modifier))
+
+    def with_timezone(self, timezone: str | tzinfo) -> Self:
+        """Return this same instant, read in another zone.
+
+        The moment does not move — only the wall clock showing it does.
+
+        Args:
+            timezone: A name, an offset, or a resolved zone.
+
+        Raises:
+            InvalidTimezoneError: When ``timezone`` names no known zone.
+        """
+        return self.astimezone(resolve_timezone(timezone))
+
+    def __reduce_ex__(
+        self, protocol: SupportsIndex
+    ) -> tuple[Callable[..., Self], tuple[object, ...]]:
+        """Pickle and copy through :meth:`__reduce__`, which pins the fields.
+
+        The inherited implementation answers pickle directly and never
+        consults ``__reduce__``, so overriding only that one would leave both
+        pickling and copying on the packed path this class does not read.
+        """
+        return self.__reduce__()
+
+    def __reduce__(self) -> tuple[Callable[..., Self], tuple[object, ...]]:
+        """Pickle by field rather than by packed state.
+
+        The inherited form hands the constructor a packed byte string this
+        class does not read. Rebuilding from the fields it does read keeps
+        unpickling on the same path as every other way of making an instant,
+        so a restored one carries the same guarantees.
+        """
+        return (
+            _rebuild,
+            (
+                type(self),
+                self.year,
+                self.month,
+                self.day,
+                self.hour,
+                self.minute,
+                self.second,
+                self.microsecond,
+                self.tzinfo,
+                self.fold,
+            ),
+        )
+
+
+def _rebuild(
+    cls: type[_DatePointT],
+    year: int,
+    month: int,
+    day: int,
+    hour: int,
+    minute: int,
+    second: int,
+    microsecond: int,
+    tzinfo: tzinfo | None,
+    fold: int,
+) -> _DatePointT:
+    """Rebuild a pickled instant. Named at module level so pickle can find it."""
+    return cls(year, month, day, hour, minute, second, microsecond, tzinfo, fold=fold)

xtr_clock/exception/__init__.py

@@ -0,0 +1,17 @@
+"""Every error this library raises.
+
+All of them derive from :class:`ClockError`, so one ``except`` catches
+anything a clock can go wrong with, and a narrower one handles a single
+cause. Each carries the data a caller needs as typed attributes rather than
+forcing a message to be parsed.
+"""
+
+from .clock_error import ClockError
+from .invalid_modifier_error import InvalidModifierError
+from .invalid_timezone_error import InvalidTimezoneError
+
+__all__ = [
+    "ClockError",
+    "InvalidModifierError",
+    "InvalidTimezoneError",
+]

xtr_clock/exception/clock_error.py

@@ -0,0 +1,14 @@
+"""The root every error in this library derives from."""
+
+from __future__ import annotations
+
+__all__ = ["ClockError"]
+
+
+class ClockError(Exception):
+    """Base class for every error raised by this library.
+
+    Catch this to handle anything reading a clock can go wrong with; catch a
+    subclass to handle one cause. Every subclass carries the data a caller
+    needs as typed attributes and composes its own message from them.
+    """