xtr-cache-contracts 1.2.0__py3-none-any.whl

xtr_cache_contracts/__init__.py

@@ -0,0 +1,67 @@
+"""The caching contract: what code that caches depends on, and nothing more.
+
+Code that caches should not decide where values go. It takes a
+:class:`CacheInterface` and hands it a key and the function that computes the
+value; the application decides whether memory, files or a server sit behind
+it — so depending on this package costs a library nothing but the contract.
+
+```python
+async def load_profile(item: ItemInterface) -> Profile:
+    item.expires_after(3600)
+    return await profiles.fetch(user_id)
+
+
+profile = await cache.get(f"profile.{user_id}", load_profile)
+```
+
+Three levels, most code needing only the first:
+
+- :class:`CacheInterface` — fetch-or-compute, and delete.
+  :class:`TagAwareCacheInterface` adds invalidation by tag.
+- :class:`CacheItemPoolInterface` — the items underneath: hits told apart
+  from misses, reads of several keys at once, batched writes. What a backend
+  implements; :class:`CacheMixin` builds :class:`CacheInterface` on it.
+- :class:`NamespacedPoolInterface` — a view of a pool confined to a
+  sub-namespace.
+
+Every call that reaches a backend is awaited. Backends and everything that
+acts on stored values — adapters, serialisation, stampede locks, the bundle —
+are ``xtr-cache``, which implements this contract and re-exports it, so the
+two are never two different objects.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .cache_interface import CacheInterface
+from .cache_item_pool_interface import CacheItemPoolInterface
+from .cache_mixin import CacheMixin
+from .callback import Callback
+from .exception import CacheError, InvalidArgumentError
+from .item_interface import RESERVED_CHARACTERS, ItemInterface
+from .metadata import Metadata
+from .namespaced_pool_interface import NamespacedPoolInterface
+from .tag_aware_cache_interface import TagAwareCacheInterface
+
+try:
+    __version__ = version("xtr-cache-contracts")
+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__ = [
+    "RESERVED_CHARACTERS",
+    "CacheError",
+    "CacheInterface",
+    "CacheItemPoolInterface",
+    "CacheMixin",
+    "Callback",
+    "InvalidArgumentError",
+    "ItemInterface",
+    "Metadata",
+    "NamespacedPoolInterface",
+    "TagAwareCacheInterface",
+    "__version__",
+]

xtr_cache_contracts/cache_interface.py

@@ -0,0 +1,85 @@
+"""Read a value from a cache, computing and storing it when it is missing."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, TypeVar, runtime_checkable
+
+if TYPE_CHECKING:
+    from .callback import Callback
+    from .metadata import Metadata
+
+__all__ = ["CacheInterface"]
+
+_T = TypeVar("_T")
+
+
+@runtime_checkable
+class CacheInterface(Protocol):
+    """Covers most caching needs in two calls: fetch-or-compute, and forget.
+
+    The type code that caches should depend on. Instead of checking for a
+    value, computing it on a miss and saving it — three steps, with a race
+    between each — a caller hands :meth:`get` the function that computes the
+    value, and the cache decides when to call it:
+
+    ```python
+    profile = await cache.get(f"profile.{user_id}", load_profile)
+    ```
+
+    Deciding in one place is what lets an implementation protect a backend
+    from a stampede — many callers missing the same key at once, all
+    computing it — by computing it once and sharing the result, or by
+    refreshing a value shortly before it expires.
+    """
+
+    async def get(
+        self,
+        key: str,
+        callback: Callback[_T],
+        /,
+        *,
+        beta: float | None = None,
+        metadata: Metadata | None = None,
+    ) -> _T:
+        """Return the value cached under ``key``, computing and saving it on a miss.
+
+        On a miss ``callback`` is awaited with the item for ``key``; what it
+        returns is saved and returned. A value that cannot be saved is still
+        returned — the cache is an optimisation, not a dependency — and
+        reported through ``metadata``.
+
+        On a hit the stored value is returned as the type ``callback`` would
+        have returned: keep one key for one type.
+
+        Args:
+            key: The key the value is stored under.
+            callback: Computes the value on a miss.
+            beta: How eagerly to recompute a value before it expires. The
+                chance grows as expiry nears, and faster the larger ``beta``
+                is. ``0`` disables early recomputation; ``math.inf`` forces
+                recomputation now. ``None`` lets the implementation choose,
+                ``1.0`` being the usual choice.
+            metadata: A mapping to fill with the metadata of the value — see
+                :class:`~xtr_cache_contracts.metadata.Metadata` — plus
+                ``save_failed`` when a computed value could not be saved.
+                Keys already in it are overwritten, not cleared.
+
+        Returns:
+            The cached value, or the one ``callback`` computed.
+
+        Raises:
+            InvalidArgumentError: When ``key`` is not a valid key, or ``beta``
+                is negative.
+        """
+        ...
+
+    async def delete(self, key: str, /) -> bool:
+        """Remove the value under ``key``; a key holding nothing is fine.
+
+        Returns:
+            ``False`` when the backend failed; ``True`` otherwise.
+
+        Raises:
+            InvalidArgumentError: When ``key`` is not a valid key.
+        """
+        ...

