xtr-cache 3.0.0__tar.gz → 4.0.2__tar.gz

{xtr_cache-3.0.0 → xtr_cache-4.0.2}/LICENSE

@@ -1,6 +1,7 @@
 MIT License
 
 Copyright (c) 2026 xterr
+Copyright (c) 2016-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_cache-3.0.0 → xtr_cache-4.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xtr-cache
-Version: 3.0.0
+Version: 4.0.2
 Summary: Cache pools in memory, in files, in Redis, chained or tag-aware, with stampede protection.
 Keywords: cache,redis,stampede,tags,asyncio
 Author: Xterr
@@ -16,14 +16,14 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Typing :: Typed
 Requires-Dist: typing-extensions>=4.4
-Requires-Dist: xtr-cache-contracts>=3.0,<4
-Requires-Dist: xtr-clock>=3.0,<4
-Requires-Dist: xtr-lock>=3.0,<4
-Requires-Dist: xtr-logging-contracts>=3.0,<4
-Requires-Dist: xtr-console>=3.0,<4 ; extra == 'console'
-Requires-Dist: xtr-dependency-injection>=3.0,<4 ; extra == 'di'
-Requires-Dist: xtr-service-contracts>=3.0,<4 ; extra == 'di'
-Requires-Dist: xtr-logging>=3.0,<4 ; extra == 'logging'
+Requires-Dist: xtr-cache-contracts>=4.0,<5
+Requires-Dist: xtr-clock>=4.0,<5
+Requires-Dist: xtr-lock>=4.0,<5
+Requires-Dist: xtr-logging-contracts>=4.0,<5
+Requires-Dist: xtr-console>=4.0,<5 ; extra == 'console'
+Requires-Dist: xtr-dependency-injection>=4.0,<5 ; extra == 'di'
+Requires-Dist: xtr-service-contracts>=4.0,<5 ; extra == 'di'
+Requires-Dist: xtr-logging>=4.0,<5 ; extra == 'logging'
 Requires-Dist: redis>=5.0 ; extra == 'redis'
 Requires-Dist: pynacl>=1.5 ; extra == 'sodium'
 Requires-Python: >=3.11
@@ -190,8 +190,8 @@ await pool.close()  # ... which it closes
 
 Each value is a string key, `namespace:key`, expired by the server itself. Reads fetch many keys
 in one round trip, writes are pipelined, and clearing scans the namespace and unlinks its keys in
-batches — so set a namespace when the database holds anything else: without one, clearing empties
-the database. A client built from a DSN gives up on a server silent for 5 seconds — a miss, or a
+batches — so a namespace is required: without one, clearing would empty the database. A client
+built from a DSN gives up on a server silent for 5 seconds — a miss, or a
 failed write — unless `?socket_timeout=` and `?socket_connect_timeout=` in the DSN say otherwise.
 One server; not a cluster, not Sentinel.
 

{xtr_cache-3.0.0 → xtr_cache-4.0.2}/README.md

@@ -154,8 +154,8 @@ await pool.close()  # ... which it closes
 
 Each value is a string key, `namespace:key`, expired by the server itself. Reads fetch many keys
 in one round trip, writes are pipelined, and clearing scans the namespace and unlinks its keys in
-batches — so set a namespace when the database holds anything else: without one, clearing empties
-the database. A client built from a DSN gives up on a server silent for 5 seconds — a miss, or a
+batches — so a namespace is required: without one, clearing would empty the database. A client
+built from a DSN gives up on a server silent for 5 seconds — a miss, or a
 failed write — unless `?socket_timeout=` and `?socket_connect_timeout=` in the DSN say otherwise.
 One server; not a cluster, not Sentinel.
 