xtr_cache_contracts/cache_item_pool_interface.py

@@ -0,0 +1,133 @@
+"""A store of cache items: look them up, save them, delete them."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Mapping
+
+    from .item_interface import ItemInterface
+
+__all__ = ["CacheItemPoolInterface"]
+
+
+@runtime_checkable
+class CacheItemPoolInterface(Protocol):
+    """The item-level view of a cache, for code that needs more than fetch-or-compute.
+
+    Most code should depend on
+    :class:`~xtr_cache_contracts.cache_interface.CacheInterface`. This is the
+    level below it: a hit told apart from a miss, several keys read in one
+    round trip, writes batched until :meth:`commit`. It is also the level a
+    backend implements — :class:`~xtr_cache_contracts.cache_mixin.CacheMixin`
+    builds the fetch-or-compute contract on top of it.
+
+    The rules:
+
+    - A key is a non-empty string without any of
+      :data:`~xtr_cache_contracts.item_interface.RESERVED_CHARACTERS`. Letters,
+      digits, ``_`` and ``.`` up to 64 characters work everywhere; a pool may
+      accept more. A key it refuses raises
+      :class:`~xtr_cache_contracts.exception.InvalidArgumentError`.
+    - A backend failure never raises: the call returns ``False``, or reads as
+      a miss, and the implementation logs it. Code that caches keeps working
+      when the cache does not.
+    - A pool saves items of the kind it hands out, and refuses any other by
+      returning ``False``. Pools of one implementation may take each other's
+      items, which is how one pool fills another.
+    """
+
+    async def get_item(self, key: str, /) -> ItemInterface:
+        """Return the item for ``key``, a hit or a miss.
+
+        Raises:
+            InvalidArgumentError: When ``key`` is not a valid key.
+        """
+        ...
+
+    async def get_items(self, keys: Iterable[str], /) -> Mapping[str, ItemInterface]:
+        """Return an item for each of ``keys``, hits and misses alike, in the order asked.
+
+        Raises:
+            InvalidArgumentError: When a key is not a valid key.
+        """
+        ...
+
+    async def has_item(self, key: str, /) -> bool:
+        """Tell whether the pool holds a value for ``key``.
+
+        Do not follow it with :meth:`get_item`: the value may expire in
+        between. Read the item and ask it
+        :meth:`~xtr_cache_contracts.item_interface.ItemInterface.is_hit`
+        instead.
+
+        Raises:
+            InvalidArgumentError: When ``key`` is not a valid key.
+        """
+        ...
+
+    async def clear(self, prefix: str = "") -> bool:
+        """Remove every item whose key starts with ``prefix``; every item, by default.
+
+        Items saved as deferred and not yet committed are dropped too.
+
+        Returns:
+            ``False`` when the backend failed; ``True`` otherwise.
+        """
+        ...
+
+    async def delete_item(self, key: str, /) -> bool:
+        """Remove the item under ``key``; a key holding nothing is fine.
+
+        Returns:
+            ``False`` when the backend failed; ``True`` otherwise.
+
+        Raises:
+            InvalidArgumentError: When ``key`` is not a valid key.
+        """
+        ...
+
+    async def delete_items(self, keys: Iterable[str], /) -> bool:
+        """Remove the items under ``keys``.
+
+        Returns:
+            ``False`` when the backend failed for any of them; ``True``
+            otherwise.
+
+        Raises:
+            InvalidArgumentError: When a key is not a valid key.
+        """
+        ...
+
+    async def save(self, item: ItemInterface, /) -> bool:
+        """Store ``item`` now.
+
+        Returns:
+            ``False`` when the backend failed, or when ``item`` is of a kind
+            the pool does not store; ``True`` otherwise.
+        """
+        ...
+
+    async def save_deferred(self, item: ItemInterface, /) -> bool:
+        """Queue ``item`` to be stored by the next :meth:`commit`.
+
+        Reading a queued item's key from this pool commits the queue first, so
+        the pool never answers with a value older than one it was given.
+        Nothing commits the queue on its own when the pool is discarded: call
+        :meth:`commit`.
+
+        Returns:
+            ``False`` when ``item`` is of a kind the pool does not store;
+            ``True`` otherwise.
+        """
+        ...
+
+    async def commit(self) -> bool:
+        """Store every item queued by :meth:`save_deferred`.
+
+        Returns:
+            ``False`` when the backend failed for any of them; ``True``
+            otherwise.
+        """
+        ...

xtr_cache_contracts/cache_mixin.py

@@ -0,0 +1,169 @@
+"""Fetch-or-compute, for a class that already knows how to read, save and delete items."""
+
+from __future__ import annotations
+
+import math
+from abc import ABC, abstractmethod
+from random import random
+from typing import TYPE_CHECKING, Final, TypeVar, cast
+
+from typing_extensions import override
+from xtr_clock import now
+
+from .cache_interface import CacheInterface
+from .exception.invalid_argument_error import InvalidArgumentError
+
+if TYPE_CHECKING:
+    from .callback import Callback
+    from .item_interface import ItemInterface
+    from .metadata import Metadata
+
+__all__ = ["CacheMixin"]
+
+_T = TypeVar("_T")
+
+_DEFAULT_BETA: Final = 1.0
+"""The ``beta`` used when none is given; what the early-expiry model is tuned for."""
+
+
+class CacheMixin(CacheInterface, ABC):
+    """Implements :class:`~xtr_cache_contracts.cache_interface.CacheInterface` on a pool.
+
+    A class that implements
+    :class:`~xtr_cache_contracts.cache_item_pool_interface.CacheItemPoolInterface`
+    derives from this too and gets :meth:`get` and :meth:`delete` built on its
+    own :meth:`get_item`, :meth:`save` and :meth:`delete_item`. List it after
+    the pool's interfaces, so the pool's own methods are the ones found.
+
+    Early recomputation: a hit whose metadata says when it expires and how
+    long it took to compute may be recomputed before it expires, with a
+    chance that grows as expiry nears. Under load, one caller refreshes the
+    value while the others still read the old one, rather than all of them
+    missing at the same moment. A value stored without that metadata is only
+    recomputed once it has expired. The time is read from the clock in force
+    (:func:`xtr_clock.now`), so freezing it in a test freezes this too.
+
+    :meth:`get` is a template an implementation adjusts through three steps
+    rather than rewrites: :meth:`_compute` — how a missing value is computed
+    and saved, where concurrent misses can be made to share one computation
+    or wait on a lock; :meth:`_now` — which clock is read; and
+    :meth:`_on_elected` — what to do when a hit is elected for early
+    recomputation, such as logging it.
+    """
+
+    @abstractmethod
+    async def get_item(self, key: str, /) -> ItemInterface:
+        """Return the item for ``key``, a hit or a miss."""
+
+    @abstractmethod
+    async def save(self, item: ItemInterface, /) -> bool:
+        """Store ``item`` now; ``False`` when that failed."""
+
+    @abstractmethod
+    async def delete_item(self, key: str, /) -> bool:
+        """Remove the item under ``key``; ``False`` when that failed."""
+
+    @override
+    async def get(
+        self,
+        key: str,
+        callback: Callback[_T],
+        /,
+        *,
+        beta: float | None = None,
+        metadata: Metadata | None = None,
+    ) -> _T:
+        """Return the value under ``key``, computing and saving it on a miss.
+
+        Raises:
+            InvalidArgumentError: When ``key`` is not a valid key, or ``beta``
+                is negative or not a number.
+        """
+        beta = _DEFAULT_BETA if beta is None else beta
+        # Written this way round so that NaN, which compares false to everything, is refused too.
+        if not beta >= 0:
+            raise InvalidArgumentError(f"beta must be zero or more, got {beta!r}")
+
+        item = await self.get_item(key)
+        found = item.metadata
+        if metadata is not None:
+            metadata.update(found)
+
+        if (
+            item.is_hit()
+            and not math.isinf(beta)
+            and not self._elect_early_recomputation(item, found, beta)
+        ):
+            # The key's value was stored by the same callback type, which is the caller's promise.
+            return cast("_T", item.get())
+
+        return await self._compute(item, callback, beta, metadata)
+
+    @override
+    async def delete(self, key: str, /) -> bool:
+        """Remove the value under ``key``; ``False`` when the backend failed."""
+        return await self.delete_item(key)
+
+    async def _compute(
+        self,
+        item: ItemInterface,
+        callback: Callback[_T],
+        beta: float,
+        metadata: Metadata | None,
+    ) -> _T:
+        """Compute the value for ``item`` with ``callback``, save it, and return it.
+
+        A value that cannot be saved is still returned, and reported through
+        ``metadata``. ``beta`` is infinite when the caller forces the value to
+        be computed again.
+        """
+        del beta
+        value = await callback(item)
+        _ = item.set(value)
+        if not await self.save(item) and metadata is not None:
+            metadata["save_failed"] = True
+
+        return value
+
+    def _now(self) -> float:
+        """Return the current time as a Unix timestamp, from the clock in force."""
+        return now().timestamp()
+
+    def _on_elected(self, item: ItemInterface, remaining: float) -> None:
+        """Hear that ``item`` was elected for early recomputation, ``remaining`` seconds early."""
+        del item, remaining
+
+    def _elect_early_recomputation(
+        self,
+        item: ItemInterface,
+        metadata: Metadata,
+        beta: float,
+    ) -> bool:
+        """Decide whether a hit should be recomputed now, ahead of its expiry.
+
+        The value is recomputed when its expiry falls within a random span
+        ahead of now — the time it took to compute, scaled by ``beta`` and by
+        an exponentially distributed factor. Values that are slow to compute
+        are refreshed earlier, and callers spread over time do not all pick
+        the same moment. An elected item has its expiry reset, so the pool's
+        default lifetime applies to the recomputed value unless the callback
+        sets one.
+        """
+        expiry = metadata.get("expiry")
+        ctime = metadata.get("ctime")
+        if not expiry or not ctime:
+            return False
+
+        current = self._now()
+        if expiry > current - ctime / 1000 * beta * math.log(_draw()):
+            return False
+
+        _ = item.expires_at(None)
+        self._on_elected(item, expiry - current)
+
+        return True
+
+
+def _draw() -> float:
+    """Return a random number in ``(0, 1]``, so its logarithm is always defined."""
+    return 1.0 - random()  # noqa: S311 — spreads recomputation over time; nothing here is a secret.

xtr_cache_contracts/callback.py

@@ -0,0 +1,33 @@
+"""What computes a value a cache does not have yet."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import TypeAlias, TypeVar
+
+from .item_interface import ItemInterface
+
+__all__ = ["Callback"]
+
+_T = TypeVar("_T")
+
+Callback: TypeAlias = Callable[[ItemInterface], Awaitable[_T]]
+"""Computes the value for an item, on a miss.
+
+Receives the item the value is for, so it can set how long the value lives
+(:meth:`~xtr_cache_contracts.item_interface.ItemInterface.expires_after`) or
+tag it (:meth:`~xtr_cache_contracts.item_interface.ItemInterface.tag`), and
+returns the value. Asynchronous, because computing a value worth caching is
+usually I/O.
+
+Any ``async def`` taking the item fits, and so does an object with an
+``async def __call__`` taking it. Raising stores nothing: the error reaches
+the caller of :meth:`~xtr_cache_contracts.cache_interface.CacheInterface.get`
+as it was raised.
+
+```python
+async def load_profile(item: ItemInterface) -> Profile:
+    item.expires_after(3600)
+    return await profiles.fetch(user_id)
+```
+"""

xtr_cache_contracts/exception/__init__.py

@@ -0,0 +1,17 @@
+"""The errors the caching contract names.
+
+:class:`CacheError` is the root every caching error derives from, including
+every one an implementation adds, so catching it catches anything caching can
+go wrong with, whichever package raised it. :class:`InvalidArgumentError` is
+the one the interfaces here document raising.
+"""
+
+from __future__ import annotations
+
+from .cache_error import CacheError
+from .invalid_argument_error import InvalidArgumentError
+
+__all__ = [
+    "CacheError",
+    "InvalidArgumentError",
+]

xtr_cache_contracts/exception/cache_error.py

@@ -0,0 +1,20 @@
+"""The root every caching error derives from."""
+
+from __future__ import annotations
+
+__all__ = ["CacheError"]
+
+
+class CacheError(Exception):
+    """Base class for every error raised through the caching contract.
+
+    Catch this to handle anything caching can go wrong with, whichever
+    package raised it; 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.
+
+    A backend failing is not one of those causes: a cache is an optimisation,
+    so a pool reports a backend it cannot reach by returning ``False`` rather
+    than by raising. What does raise is a mistake in the calling code — a key
+    no pool accepts, a tag on an item that cannot carry one.
+    """

xtr_cache_contracts/exception/invalid_argument_error.py

@@ -0,0 +1,28 @@
+"""A cache was given a key, a tag or an option it cannot work with."""
+
+from __future__ import annotations
+
+from .cache_error import CacheError
+
+__all__ = ["InvalidArgumentError"]
+
+
+class InvalidArgumentError(CacheError, ValueError):
+    """A cache was given a key, a tag or an option it cannot work with.
+
+    An empty key, one holding a reserved character, a negative ``beta``.
+    Raised where the argument is given, before anything reaches a backend.
+
+    Also a :class:`ValueError`, so code that already guards its input with
+    ``except ValueError`` keeps working without learning a new exception.
+
+    Attributes:
+        reason: What is wrong with the argument.
+    """
+
+    reason: str
+
+    def __init__(self, reason: str) -> None:
+        """Record what is wrong with the argument."""
+        self.reason = reason
+        super().__init__(reason)

xtr_cache_contracts/item_interface.py

@@ -0,0 +1,93 @@
+"""One cached entry: its key, its value if there is one, and how long it lives."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Final, Protocol, Self, runtime_checkable
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+    from datetime import datetime, timedelta
+
+    from .metadata import Metadata
+
+__all__ = ["RESERVED_CHARACTERS", "ItemInterface"]
+
+RESERVED_CHARACTERS: Final = "{}()/\\@:"
+"""Characters no key and no tag may contain.
+
+Pools use them for their own structure — namespace separators above all — so
+a key holding one could reach into another key's space.
+"""
+
+
+@runtime_checkable
+class ItemInterface(Protocol):
+    """A cache entry as a pool hands it out: looked up, maybe found, ready to save.
+
+    A pool returns an item for every key it is asked about, found or not;
+    :meth:`is_hit` tells which. That is what lets ``None`` be a value like any
+    other rather than a stand-in for "not cached".
+
+    An item is a plain object in memory. Changing it — :meth:`set`,
+    :meth:`expires_after`, :meth:`tag` — reaches the backend only once the item
+    is handed back to the pool it came from, through
+    :meth:`CacheItemPoolInterface.save
+    <xtr_cache_contracts.cache_item_pool_interface.CacheItemPoolInterface.save>`
+    or, inside :meth:`CacheInterface.get
+    <xtr_cache_contracts.cache_interface.CacheInterface.get>`, by the pool
+    itself. The mutators return the item, so calls chain.
+    """
+
+    @property
+    def key(self) -> str:
+        """The key the item is stored under."""
+        ...
+
+    def get(self) -> object:
+        """Return the value; ``None`` when the item is not a hit.
+
+        Typed ``object`` because a pool holds values of any type: narrow it
+        where the type is known. :meth:`CacheInterface.get
+        <xtr_cache_contracts.cache_interface.CacheInterface.get>` does that
+        for you, through the type its callback returns.
+        """
+        ...
+
+    def is_hit(self) -> bool:
+        """Tell whether the pool had a value for the key when the item was looked up."""
+        ...
+
+    def set(self, value: object, /) -> Self:
+        """Set the value to save; the item is not saved until the pool is told to."""
+        ...
+
+    def expires_at(self, expiration: datetime | None, /) -> Self:
+        """Expire the item at ``expiration``; ``None`` falls back to the pool's default."""
+        ...
+
+    def expires_after(self, ttl: float | timedelta | None, /) -> Self:
+        """Expire the item ``ttl`` from now, in seconds or as a duration.
+
+        A lifetime of zero or less expires the item at once: saving it removes
+        whatever the pool held under its key. ``None`` falls back to the
+        pool's default.
+        """
+        ...
+
+    def tag(self, tags: str | Iterable[str], /) -> Self:
+        """Add one tag, or several, to invalidate the item by later.
+
+        Tags follow the same rules as keys.
+
+        Raises:
+            InvalidArgumentError: When a tag is empty or holds a reserved
+                character.
+            CacheError: When the item comes from a pool that cannot store
+                tags.
+        """
+        ...
+
+    @property
+    def metadata(self) -> Metadata:
+        """What the pool stored alongside the value; empty when it stored nothing."""
+        ...

xtr_cache_contracts/metadata.py

@@ -0,0 +1,37 @@
+"""What a pool stores alongside a value, and reports back about it."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, TypedDict
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+__all__ = ["Metadata"]
+
+
+class Metadata(TypedDict, total=False):
+    """Facts about a cached value, every one of them optional.
+
+    A pool that records none returns an empty mapping. The keys a pool fills
+    in are what makes early recomputation possible: knowing when a value
+    expires and how long it took to compute is enough to refresh it shortly
+    before it runs out, instead of making every caller wait once it has.
+
+    Attributes:
+        expiry: When the value expires, as a Unix timestamp in seconds. Wall
+            clock rather than monotonic, because the value is shared with
+            other processes and other machines.
+        ctime: How long the value took to compute, in milliseconds.
+        tags: The tags the value was saved with.
+        save_failed: Set by :meth:`CacheInterface.get
+            <xtr_cache_contracts.cache_interface.CacheInterface.get>` when the
+            value it computed could not be saved. Never stored, so never in
+            :attr:`ItemInterface.metadata
+            <xtr_cache_contracts.item_interface.ItemInterface.metadata>`.
+    """
+
+    expiry: float
+    ctime: int
+    tags: Sequence[str]
+    save_failed: bool

xtr_cache_contracts/namespaced_pool_interface.py

@@ -0,0 +1,29 @@
+"""A pool that can hand out a view of itself confined to a sub-namespace."""
+
+from __future__ import annotations
+
+from typing import Protocol, Self, runtime_checkable
+
+__all__ = ["NamespacedPoolInterface"]
+
+
+@runtime_checkable
+class NamespacedPoolInterface(Protocol):
+    """Confines keys to a sub-namespace, so a group of them can be dropped at once.
+
+    Keys written through the returned pool are prefixed with the backend's
+    own namespace separator, so clearing that namespace invalidates them
+    together without listing them. Tags ignore sub-namespaces: invalidating a
+    tag reaches a value whichever sub-namespace it was saved in.
+    """
+
+    def with_sub_namespace(self, namespace: str, /) -> Self:
+        """Return a pool whose keys live under ``namespace``, inside this pool's namespace.
+
+        This pool is left as it was; the returned one is new.
+
+        Raises:
+            InvalidArgumentError: When ``namespace`` is empty or holds a
+                reserved character.
+        """
+        ...

xtr_cache_contracts/tag_aware_cache_interface.py

@@ -0,0 +1,47 @@
+"""A cache whose values can be invalidated in groups, by tag."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+from .cache_interface import CacheInterface
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+__all__ = ["TagAwareCacheInterface"]
+
+
+@runtime_checkable
+class TagAwareCacheInterface(CacheInterface, Protocol):
+    """A cache that can drop every value carrying a tag, without knowing their keys.
+
+    A value is tagged when it is computed, through the item its callback
+    receives:
+
+    ```python
+    async def load_invoice(item: ItemInterface) -> Invoice:
+        item.tag(f"customer.{customer_id}")
+        return await invoices.fetch(invoice_id)
+    ```
+
+    Invalidating ``customer.42`` later drops every invoice cached for that
+    customer, whatever it was cached under.
+    """
+
+    async def invalidate_tags(self, tags: Iterable[str], /) -> bool:
+        """Invalidate every value tagged with any of ``tags``.
+
+        An implementation built on an item pool does not invalidate items
+        saved as deferred and not yet committed; they are committed as usual.
+        That lets a caller replace old tagged values with new ones without a
+        window where neither is cached.
+
+        Returns:
+            ``False`` when the backend failed; ``True`` otherwise.
+
+        Raises:
+            InvalidArgumentError: When a tag is empty or holds a reserved
+                character.
+        """
+        ...

xtr_cache_contracts-1.2.0.dist-info/METADATA

@@ -0,0 +1,239 @@
+Metadata-Version: 2.4
+Name: xtr-cache-contracts
+Version: 1.2.0
+Summary: The caching contract: compute-once reads, item pools, tags and namespaces, with no backend attached.
+Keywords: cache,contracts,interface,protocol,asyncio,stampede
+Author: Razvan Ceana
+Author-email: Razvan Ceana <razvan@ceana.ro>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Dist: typing-extensions>=4.4
+Requires-Dist: xtr-clock>=1.0,<2
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# xtr-cache-contracts
+
+**The caching contract, and nothing else — so a library that caches installs nothing else.**
+
+<img alt="python 3.11+" src="https://img.shields.io/badge/python-%E2%89%A5%203.11-3776AB?logo=python&logoColor=white">
+<img alt="asyncio" src="https://img.shields.io/badge/asyncio-native-1f6feb">
+<img alt="core dependencies: 2" src="https://img.shields.io/badge/core%20deps-2-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">
+
+</div>
+
+---
+
+## Why?
+
+A library that caches should not decide where values go. It takes a `CacheInterface`, hands it a
+key and the function that computes the value, and leaves memory, files or a server to the
+application that wires it.
+
+That needs the *contract*, not a backend. This package is that dependency, reduced to what the
+seam is made of:
+
+- 🔁 **`CacheInterface`** — fetch-or-compute in one call, and delete.
+- 🏷️ **`TagAwareCacheInterface`** — drop every value carrying a tag, whatever its key.
+- 🗃️ **`CacheItemPoolInterface`** — the items underneath: hits told apart from misses, several
+  keys per round trip, batched writes.
+- 📁 **`NamespacedPoolInterface`** — a view of a pool confined to a sub-namespace.
+- 🧩 **`CacheMixin`** — `CacheInterface` for free on any pool, with early recomputation.
+- 🪶 **Two small dependencies** — `typing-extensions`, for `@override` on 3.11, and
+  `xtr-clock`, which has none of its own.
+
+```python
+from xtr_cache_contracts import CacheInterface, ItemInterface
+
+
+class Profiles:
+    def __init__(self, cache: CacheInterface) -> None:
+        self._cache = cache
+
+    async def get(self, user_id: int) -> Profile:
+        async def load(item: ItemInterface) -> Profile:
+            item.expires_after(3600)
+            return await fetch_profile(user_id)
+
+        return await self._cache.get(f"profile.{user_id}", load)
+```
+
+## Install
+
+```sh
+uv add xtr-cache-contracts
+```
+
+Requires Python 3.11+.
+
+## Who installs what
+
+|  | Depends on |
+| --- | --- |
+| **A library that caches** | `xtr-cache-contracts` at runtime. |
+| **An application** | `xtr-cache`, which implements this contract with adapters and wires pools from configuration. |
+
+`xtr-cache` **re-exports** every symbol here rather than redefining it, so
+`xtr_cache.CacheInterface is xtr_cache_contracts.CacheInterface`. That identity is what lets a
+container register a pool under the interface and a library, which never imported `xtr-cache`,
+receive it.
+
+## Fetch-or-compute
+
+```python
+class CacheInterface(Protocol):
+    async def get(
+        self,
+        key: str,
+        callback: Callback[T],
+        /,
+        *,
+        beta: float | None = None,
+        metadata: Metadata | None = None,
+    ) -> T: ...
+
+    async def delete(self, key: str, /) -> bool: ...
+```
+
+On a miss, `callback` is awaited with the item for `key`; what it returns is saved and returned.
+On a hit, the stored value comes back as the type `callback` returns — keep one key for one type.
+
+Checking for a value, computing it and saving it is three steps with a race between each. Handing
+the cache the computation instead lets it decide when to run it, which is what makes stampede
+protection possible: computing a missing key once for every caller waiting on it, or refreshing
+a value just before it expires.
+
+- **The callback** is any `async def` taking the item, or an object with an `async def __call__`.
+  It sets the value's lifetime and tags through the item. If it raises, nothing is stored and
+  the error reaches the caller unchanged.
+- **`beta`** controls early recomputation. A hit whose metadata says when it expires and how long
+  it took to compute may be recomputed before it expires, with a chance that grows as expiry
+  nears and as `beta` grows. `0` disables it, `math.inf` forces recomputation now, and `None`
+  leaves the choice to the implementation (`1.0` in `CacheMixin`).
+- **`metadata`** is a dict the cache fills: `expiry` (Unix timestamp), `ctime` (milliseconds the
+  value took to compute), `tags`, and `save_failed` when a computed value could not be stored.
+
+```python
+from xtr_cache_contracts import Metadata
+
+metadata: Metadata = {}
+report = await cache.get("report.daily", build_report, metadata=metadata)
+if metadata.get("save_failed"):
+    ...
+```
+
+## Items and pools
+
+`CacheItemPoolInterface` is the level below: for code that needs a hit told apart from a miss,
+several keys in one round trip, or writes batched until `commit()` — and the level a backend
+implements.
+
+```python
+item = await pool.get_item("rate.42")
+if not item.is_hit():
+    await pool.save(item.set(0).expires_after(60))
+
+items = await pool.get_items(["a", "b", "c"])  # every key, hit or miss, in the order asked
+await pool.save_deferred(item)  # queued ...
+await pool.commit()  # ... stored
+```
+
+An item is returned for every key, found or not, so `None` is a value like any other. Changing
+an item reaches the backend only once it is saved. A pool refuses, with `False`, an item of a kind
+it does not store.
+
+The rules:
+
+- **Keys** are non-empty strings without any of `{}()/\@:` (`RESERVED_CHARACTERS`). Letters,
+  digits, `_` and `.` up to 64 characters work everywhere; a pool may accept more. Tags follow
+  the same rules.
+- **A backend failure never raises.** The call returns `False`, or reads as a miss, and the
+  implementation logs it: code that caches keeps working when the cache does not. What raises
+  is a mistake in the calling code — an invalid key, a tag on an item whose pool cannot store
+  tags.
+- **Lifetimes** are set on the item: `expires_after(seconds or timedelta)` or
+  `expires_at(datetime)`. `None` falls back to the pool's default; a lifetime of zero or less
+  removes the key when the item is saved.
+- **Deferred items** are committed by `commit()`, or before their key is read from the same pool.
+  Nothing commits them when the pool is discarded.
+
+## Tags and namespaces
+
+A tag-aware cache drops values by tag rather than by key. Tag a value when computing it:
+
+```python
+async def load_invoice(item: ItemInterface) -> Invoice:
+    item.tag([f"customer.{customer_id}", "invoices"])
+    return await fetch_invoice(invoice_id)
+
+
+await cache.get(f"invoice.{invoice_id}", load_invoice)
+await cache.invalidate_tags([f"customer.{customer_id}"])  # every invoice of that customer
+```
+
+A namespaced pool hands out a view of itself whose keys live under a sub-namespace, so a group of
+keys can be cleared together: `pool.with_sub_namespace("tenant42")`. The original pool is left as
+it was. Tags ignore sub-namespaces.
+
+## Implementing a pool
+
+Implement `CacheItemPoolInterface` and derive from `CacheMixin` to get `get()` and `delete()`
+built on your `get_item()`, `save()` and `delete_item()`:
+
+```python
+from xtr_cache_contracts import CacheItemPoolInterface, CacheMixin
+
+
+class MyPool(CacheItemPoolInterface, CacheMixin): ...
+```
+
+`CacheMixin` computes a miss, saves it, reports a failed save in `metadata`, and recomputes a hit
+early when its metadata allows. It reads the time from the clock in force (`xtr_clock.now()`),
+so `mock_time()` or a `MockClock` installed by a test freezes it too. It does not make concurrent misses on one key compute once — that
+needs a lock or a shared in-flight computation, and is the implementation's to add by overriding
+`get()`.
+
+## What is not here
+
+Everything that stores or acts on values: the item class, adapters for memory, files and Redis,
+serialisation, stampede locking, chaining, and the bundle. All of that is
+[xtr-cache](https://github.com/xterr/python-xtr-cache).
+
+There is no simple key-value interface (`get(key, default)` / `set(key, value, ttl)`): it cannot
+tell a cached `None` from a miss, and checking then reading is a race. Fetch-or-compute covers the
+common case, and the item pool covers the rest.
+
+## Errors
+
+| Error | Raised when |
+| --- | --- |
+| `CacheError` | Never directly — the base every caching error derives from, `xtr-cache`'s included, such as the one `tag()` raises on an item whose pool cannot store tags |
+| `InvalidArgumentError` | A key, a tag, a namespace or `beta` is invalid (also a `ValueError`); what is wrong is in `reason` |
+
+## Development
+
+Developed in the [python-xtr](https://github.com/xterr/python-xtr) monorepo, under
+`packages/xtr-cache-contracts`; run the commands below from there. The
+`python-xtr-cache-contracts` repository is a read-only copy, so send issues and pull requests to
+the monorepo.
+
+```sh
+uv sync
+uv run ruff check && uv run ruff format --check && uv run basedpyright && uv run ty check && uv run pytest
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

xtr_cache_contracts-1.2.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+xtr_cache_contracts/__init__.py,sha256=ACsLYZsgturVqjAPrZ5QQxYecWk5zlMvll4jRWaTxvU,2455
+xtr_cache_contracts/cache_interface.py,sha256=mlRJfCwO-sPktkxN5jmsB8-Ey_UnqZnl2CXwMQh5qts,3090
+xtr_cache_contracts/cache_item_pool_interface.py,sha256=IeEGNCSbAC8np80YcD-DstAfvulMcmPwYzDCmbFnrjU,4544
+xtr_cache_contracts/cache_mixin.py,sha256=bc9sK7RmXPvqx8WE-SF_8yDWEnX1pQkx0p7jMNYNeEI,6278
+xtr_cache_contracts/callback.py,sha256=5gmOBm43JeEWYTLtSmoYEtfUdaxP5W5rg34xxgVTs_4,1081
+xtr_cache_contracts/exception/__init__.py,sha256=T8t2AuVMuyX5yx0dhuurxRNVUxr_b_QhcyYaYtBkLVM,515
+xtr_cache_contracts/exception/cache_error.py,sha256=fbO2QTMCB_jNhx_NvZWzQv0_Zq9SkXQFbR1Skv6_chE,767
+xtr_cache_contracts/exception/invalid_argument_error.py,sha256=NX4WdrTCL0pLvsgn-pKytP_vFreYvSJz2YJwkjwECkg,858
+xtr_cache_contracts/item_interface.py,sha256=2Wp_HDUUlPCcMOEDY0Fsb1PsGLjRJp28baCF5VTk6-U,3308
+xtr_cache_contracts/metadata.py,sha256=PP0Pi2wuu2101feeKsWH6302Ghu7JkHPyBVrDfT8YGk,1387
+xtr_cache_contracts/namespaced_pool_interface.py,sha256=-6GpGEX9OZ7_vF7vdvk8wdlQXz00lW8ilF93nuu_HNU,1019
+xtr_cache_contracts/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+xtr_cache_contracts/tag_aware_cache_interface.py,sha256=y8UWZQ2umFCbJeWxPCye7B6WlPFShWVJTuGgY4mZvRw,1490
+xtr_cache_contracts-1.2.0.dist-info/licenses/LICENSE,sha256=Jc61y5SgAtm5uDf7mEdR5fxnx6z0RsmS7V4P1dE0TF0,1062
+xtr_cache_contracts-1.2.0.dist-info/WHEEL,sha256=e4_1dyBeezi8ZjfxrZ3bnVOxFDa3ksqVqH0jTHkUZ3k,81
+xtr_cache_contracts-1.2.0.dist-info/METADATA,sha256=Wh-a3RZGzpwKSPi7zqfNebW0ZuPXbY_uECI1uw4fBoM,9561
+xtr_cache_contracts-1.2.0.dist-info/RECORD,,

xtr_cache_contracts-1.2.0.dist-info/WHEEL

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

xtr_cache_contracts-1.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xterr
+
+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.