{xtr_cache-3.0.0 → xtr_cache-4.0.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "xtr-cache"
-version = "3.0.0"
+version = "4.0.2"
 description = "Cache pools in memory, in files, in Redis, chained or tag-aware, with stampede protection."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -25,10 +25,10 @@ classifiers = [
 ]
 dependencies = [
     "typing-extensions>=4.4",
-    "xtr-cache-contracts>=3.0,<4",
-    "xtr-clock>=3.0,<4",
-    "xtr-lock>=3.0,<4",
-    "xtr-logging-contracts>=3.0,<4",
+    "xtr-cache-contracts>=4.0,<5",
+    "xtr-clock>=4.0,<5",
+    "xtr-lock>=4.0,<5",
+    "xtr-logging-contracts>=4.0,<5",
 ]
 
 [[project.authors]]
@@ -39,11 +39,11 @@ email = "me@xterr.dev"
 redis = ["redis>=5.0"]
 sodium = ["pynacl>=1.5"]
 di = [
-    "xtr-dependency-injection>=3.0,<4",
-    "xtr-service-contracts>=3.0,<4",
+    "xtr-dependency-injection>=4.0,<5",
+    "xtr-service-contracts>=4.0,<5",
 ]
-console = ["xtr-console>=3.0,<4"]
-logging = ["xtr-logging>=3.0,<4"]
+console = ["xtr-console>=4.0,<5"]
+logging = ["xtr-logging>=4.0,<5"]
 
 [project.entry-points."xtr_dependency_injection.bundles"]
 cache = "xtr_cache.bundle:CacheBundle"
@@ -61,10 +61,10 @@ dev = [
     "ty>=0.0.83",
     "pynacl>=1.5",
     "redis>=5.0",
-    "xtr-console>=3.0,<4",
-    "xtr-dependency-injection>=3.0,<4",
-    "xtr-logging>=3.0,<4",
-    "xtr-service-contracts>=3.0,<4",
+    "xtr-console>=4.0,<5",
+    "xtr-dependency-injection>=4.0,<5",
+    "xtr-logging>=4.0,<5",
+    "xtr-service-contracts>=4.0,<5",
 ]
 
 [build-system]

{xtr_cache-3.0.0 → xtr_cache-4.0.2}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "xtr-cache"
-version = "3.0.0"
+version = "4.0.2"
 description = "Cache pools in memory, in files, in Redis, chained or tag-aware, with stampede protection."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -22,10 +22,10 @@ classifiers = [
 ]
 dependencies = [
     "typing-extensions>=4.4",
-    "xtr-cache-contracts>=3.0,<4",
-    "xtr-clock>=3.0,<4",
-    "xtr-lock>=3.0,<4",
-    "xtr-logging-contracts>=3.0,<4",
+    "xtr-cache-contracts>=4.0,<5",
+    "xtr-clock>=4.0,<5",
+    "xtr-lock>=4.0,<5",
+    "xtr-logging-contracts>=4.0,<5",
 ]
 
 [project.optional-dependencies]
@@ -36,14 +36,14 @@ sodium = [
     "pynacl>=1.5",
 ]
 di = [
-    "xtr-dependency-injection>=3.0,<4",
-    "xtr-service-contracts>=3.0,<4",
+    "xtr-dependency-injection>=4.0,<5",
+    "xtr-service-contracts>=4.0,<5",
 ]
 console = [
-    "xtr-console>=3.0,<4",
+    "xtr-console>=4.0,<5",
 ]
 logging = [
-    "xtr-logging>=3.0,<4",
+    "xtr-logging>=4.0,<5",
 ]
 
 # Advertises the bundle so debug:bundles can name it when installed but not listed.
@@ -65,10 +65,10 @@ dev = [
     "ty>=0.0.83",
     "pynacl>=1.5",
     "redis>=5.0",
-    "xtr-console>=3.0,<4",
-    "xtr-dependency-injection>=3.0,<4",
-    "xtr-logging>=3.0,<4",
-    "xtr-service-contracts>=3.0,<4",
+    "xtr-console>=4.0,<5",
+    "xtr-dependency-injection>=4.0,<5",
+    "xtr-logging>=4.0,<5",
+    "xtr-service-contracts>=4.0,<5",
 ]
 
 [build-system]

{xtr_cache-3.0.0 → xtr_cache-4.0.2}/src/xtr_cache/.agents/skills/xtr-cache/SKILL.md

@@ -158,7 +158,7 @@ rotation.
 
       with mock_time("2026-01-01 00:00:00") as clock:
           first = await invoices.get(7)
-          assert await invoices.get(7) is first  # a hit; nothing fetched
+          assert await invoices.get(7) == first  # a hit; a serialized pool hands back a copy
 
           clock.sleep(601)
           assert await invoices.get(7) is not first
@@ -271,7 +271,7 @@ them: it is logged, and the call misses or returns `False`.
 - Do not mutate what `get()` returned and expect the cache to keep the original — concurrent
   callers get the same object. Copy first.
 - Do not put a reserved character in a key; `{}()/\@:` raise `InvalidArgumentError`.
-- Do not run a `RedisAdapter` without a namespace on a database holding anything else — `clear()`
-  empties it — and do not leave one built by `from_url` unclosed.
+- Do not leave a `RedisAdapter` built by `from_url` unclosed. A namespace is required: without
+  one, `clear()` would empty the whole database.
 - Do not pickle from a backend others can write to. Use `SodiumMarshaller`.
 - Do not sleep in a test to let a value expire. Freeze the clock with `mock_time`.

{xtr_cache-3.0.0 → xtr_cache-4.0.2}/src/xtr_cache/.agents/skills/xtr-cache/references/adapters.md

@@ -45,8 +45,9 @@ await pool.close()  # ... which it closes
 ```
 
 Each value is one string key, `namespace:key`, expired by the server. Reads fetch many keys in one
-round trip, writes are pipelined, and `clear()` scans the namespace and unlinks in batches — so
-always set a namespace when the database holds anything else. A client built from a DSN gives up
+round trip, writes are pipelined, and `clear()` scans the namespace and unlinks in batches — so a
+namespace is required: without one, `clear()` would empty the whole database. A client built from a
+DSN gives up
 on a server silent for 5 seconds unless `?socket_timeout=` and `?socket_connect_timeout=` say
 otherwise. One server; not a cluster, not Sentinel. Needs the `redis` extra and a client returning
 bytes: one made with `decode_responses=True` raises `InvalidArgumentError`.

xtr_cache-4.0.2/src/xtr_cache/_internal_key.py

@@ -0,0 +1,22 @@
+"""A key the library forms for itself, exempt from the user-key character rules."""
+
+from __future__ import annotations
+
+from typing import final
+
+__all__ = ["InternalKey"]
+
+
+@final
+class InternalKey(str):
+    """A key a pool builds internally, trusted past :meth:`CacheItem.validate_key`.
+
+    A tag-aware pool keeps each tag's version under a key starting with a
+    control character, so no user key — none of which may hold one — can ever
+    name it. :meth:`~xtr_cache.cache_item.CacheItem.validate_key` refuses those
+    characters for every key it is handed, which would refuse the version keys
+    too; marking them as this type lets the pool reach its own keys without
+    reopening that door to a caller.
+    """
+
+    __slots__ = ()

{xtr_cache-3.0.0 → xtr_cache-4.0.2}/src/xtr_cache/adapter/abstract_adapter.py

@@ -11,7 +11,6 @@ from typing import TYPE_CHECKING, ClassVar, Final, Self
 from typing_extensions import override
 from xtr_cache_contracts import InvalidArgumentError, NamespacedPoolInterface
 
-from xtr_cache._digest import urlsafe_digest
 from xtr_cache.cache_item import CacheItem
 from xtr_cache.exception.marshalling_error import MarshallingError
 
@@ -45,17 +44,12 @@ class AbstractAdapter(
     cannot be reached makes reads miss and writes return ``False``; the code
     caching keeps running.
 
-    An identifier is the pool's namespace followed by the key. A backend with
-    a limit on identifier length sets :attr:`max_id_length`, and keys that
-    would exceed it are hashed.
+    An identifier is the pool's namespace followed by the key.
     """
 
     NS_SEPARATOR: ClassVar[str] = ":"
     """What separates a namespace from what follows it in an identifier."""
 
-    max_id_length: ClassVar[int | None] = None
-    """The longest identifier the backend takes, or ``None`` for no limit."""
-
     _namespace: str
     _default_lifetime: float
     _clock: ClockInterface
@@ -80,8 +74,7 @@ class AbstractAdapter(
 
         Raises:
             InvalidArgumentError: When ``namespace`` is not a valid key once
-                its separators are removed, has an empty sub-namespace, or
-                leaves no room for keys within :attr:`max_id_length`.
+                its separators are removed, or has an empty sub-namespace.
         """
         if namespace:
             if self.NS_SEPARATOR * 2 in namespace:
@@ -89,11 +82,6 @@ class AbstractAdapter(
                     f'Cache namespace "{namespace}" contains an empty sub-namespace.',
                 )
             _ = CacheItem.validate_key(namespace.replace(self.NS_SEPARATOR, ""))
-            if self.max_id_length is not None and len(namespace) > self.max_id_length - 24:
-                raise InvalidArgumentError(
-                    f"A cache namespace must be {self.max_id_length - 24} characters at most, "
-                    f"got {len(namespace)}.",
-                )
             namespace += self.NS_SEPARATOR
 
         self._namespace = namespace
@@ -314,16 +302,12 @@ class AbstractAdapter(
         return CacheItem.from_stored(key, stored, clock=self._clock)
 
     def _get_id(self, key: str) -> str:
-        """Return the backend identifier of ``key``, hashing it when it would be too long.
+        """Return the backend identifier of ``key``: the namespace, then the key.
 
         Raises:
             InvalidArgumentError: When ``key`` is not a valid key.
         """
-        id_ = self._namespace + CacheItem.validate_key(key)
-        if self.max_id_length is None or len(id_) <= self.max_id_length:
-            return id_
-
-        return self._namespace + urlsafe_digest(key, size=16) + self.NS_SEPARATOR
+        return self._namespace + CacheItem.validate_key(key)
 
     def _unmarshall_found(
         self,

{xtr_cache-3.0.0 → xtr_cache-4.0.2}/src/xtr_cache/adapter/adapter_factory.py

@@ -32,6 +32,7 @@ __all__ = ["AdapterFactory"]
 _FILESYSTEM: Final = "filesystem"
 _FILESYSTEM_PREFIX: Final = "filesystem://"
 _KEYWORDS: Final = ("array", "null", _FILESYSTEM)
+_PRUNEABLE_KEYWORDS: Final = ("array", _FILESYSTEM)
 
 
 @final
@@ -136,3 +137,17 @@ class AdapterFactory:
         raise InvalidArgumentError(
             f'Unsupported cache connection: "{describe_connection_scheme(connection)}".'
         )
+
+    @staticmethod
+    def serves_pruneable(connection: object) -> bool:
+        """Tell whether ``connection`` names an adapter whose backend keeps expired values.
+
+        A memory or filesystem pool holds a value's slot until something drops
+        it, so pruning frees them; a Redis server and the null pool expire or
+        keep nothing of their own, so pruning one does nothing. Read from the
+        configuration, so a command can skip a pool it cannot prune without
+        building it — without reaching a server.
+        """
+        return isinstance(connection, str) and (
+            connection in _PRUNEABLE_KEYWORDS or connection.startswith(_FILESYSTEM_PREFIX)
+        )

{xtr_cache-3.0.0 → xtr_cache-4.0.2}/src/xtr_cache/adapter/array_adapter.py

@@ -3,12 +3,13 @@
 from __future__ import annotations
 
 import dataclasses
-from typing import TYPE_CHECKING, cast, final
+from typing import TYPE_CHECKING, Final, cast, final
 
 from typing_extensions import override
 
 from xtr_cache.exception import InvalidArgumentError, MarshallingError
 from xtr_cache.marshaller.default_marshaller import DefaultMarshaller
+from xtr_cache.pruneable_interface import PruneableInterface
 from xtr_cache.value_wrapper import ValueWrapper
 
 from .abstract_adapter import AbstractAdapter
@@ -22,9 +23,12 @@ if TYPE_CHECKING:
 
 __all__ = ["ArrayAdapter"]
 
+_PRUNE_EVERY: Final = 1000
+"""How many values are saved between the sweeps that drop what has expired."""
+
 
 @final
-class ArrayAdapter(AbstractAdapter):
+class ArrayAdapter(AbstractAdapter, PruneableInterface):
     """Keeps values in a dictionary, for tests and for caching within one process.
 
     Values are stored serialized by default, so what a caller gets back is a
@@ -34,6 +38,11 @@ class ArrayAdapter(AbstractAdapter):
 
     Every method completes without awaiting, so tasks on one event loop never
     see it half-updated. Two instances share nothing.
+
+    Nothing expires an entry on its own: a read drops the one it finds expired,
+    and every ``1000`` saves sweep the rest, so a churn of short-lived keys
+    does not grow the dictionary without bound. :meth:`prune` sweeps them on
+    demand.
     """
 
     _values: dict[str, tuple[object, float | None]]
@@ -41,6 +50,7 @@ class ArrayAdapter(AbstractAdapter):
     _max_lifetime: float
     _max_items: int
     _marshaller: MarshallerInterface
+    _saves: int
 
     def __init__(  # noqa: PLR0913 — every option past the lifetime is keyword-only.
         self,
@@ -81,6 +91,7 @@ class ArrayAdapter(AbstractAdapter):
         self._max_lifetime = max_lifetime
         self._max_items = max_items
         self._marshaller = marshaller if marshaller is not None else DefaultMarshaller()
+        self._saves = 0
 
     def values(self) -> dict[str, object]:
         """Return every live value by identifier, as stored; for tests."""
@@ -91,6 +102,12 @@ class ArrayAdapter(AbstractAdapter):
             if expiry is None or expiry > now
         }
 
+    @override
+    async def prune(self) -> bool:
+        """Drop every value whose expiry has passed."""
+        self._prune(self._clock.now().timestamp())
+        return True
+
     @override
     async def _do_fetch(self, ids: Sequence[str]) -> Mapping[str, object]:
         now = self._clock.now().timestamp()
@@ -162,8 +179,20 @@ class ArrayAdapter(AbstractAdapter):
             while len(self._values) > self._max_items:
                 del self._values[next(iter(self._values))]
 
+        self._saves += len(stored)
+        if self._saves >= _PRUNE_EVERY:
+            self._saves = 0
+            self._prune(self._clock.now().timestamp())
+
         return failed or True
 
+    def _prune(self, now: float) -> None:
+        """Drop every value whose expiry is at or before ``now``."""
+        for id_ in [
+            id_ for id_, (_, expiry) in self._values.items() if expiry is not None and expiry <= now
+        ]:
+            del self._values[id_]
+
     @override
     def __repr__(self) -> str:
         return f"{type(self).__name__}({self._default_lifetime!r})"

{xtr_cache-3.0.0 → xtr_cache-4.0.2}/src/xtr_cache/adapter/chain_adapter.py

@@ -90,6 +90,7 @@ class ChainAdapter(ContractsMixin, AdapterInterface, NamespacedPoolInterface, Pr
         found: dict[str, CacheItem] = {}
         missing = wanted
         missed: list[AdapterInterface] = []
+        written: list[AdapterInterface] = []
         for adapter in self._adapters:
             if not missing:
                 break
@@ -99,10 +100,12 @@ class ChainAdapter(ContractsMixin, AdapterInterface, NamespacedPoolInterface, Pr
                     found[key] = item
                     for faster in missed:
                         _ = await faster.save_deferred(self._copy(item))
+                        if faster not in written:
+                            written.append(faster)
             missing = [key for key in missing if key not in found]
             missed.append(adapter)
 
-        for faster in missed:
+        for faster in written:
             _ = await faster.commit()
 
         return {key: found.get(key) or CacheItem(key, clock=self._clock) for key in wanted}

{xtr_cache-3.0.0 → xtr_cache-4.0.2}/src/xtr_cache/adapter/filesystem_adapter.py

@@ -47,6 +47,14 @@ _HEADER_BYTES: Final = 4096
 _PRIVATE_MODE: Final = 0o700
 """The default directory's mode: in the shared temporary directory, only its owner may enter."""
 
+_PRIVATE_FILE_MODE: Final = 0o600
+_PRIVATE_DIR_MODE: Final = 0o700
+"""A pool's own files and directories, reachable by their owner alone, the default."""
+
+_SHARED_FILE_MODE: Final = 0o666
+_SHARED_DIR_MODE: Final = 0o777
+"""The modes ``shared`` opts into, so processes run as other users can read the files."""
+
 
 @final
 class FilesystemAdapter(AbstractAdapter, PruneableInterface):
@@ -60,6 +68,15 @@ class FilesystemAdapter(AbstractAdapter, PruneableInterface):
     Nothing is created until the first value is written. An expired file is
     removed when it is read; :meth:`prune` removes the ones nobody reads.
 
+    Files are the owner's alone (``0o600``) in directories the owner alone may
+    enter (``0o700``), unless ``shared`` opens them to everyone (``0o666`` and
+    ``0o777``, as the umask allows) so processes run as other users can read
+    them. A shared directory is dangerous with the pickle marshaller: anyone
+    who can write a file into it chooses what this process unpickles, which is
+    code execution. Share a directory only with a marshaller that
+    authenticates what it reads, such as
+    :class:`~xtr_cache.marshaller.SodiumMarshaller`.
+
     Without a directory of its own, a pool keeps its files in the system's
     temporary directory, where every user may create one first. Values are
     unpickled when read, so there the directory is made for this user alone,
@@ -71,13 +88,16 @@ class FilesystemAdapter(AbstractAdapter, PruneableInterface):
     _marshaller: MarshallerInterface
     _private_root: Path | None
     _private_root_checked: bool
+    _file_mode: int
+    _dir_mode: int
 
-    def __init__(
+    def __init__(  # noqa: PLR0913 — every option past the directory is keyword-only.
         self,
         namespace: str = "",
         default_lifetime: float = 0.0,
         directory: str | os.PathLike[str] | None = None,
         *,
+        shared: bool = False,
         marshaller: MarshallerInterface | None = None,
         clock: ClockInterface | None = None,
     ) -> None:
@@ -90,6 +110,11 @@ class FilesystemAdapter(AbstractAdapter, PruneableInterface):
                 expiry; ``0`` for no limit.
             directory: Where the files go. ``None`` uses ``xtr-cache`` under
                 the system's temporary directory.
+            shared: Create files and directories readable by every user
+                (``0o666``/``0o777``, as the umask allows) rather than the
+                owner alone (``0o600``/``0o700``). Dangerous with pickle: a
+                shared directory lets anyone choose what is unpickled, which
+                is code execution. Pair it with an authenticating marshaller.
             marshaller: What turns values into bytes. Pickle when omitted.
             clock: What lifetimes are counted from. ``None`` reads the clock
                 in force.
@@ -108,6 +133,8 @@ class FilesystemAdapter(AbstractAdapter, PruneableInterface):
         self._private_root = base if directory is None else None
         self._private_root_checked = False
         self._marshaller = marshaller if marshaller is not None else DefaultMarshaller()
+        self._file_mode = _SHARED_FILE_MODE if shared else _PRIVATE_FILE_MODE
+        self._dir_mode = _SHARED_DIR_MODE if shared else _PRIVATE_DIR_MODE
 
     @property
     def directory(self) -> Path:
@@ -203,10 +230,10 @@ class FilesystemAdapter(AbstractAdapter, PruneableInterface):
             header = f"{expiry:.6f}\n{quote(id_, safe='')}\n".encode("ascii")
             temporary = path.parent / f"{_TEMPORARY_PREFIX}{secrets.token_hex(8)}"
             try:
-                path.parent.mkdir(parents=True, exist_ok=True)
-                # Readable by whoever the umask lets read it, so processes run as other users
-                # can share the directory.
-                with os.fdopen(os.open(temporary, _WRITE_FLAGS, 0o666), "wb") as file:
+                path.parent.mkdir(self._dir_mode, parents=True, exist_ok=True)
+                # The owner's alone by default; readable by whoever the umask lets read it
+                # when shared, so processes run as other users can share the directory.
+                with os.fdopen(os.open(temporary, _WRITE_FLAGS, self._file_mode), "wb") as file:
                     _ = file.write(header)
                     _ = file.write(data)
                 _ = temporary.replace(path)

{xtr_cache-3.0.0 → xtr_cache-4.0.2}/src/xtr_cache/adapter/redis_adapter.py

@@ -86,7 +86,7 @@ class RedisAdapter(AbstractAdapter):
     def __init__(
         self,
         redis: Redis,
-        namespace: str = "",
+        namespace: str,
         default_lifetime: float = 0.0,
         *,
         marshaller: MarshallerInterface | None = None,
@@ -96,8 +96,9 @@ class RedisAdapter(AbstractAdapter):
 
         Args:
             redis: An asyncio client.
-            namespace: Put in front of every key. Set one when the database
-                holds anything else.
+            namespace: Put in front of every key, and required: without one
+                :meth:`clear` unlinks every key in the database, not only this
+                pool's.
             default_lifetime: Seconds a value lives when its item sets no
                 expiry; ``0`` for no limit.
             marshaller: What turns values into bytes. Pickle when omitted.
@@ -105,8 +106,9 @@ class RedisAdapter(AbstractAdapter):
                 clock in force.
 
         Raises:
-            InvalidArgumentError: When the client decodes replies into text:
-                stored values are bytes, and would never read back.
+            InvalidArgumentError: When ``namespace`` is empty, or the client
+                decodes replies into text — stored values are bytes, and would
+                never read back.
         """
         # The client is typed for its blocking twin too; see _Client.
         client = cast("_Client", cast("object", redis))
@@ -115,6 +117,11 @@ class RedisAdapter(AbstractAdapter):
                 "A Redis cache pool needs a client returning bytes; "
                 "this one was created with decode_responses=True.",
             )
+        if not namespace:
+            raise InvalidArgumentError(
+                "A Redis cache pool needs a namespace: clearing it unlinks every "
+                "key under the namespace, and empties the whole database without one.",
+            )
 
         super().__init__(namespace, default_lifetime, clock=clock)
         self._redis = redis
@@ -126,7 +133,7 @@ class RedisAdapter(AbstractAdapter):
     def from_url(
         cls,
         dsn: str,
-        namespace: str = "",
+        namespace: str,
         default_lifetime: float = 0.0,
         *,
         marshaller: MarshallerInterface | None = None,

{xtr_cache-3.0.0 → xtr_cache-4.0.2}/src/xtr_cache/adapter/tag_aware_adapter.py

@@ -10,6 +10,7 @@ from typing import TYPE_CHECKING, Final, Self, final
 from typing_extensions import override
 from xtr_cache_contracts import Metadata, NamespacedPoolInterface
 
+from xtr_cache._internal_key import InternalKey
 from xtr_cache.cache_item import CacheItem
 from xtr_cache.pruneable_interface import PruneableInterface
 from xtr_cache.value_wrapper import ValueWrapper
@@ -29,11 +30,14 @@ if TYPE_CHECKING:
 __all__ = ["TagAwareAdapter"]
 
 TAGS_PREFIX: Final = "\x01tags\x01"
+"""What the key holding a tag's version starts with, so it never meets a user key."""
 
-#: How long a tag's version is kept. Given explicitly, so a tags pool's default
-#: lifetime never drops a version before the values that were saved with it.
 _TAG_VERSION_LIFETIME: Final = 100 * 365 * 86400
-"""What the key holding a tag's version starts with, so it never meets a user key."""
+"""How long a tag's version is kept.
+
+Given explicitly, so a tags pool's default lifetime never drops a version
+before the values that were saved with it.
+"""
 
 
 @final
@@ -99,7 +103,7 @@ class TagAwareAdapter(
     async def invalidate_tags(self, tags: Iterable[str], /) -> bool:
         ids: list[str] = []
         for tag in tags:
-            ids.append(TAGS_PREFIX + CacheItem.validate_key(tag))
+            ids.append(InternalKey(TAGS_PREFIX + CacheItem.validate_key(tag)))
             _ = self._known.pop(tag, None)
 
         return not ids or await self._tags.delete_items(ids)
@@ -200,7 +204,12 @@ class TagAwareAdapter(
         stored = inner.get()
         if not isinstance(stored, TaggedValue):
             return CacheItem(
-                key, stored, hit=True, metadata=inner.metadata, taggable=True, clock=self._clock
+                key,
+                stored,
+                hit=True,
+                metadata=inner.metadata.copy(),
+                taggable=True,
+                clock=self._clock,
             )
 
         if any(versions.get(tag) != version for tag, version in stored.versions.items()):
@@ -236,9 +245,10 @@ class TagAwareAdapter(
                 unknown.append(tag)
 
         if unknown:
-            items = await self._tags.get_items([TAGS_PREFIX + tag for tag in unknown])
+            keys = {tag: InternalKey(TAGS_PREFIX + tag) for tag in unknown}
+            items = await self._tags.get_items(keys.values())
             for tag in unknown:
-                item = items[TAGS_PREFIX + tag]
+                item = items[keys[tag]]
                 version = item.get() if item.is_hit() else None
                 versions[tag] = version if isinstance(version, str) else None
                 self._remember(tag, versions[tag], now)
@@ -267,7 +277,8 @@ class TagAwareAdapter(
             created = [tag for tag, found in current.items() if found is None]
 
             for tag in created:
-                version = CacheItem(TAGS_PREFIX + tag, versions[tag], clock=self._clock)
+                key = InternalKey(TAGS_PREFIX + tag)
+                version = CacheItem(key, versions[tag], clock=self._clock)
                 _ = await self._tags.save_deferred(version.expires_after(_TAG_VERSION_LIFETIME))
             # A version the tags pool did not keep must not be trusted here while others miss it.
             if created and await self._tags.commit():

{xtr_cache-3.0.0 → xtr_cache-4.0.2}/src/xtr_cache/bundle/cache_bundle.py

@@ -54,7 +54,7 @@ from xtr_cache.adapter.contracts_mixin import ContractsMixin
 from xtr_cache.adapter.redis_adapter import RedisAdapter
 from xtr_cache.adapter.tag_aware_adapter import TagAwareAdapter
 from xtr_cache.adapter.tag_aware_adapter_interface import TagAwareAdapterInterface
-from xtr_cache.cache_pool_clearer import CachePoolClearer
+from xtr_cache.cache_pool_clearer import CachePoolClearer, PoolCapabilities
 from xtr_cache.exception import InvalidArgumentError
 from xtr_cache.lock_registry import LockRegistry
 from xtr_cache.marshaller.default_marshaller import DefaultMarshaller
@@ -197,7 +197,26 @@ async def _lock_registry(
 
 def _cache_pool_clearer(config: CacheConfig, container: ContainerInterface) -> CachePoolClearer:
     """Name every pool for the commands, each built only when a command first needs it."""
-    return CachePoolClearer({name: _provider(container, name) for name in config.pool_configs()})
+    configs = config.pool_configs()
+    return CachePoolClearer(
+        {name: _provider(container, name) for name in configs},
+        capabilities={name: _capabilities(pool) for name, pool in configs.items()},
+    )
+
+
+def _capabilities(pool: PoolConfig) -> PoolCapabilities:
+    """Read what a pool can do from its configuration, so a command need not build it.
+
+    A tag-aware pool and a chain are always prunable (each wraps the pool
+    underneath), so is a single pool whose adapter keeps expired values.
+    """
+    entries = pool.adapters()
+    prunable = (
+        bool(pool.tags)
+        or len(entries) > 1
+        or any(AdapterFactory.serves_pruneable(entry) for entry in entries)
+    )
+    return PoolCapabilities(tag_aware=bool(pool.tags), prunable=prunable)
 
 
 def _provider(

{xtr_cache-3.0.0 → xtr_cache-4.0.2}/src/xtr_cache/bundle/cache_config.py

@@ -25,6 +25,30 @@ def _no_pools() -> dict[str, PoolEntry]:
     return {}
 
 
+def _refuse_tags_cycles(edges: Mapping[str, str]) -> None:
+    """Refuse a cycle in the pools' tags references, of any length, naming its pools.
+
+    Each pool keeping its tags in another points at one pool only, so the
+    references form a functional graph: a walk from any pool revisits a pool
+    exactly when it is caught in a cycle. A cycle would make building one of
+    its pools need itself, so it is refused before anything is built.
+
+    Raises:
+        InvalidArgumentError: When the tags references form a cycle.
+    """
+    for start in edges:
+        seen: list[str] = []
+        node = start
+        while node in edges:
+            if node in seen:
+                cycle = [*seen[seen.index(node) :], node]
+                raise InvalidArgumentError(
+                    f"The cache pools form a tags cycle: {' -> '.join(cycle)}.",
+                )
+            seen.append(node)
+            node = edges[node]
+
+
 @dataclass(frozen=True, slots=True)
 class CacheConfig:
     """Which cache pools exist, and what each keeps its values in.
@@ -82,6 +106,7 @@ class CacheConfig:
             InvalidArgumentError: When the configuration cannot be read.
         """
         _ = PoolConfig(adapter=self.app)
+        edges: dict[str, str] = {}
         for name, entry in self.pools.items():
             if not isinstance(name, str) or not name:  # pyright: ignore[reportUnnecessaryIsInstance] -- configs are written by hand; the annotation is not enforced
                 raise InvalidArgumentError(f"A cache pool needs a non-empty name, got {name!r}.")
@@ -96,6 +121,9 @@ class CacheConfig:
                     f'The "{name}" cache pool keeps its tags in "{entry.tags}", '
                     f"which is not another pool.",
                 )
+            elif isinstance(entry.tags, str):
+                edges[name] = entry.tags
+        _refuse_tags_cycles(edges)
 
     def pool_configs(self) -> dict[str, PoolConfig]:
         """Return every pool, ``app`` first, each with its adapters resolved to a tuple."""

{xtr_cache-3.0.0 → xtr_cache-4.0.2}/src/xtr_cache/cache_item.py

@@ -9,6 +9,7 @@ from typing_extensions import override
 from xtr_cache_contracts import RESERVED_CHARACTERS, InvalidArgumentError, ItemInterface, Metadata
 from xtr_clock import Clock
 
+from ._internal_key import InternalKey
 from .exception.logic_error import LogicError
 from .value_wrapper import ValueWrapper
 
@@ -115,8 +116,9 @@ class CacheItem(ItemInterface):
         """Return ``key`` when it is a valid key or tag.
 
         Raises:
-            InvalidArgumentError: When ``key`` is not a string, is empty, or
-                holds one of :data:`~xtr_cache_contracts.RESERVED_CHARACTERS`.
+            InvalidArgumentError: When ``key`` is not a string, is empty, holds
+                a non-printable character, or holds one of
+                :data:`~xtr_cache_contracts.RESERVED_CHARACTERS`.
         """
         if not isinstance(key, str):
             raise InvalidArgumentError(
@@ -124,6 +126,12 @@ class CacheItem(ItemInterface):
             )
         if not key:
             raise InvalidArgumentError("A cache key must not be empty.")
+        if isinstance(key, InternalKey):
+            return key
+        if not key.isprintable():
+            raise InvalidArgumentError(
+                f"A cache key must not contain non-printable characters, got {key!r}.",
+            )
         if any(character in RESERVED_CHARACTERS for character in key):
             raise InvalidArgumentError(
                 f'Cache key "{key}" contains one of the reserved characters '

{xtr_cache-3.0.0 → xtr_cache-4.0.2}/src/xtr_cache/cache_pool_clearer.py

@@ -3,20 +3,47 @@
 from __future__ import annotations
 
 from collections.abc import Callable
+from dataclasses import dataclass
 from typing import TYPE_CHECKING, TypeAlias, final
 
 from typing_extensions import override
-from xtr_cache_contracts import CacheItemPoolInterface, InvalidArgumentError
+from xtr_cache_contracts import (
+    CacheItemPoolInterface,
+    InvalidArgumentError,
+    TagAwareCacheInterface,
+)
+
+from xtr_cache.pruneable_interface import PruneableInterface
 
 if TYPE_CHECKING:
     from collections.abc import Awaitable, Mapping
 
-__all__ = ["CachePoolClearer", "PoolProvider"]
+__all__ = ["CachePoolClearer", "PoolCapabilities", "PoolProvider"]
 
 PoolProvider: TypeAlias = CacheItemPoolInterface | Callable[[], "Awaitable[CacheItemPoolInterface]"]
 """A pool, or what builds it when first asked for."""
 
 
+@final
+@dataclass(frozen=True, slots=True)
+class PoolCapabilities:
+    """What a pool can do, read from its configuration before it is built.
+
+    A command that acts on only some pools — pruning the ones that keep
+    expired values, invalidating tags in the tag-aware ones — asks these of
+    every pool and builds only the ones that answer yes, so naming a Redis
+    pool it would skip never reaches the server.
+
+    Attributes:
+        tag_aware: Whether items can be tagged and invalidated by tag.
+        prunable: Whether the backend keeps expired values, so pruning frees
+            them.
+    """
+
+    tag_aware: bool
+    prunable: bool
+
+
 @final
 class CachePoolClearer:
     """Knows every named pool, and clears them by name.
@@ -26,15 +53,27 @@ class CachePoolClearer:
     nothing until a command uses it.
     """
 
-    __slots__ = ("_built", "_pools")
+    __slots__ = ("_built", "_capabilities", "_pools")
 
     _pools: dict[str, PoolProvider]
     _built: dict[str, CacheItemPoolInterface]
-
-    def __init__(self, pools: Mapping[str, PoolProvider] | None = None) -> None:
-        """Know ``pools`` by name."""
+    _capabilities: dict[str, PoolCapabilities]
+
+    def __init__(
+        self,
+        pools: Mapping[str, PoolProvider] | None = None,
+        *,
+        capabilities: Mapping[str, PoolCapabilities] | None = None,
+    ) -> None:
+        """Know ``pools`` by name, with ``capabilities`` a command can read unbuilt.
+
+        A pool given built answers its own capabilities by its type; one given
+        as a function to build later needs an entry in ``capabilities``, so a
+        command can tell what it does without building it.
+        """
         self._pools = dict(pools or {})
         self._built = {}
+        self._capabilities = dict(capabilities or {})
 
     def has_pool(self, name: str) -> bool:
         """Tell whether a pool is known by ``name``."""
@@ -44,6 +83,20 @@ class CachePoolClearer:
         """Return every pool's name, sorted."""
         return tuple(sorted(self._pools))
 
+    def is_tag_aware(self, name: str) -> bool:
+        """Tell whether the pool ``name`` can be invalidated by tag, without building it."""
+        capabilities = self._capabilities.get(name)
+        if capabilities is not None:
+            return capabilities.tag_aware
+        return isinstance(self._pools.get(name), TagAwareCacheInterface)
+
+    def is_prunable(self, name: str) -> bool:
+        """Tell whether the pool known by ``name`` keeps expired values, without building it."""
+        capabilities = self._capabilities.get(name)
+        if capabilities is not None:
+            return capabilities.prunable
+        return isinstance(self._pools.get(name), PruneableInterface)
+
     async def get_pool(self, name: str) -> CacheItemPoolInterface:
         """Return the pool known by ``name``, building it the first time.
 

{xtr_cache-3.0.0 → xtr_cache-4.0.2}/src/xtr_cache/command/cache_pool_invalidate_tags_command.py

@@ -83,12 +83,14 @@ async def _invalidate(
     invalidated = 0
     errors = False
     for name in names:
-        cache = await clearer.get_pool(name)
-        if not isinstance(cache, TagAwareCacheInterface):
+        if not clearer.is_tag_aware(name):
             if named:
                 io.error(f'Cache pool "{escape(name)}" is not tag-aware.')
                 errors = True
             continue
+        cache = await clearer.get_pool(name)
+        if not isinstance(cache, TagAwareCacheInterface):
+            continue
         if not await cache.invalidate_tags(tags):
             io.error(f'Cache tags could not be invalidated in pool "{escape(name)}".')
             errors = True

{xtr_cache-3.0.0 → xtr_cache-4.0.2}/src/xtr_cache/command/cache_pool_prune_command.py

@@ -32,6 +32,8 @@ class CachePoolPruneCommand(PoolCommand):
 
         failed: list[str] = []
         for name in clearer.pool_names():
+            if not clearer.is_prunable(name):
+                continue
             cache = await clearer.get_pool(name)
             if not isinstance(cache, PruneableInterface):
                 continue

{xtr_cache-3.0.0 → xtr_cache-4.0.2}/src/xtr_cache/lock_registry.py

@@ -3,11 +3,11 @@
 from __future__ import annotations
 
 import asyncio
-import time
 import zlib
 from typing import TYPE_CHECKING, Final, TypeVar, cast, final
 
 from typing_extensions import override
+from xtr_clock import MonotonicClock
 from xtr_logging_contracts import LoggerAware
 
 from .exception import InvalidArgumentError
@@ -16,6 +16,7 @@ if TYPE_CHECKING:
     from collections.abc import Awaitable, Callable
 
     from xtr_cache_contracts import ItemInterface
+    from xtr_clock import ClockInterface
     from xtr_lock import LockFactory
 
 __all__ = ["LockRegistry"]
@@ -48,13 +49,14 @@ class LockRegistry(LoggerAware):
     so every process agrees on which lock guards it.
     """
 
-    __slots__ = ("_evicted", "_locks", "_prefix", "_slots", "_wait")
+    __slots__ = ("_clock", "_evicted", "_locks", "_prefix", "_slots", "_wait")
 
     _locks: LockFactory
     _slots: int
     _evicted: dict[int, float]
     _wait: float
     _prefix: str
+    _clock: ClockInterface
 
     def __init__(
         self,
@@ -63,6 +65,7 @@ class LockRegistry(LoggerAware):
         slots: int = DEFAULT_SLOTS,
         wait: float = DEFAULT_WAIT,
         prefix: str = "xtr-cache.",
+        clock: ClockInterface | None = None,
     ) -> None:
         """Take slots' locks from ``locks``.
 
@@ -71,6 +74,8 @@ class LockRegistry(LoggerAware):
             slots: How many values may be computed at once.
             wait: How long to wait for another caller's computation, in seconds.
             prefix: Put in front of each slot's number to name its lock.
+            clock: What the eviction window is timed against; a monotonic clock
+                when omitted, so a wall-clock jump never widens or shortens it.
 
         Raises:
             InvalidArgumentError: When ``slots`` or ``wait`` is not positive.
@@ -85,6 +90,7 @@ class LockRegistry(LoggerAware):
         self._evicted = {}
         self._wait = wait
         self._prefix = prefix
+        self._clock = clock if clock is not None else MonotonicClock()
 
     async def compute(
         self,
@@ -147,14 +153,14 @@ class LockRegistry(LoggerAware):
         until = self._evicted.get(slot)
         if until is None:
             return slot
-        if time.monotonic() < until:
+        if self._clock.now().timestamp() < until:
             return None
         del self._evicted[slot]
         return slot
 
     def _evict(self, slot: int) -> None:
         """Set ``slot`` aside for a while, its holder stuck, so later callers do not wait on it."""
-        self._evicted[slot] = time.monotonic() + self._wait
+        self._evicted[slot] = self._clock.now().timestamp() + self._wait
 
     @property
     def slots(self) -> int: