xtr_cache ¶
Cache pools in memory, in files, in Redis, chained or tag-aware.
Every pool implements the xtr-cache-contracts interfaces, which this
package re-exports rather than redefines — xtr_cache.CacheInterface is
xtr_cache_contracts.CacheInterface — so code written against the contract
receives these pools unchanged.
cache = FilesystemAdapter("app")
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)
Every call that reaches a backend is awaited. A backend failing never raises:
reads miss, writes return False, and the pool logs why.
PoolProvider ¶
A pool, or what builds it when first asked for.
AbstractAdapter ¶
AbstractAdapter(namespace: str = '', default_lifetime: float = 0.0, *, clock: ClockInterface | None = None)
Bases: DeferredItemsMixin, ContractsMixin, AdapterInterface, NamespacedPoolInterface, ABC
A pool whose backend stores values by identifier, with a lifetime each.
A subclass implements five operations on identifiers — fetch, has, clear,
delete, save — and gets every pool method on top: keys validated and
namespaced, deferred saves committed in batches by lifetime, sub-namespaces,
fetch-or-compute, and failures logged instead of raised. A backend that
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.
Keep values under namespace, living default_lifetime unless an item says not.
Parameters:
-
namespace(str, default:'') –Put in front of every key;
:separates sub-namespaces. Empty for none. -
default_lifetime(float, default:0.0) –Seconds a value lives when its item sets no expiry;
0keeps it until it is deleted. -
clock(ClockInterface | None, default:None) –What lifetimes are counted from.
Nonereads the clock in force.
Raises:
-
InvalidArgumentError–When
namespaceis not a valid key once its separators are removed, or has an empty sub-namespace.
AdapterFactory ¶
Turns what a configuration names into an adapter.
| Given | Adapter |
|---|---|
"array" |
:class:ArrayAdapter |
"null" |
:class:NullAdapter |
"filesystem" |
:class:FilesystemAdapter in directory, or the temporary one |
"filesystem:///var/cache/app" |
:class:FilesystemAdapter in that directory |
"redis://…", "rediss://…", "unix://…" |
:class:RedisAdapter, its own client |
"valkey://…", "valkeys://…" |
the same, read as redis / rediss |
| an asyncio Redis client | :class:RedisAdapter on that client |
create_adapter
staticmethod
¶
create_adapter(connection: object, namespace: str = '', default_lifetime: float = 0.0, *, marshaller: MarshallerInterface | None = None, directory: str | PathLike[str] | None = None, clock: ClockInterface | None = None) -> AdapterInterface
Build the adapter connection names.
Parameters:
-
connection(object) –A DSN, a keyword, or an asyncio Redis client.
-
namespace(str, default:'') –The pool's namespace; an in-memory pool has no use for one.
-
default_lifetime(float, default:0.0) –Seconds a value lives when its item sets no expiry.
-
marshaller(MarshallerInterface | None, default:None) –What turns values into bytes, for a backend storing bytes.
-
directory(str | PathLike[str] | None, default:None) –Where
"filesystem"keeps its files. -
clock(ClockInterface | None, default:None) –What lifetimes are counted from.
Raises:
-
InvalidArgumentError–When no adapter serves
connection. The message names its scheme or type only, never credentials.
validate
staticmethod
¶
Refuse a DSN no adapter serves, without building one or connecting to anything.
Raises:
-
InvalidArgumentError–When no adapter serves
connection, or it needs an extra that is not installed. The message names its scheme only, never credentials.
serves_pruneable
staticmethod
¶
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.
AdapterInterface ¶
Bases: CacheItemPoolInterface, CacheInterface, Protocol
A pool handing out :class:~xtr_cache.cache_item.CacheItem, with fetch-or-compute on top.
Every adapter of this library is one, which is what lets them wrap and chain each other: an item one hands out, another stores.
ArrayAdapter ¶
ArrayAdapter(default_lifetime: float = 0.0, *, store_serialized: bool = True, max_lifetime: float = 0.0, max_items: int = 0, marshaller: MarshallerInterface | None = None, clock: ClockInterface | None = None)
Bases: 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 copy: changing it does not change what is cached, exactly as with any other backend. Turn that off to store the objects themselves, faster but shared.
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.
Keep values in memory.
Parameters:
-
default_lifetime(float, default:0.0) –Seconds a value lives when its item sets no expiry;
0for no limit. -
store_serialized(bool, default:True) –Store a serialized copy rather than the object.
-
max_lifetime(float, default:0.0) –Seconds no value outlives, whatever its item says;
0for no cap. -
max_items(int, default:0) –How many values to keep, dropping the least recently used beyond;
0for no limit. -
marshaller(MarshallerInterface | None, default:None) –What serializes values when
store_serialized. Pickle when omitted. -
clock(ClockInterface | None, default:None) –What lifetimes are counted from.
Nonereads the clock in force.
Raises:
-
InvalidArgumentError–When
max_lifetimeormax_itemsis negative.
ChainAdapter ¶
ChainAdapter(adapters: Sequence[AdapterInterface], default_lifetime: float = 0.0, *, clock: ClockInterface | None = None)
Bases: ContractsMixin, AdapterInterface, NamespacedPoolInterface, PruneableInterface
Reads from the first pool that has a value, and fills the faster ones with it.
Typically memory in front of Redis: a hit in memory costs nothing, a miss
there asks Redis, and a value found in Redis is copied into memory for
the next read — with what is left of its lifetime, when it was stored
with one, or default_lifetime otherwise. Writes, deletes and clears
go to every pool.
Chain adapters, the fastest first.
Parameters:
-
adapters(Sequence[AdapterInterface]) –The pools, in the order they are read.
-
default_lifetime(float, default:0.0) –Seconds a value copied into a faster pool lives, when it was stored without an expiry;
0leaves it to that pool's own default. -
clock(ClockInterface | None, default:None) –What lifetimes are counted from.
Nonereads the clock in force.
Raises:
-
InvalidArgumentError–When
adaptersis empty.
ContractsMixin ¶
Bases: CacheMixin, LoggerAware, ABC
Fetch-or-compute on a pool of :class:~xtr_cache.cache_item.CacheItem.
Built on :class:~xtr_cache_contracts.CacheMixin's template, adjusting how
a missing value is computed:
- It is saved with how long it took, which — with its expiry — is what makes early recomputation possible on a later read.
- Concurrent misses on one key in this process share one computation, and its result: each of them gets the very object computed, so change it only after copying it. What is cached stays apart. If the computation fails or is cancelled, each of the others computes for itself.
- With a :class:
~xtr_cache.lock_registry.LockRegistry, misses in every process sharing its locks share one computation too. - A callback reading its own key — directly or through what it calls — computes without saving, instead of waiting on itself.
- A forced recomputation (
betainfinite) runs its own callback, never joining one already in progress. - A value whose tags were invalidated while it was computed is returned but not saved: it was computed from what the invalidation retired. This sees the invalidations of this process only.
Computations are keyed by :meth:_scope and the key, so pools on one
backend under different namespaces never wait on each other, and by the
running event loop, so two loops never wait on each other's futures.
FilesystemAdapter ¶
FilesystemAdapter(namespace: str = '', default_lifetime: float = 0.0, directory: str | PathLike[str] | None = None, *, shared: bool = False, marshaller: MarshallerInterface | None = None, clock: ClockInterface | None = None)
Bases: AbstractAdapter, PruneableInterface
Keeps each value in a file of its own, under a directory per namespace.
A file holds the value's expiry, its identifier and its bytes. Writing goes to a temporary file first and replaces the old one in one step, so a reader never sees half a value, and processes sharing the directory share the cache. File work runs on a worker thread, off the event loop.
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, and one belonging to anybody else is refused: every read misses and every write fails, and the pool logs why.
Keep values in files under directory.
Parameters:
-
namespace(str, default:'') –Put in front of every key, and names the directory's subdirectory the files go in.
-
default_lifetime(float, default:0.0) –Seconds a value lives when its item sets no expiry;
0for no limit. -
directory(str | PathLike[str] | None, default:None) –Where the files go.
Noneusesxtr-cacheunder the system's temporary directory. -
shared(bool, default:False) –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(MarshallerInterface | None, default:None) –What turns values into bytes. Pickle when omitted.
-
clock(ClockInterface | None, default:None) –What lifetimes are counted from.
Nonereads the clock in force.
Raises:
-
InvalidArgumentError–When
namespaceis not valid, or is only dots.
NullAdapter ¶
Bases: CacheMixin, AdapterInterface, NamespacedPoolInterface
Stores nothing: every read misses, every write succeeds.
For switching caching off without changing the code that caches:
:meth:get computes every time — every read being a miss — and
everything else does nothing.
RedisAdapter ¶
RedisAdapter(redis: Redis, namespace: str, default_lifetime: float = 0.0, *, marshaller: MarshallerInterface | None = None, clock: ClockInterface | None = None)
Bases: AbstractAdapter
Keeps values on a Redis or Valkey server, which expires them on its own.
Each value is a string key: the pool's namespace, then the key. Saves are pipelined, reads fetch many keys in one round trip, and clearing scans the namespace's keys and unlinks them in batches — without a namespace, that is every key in the database.
One server, standalone. Not a cluster, not Sentinel.
Keep values on the server redis talks to; the client stays the caller's to close.
Parameters:
-
redis(Redis) –An asyncio client.
-
namespace(str) –Put in front of every key, and required: without one :meth:
clearunlinks every key in the database, not only this pool's. -
default_lifetime(float, default:0.0) –Seconds a value lives when its item sets no expiry;
0for no limit. -
marshaller(MarshallerInterface | None, default:None) –What turns values into bytes. Pickle when omitted.
-
clock(ClockInterface | None, default:None) –What item lifetimes are counted from.
Nonereads the clock in force.
Raises:
-
InvalidArgumentError–When
namespaceis empty, or the client decodes replies into text — stored values are bytes, and would never read back.
MISSING_CLIENT
class-attribute
¶
What a Redis DSN is refused with when the client library is not installed.
owns_connection
property
¶
Whether :meth:close closes the client, because :meth:from_url opened it.
from_url
classmethod
¶
from_url(dsn: str, namespace: str, default_lifetime: float = 0.0, *, marshaller: MarshallerInterface | None = None, clock: ClockInterface | None = None) -> RedisAdapter
Connect to the server dsn names, on first use, and own the connection.
Close the adapter with :meth:close when done.
Raises:
-
InvalidArgumentError–When the scheme is not a Redis one, or the
redisextra is not installed.
create_connection
staticmethod
¶
Return an asyncio client for dsn that connects on first use.
valkey:// and valkeys:// read as redis:// and rediss://.
Raises:
-
InvalidArgumentError–When the scheme is not a Redis one, or the
redisextra is not installed. The message names the scheme only, never credentials.
close
async
¶
Close the connection, when :meth:from_url opened it; otherwise do nothing.
TagAwareAdapter ¶
TagAwareAdapter(items_pool: AdapterInterface, tags_pool: AdapterInterface | None = None, known_tag_versions_ttl: float = 0.15, *, clock: ClockInterface | None = None)
Bases: DeferredItemsMixin, ContractsMixin, TagAwareAdapterInterface, NamespacedPoolInterface, PruneableInterface
Lets items be tagged, and every item carrying a tag be invalidated at once.
Each tag has a version, kept in the tags pool. An item is saved with the versions its tags have at that moment, and is a hit only while every one of them still has that version. Invalidating a tag deletes its version: every item saved before no longer matches, whatever its key, and the next save gives the tag a new one. Nothing is scanned or listed, so invalidating costs the same however many items carry the tag.
Versions are remembered for known_tag_versions_ttl seconds, so a burst
of reads asks the tags pool once. Invalidation elsewhere reaches this
process within that delay. Items saved as deferred take their versions
when committed, so an invalidation meanwhile does not apply to them.
Within this process, an invalidation holds once it returned: a version
read while it ran is used by that read but never remembered, and a value
computed through :meth:get while one of its tags was invalidated is
returned but not saved.
Tag the items of items_pool, keeping versions in tags_pool.
Parameters:
-
items_pool(AdapterInterface) –Where values are stored.
-
tags_pool(AdapterInterface | None, default:None) –Where tag versions are stored;
items_poolwhen omitted. A faster or shared pool here makes invalidation cheaper or wider. -
known_tag_versions_ttl(float, default:0.15) –Seconds a version read from the tags pool is trusted before it is read again;
0reads it every time. -
clock(ClockInterface | None, default:None) –What lifetimes are counted from.
Nonereads the clock in force.
TagAwareAdapterInterface ¶
Bases: AdapterInterface, TagAwareCacheInterface, Protocol
An adapter whose items can be tagged, and invalidated by any of their tags.
TaggedValue
dataclass
¶
A value as a tag-aware pool stores it, with each tag's version at the time.
Part of the stored format: its module and name must not change, or values already stored would no longer be read back.
Attributes:
-
value(object) –The cached value.
-
versions(Mapping[str, str]) –Each tag's version when the value was saved.
CacheItem ¶
CacheItem(key: str, value: object = None, *, hit: bool = False, metadata: Metadata | None = None, taggable: bool = False, clock: ClockInterface | None = None)
Bases: ItemInterface
A cache entry: its key, its value when there is one, and how long it should live.
Pools build items; code that caches receives them from get_item or in
a callback, changes them, and hands them back to be saved. Every pool of
this library stores any :class:CacheItem, so an item read from one pool
can be saved into another — which is how a chain fills its faster levels.
Beyond the item contract, a few members are for pools and adapters:
:attr:expiry, :attr:pending_tags, :meth:record_computation,
:meth:carry_metadata, :meth:pack and :meth:from_stored.
Build the item for key.
Parameters:
-
key(str) –The key, already validated by the pool.
-
value(object, default:None) –The value found, when
hit. -
hit(bool, default:False) –Whether the pool had a value for the key.
-
metadata(Metadata | None, default:None) –What the pool stored alongside the value.
-
taggable(bool, default:False) –Whether the pool it belongs to can store tags.
-
clock(ClockInterface | None, default:None) –What :meth:
expires_aftercounts from.Nonereads the clock in force.
expiry
property
¶
When the item expires, as a Unix timestamp; None for the pool's default lifetime.
Set by :meth:expires_at or :meth:expires_after. An item read from a
pool starts at None whatever it was stored with: the stored expiry
is in :attr:metadata, and saving the item again starts its lifetime
over.
pending_tags
property
¶
The tags added since the item was read, in the order they were added.
from_stored
classmethod
¶
from_stored(key: str, stored: object, *, taggable: bool = False, clock: ClockInterface | None = None) -> CacheItem
Build the hit for key from what a backend returned, unwrapping its metadata.
validate_key
staticmethod
¶
Return key when it is a valid key or tag.
Raises:
-
InvalidArgumentError–When
keyis not a string, is empty, holds a non-printable character, or holds one of :data:~xtr_cache_contracts.RESERVED_CHARACTERS.
tag ¶
Add one tag, or several.
Raises:
-
LogicError–When the item comes from a pool that cannot store tags.
-
InvalidArgumentError–When a tag is not a valid key.
record_computation ¶
Remember that the value took ctime milliseconds, so it can be refreshed early.
Stored with the value on the next save, together with when it expires — the two facts early recomputation needs.
carry_metadata ¶
Store metadata's computation time and tags with the value on the next save.
What a chain calls on the item it copies into a faster level, so the copy keeps what the original was stored with.
pack ¶
Return what a backend should store: the value, wrapped with its metadata when it has any.
The expiry stored is the one that applies: the item's own, or
default_expiry — the pool's default lifetime from now — when it set
none. Storing it is what lets a chain copy the value into a faster pool
for exactly the life it has left, and early recomputation know when the
value runs out.
Parameters:
-
default_expiry(float | None, default:None) –When the value expires if the item set no expiry, as a Unix timestamp;
Nonewhen it then never expires.
CachePoolClearer ¶
CachePoolClearer(pools: Mapping[str, PoolProvider] | None = None, *, capabilities: Mapping[str, PoolCapabilities] | None = None)
Knows every named pool, and clears them by name.
What the cache:pool:* commands work through. A pool may be given
built, or as an async function building it, so naming a pool costs
nothing until a command uses it.
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.
is_tag_aware ¶
Tell whether the pool name can be invalidated by tag, without building it.
is_prunable ¶
Tell whether the pool known by name keeps expired values, without building it.
get_pool
async
¶
Return the pool known by name, building it the first time.
Raises:
-
InvalidArgumentError–When no pool is known by
name.
clear_pool
async
¶
Clear the pool known by name, or its keys starting with prefix.
Raises:
-
InvalidArgumentError–When no pool is known by
name.
LogicError ¶
Bases: CacheError
An operation was asked of an object that cannot perform it.
Tagging an item that comes from a pool which cannot store tags, say. A mistake in the calling code, never a backend failing.
Attributes:
-
reason(str) –What was asked, and why it cannot be done.
Record what was asked, and why it cannot be done.
MarshallingError ¶
Bases: CacheError
A stored value could not be turned back into what was cached.
Raised by a marshaller's unmarshall for bytes that are corrupt, were
written by something else, or fail their integrity check. A pool reading
such a value logs it and reports a miss, so the caller computes the value
again rather than failing.
Attributes:
-
reason(str) –Why the value could not be read.
Record why the value could not be read.
LockRegistry ¶
LockRegistry(locks: LockFactory, *, slots: int = DEFAULT_SLOTS, wait: float = DEFAULT_WAIT, prefix: str = 'xtr-cache.', clock: ClockInterface | None = None)
Bases: LoggerAware
Protects a backend from a stampede: one computation per key, a bounded number at once.
Keys are spread over a fixed number of slots, each a lock. The caller that
takes a key's slot computes and saves the value; every other caller missing
the same key waits for the slot to be released and reads what was saved.
So among every process sharing the lock store — every process on a machine
with file locks, every machine with Redis — one computes each value, and
no more than slots compute at once.
A caller that waited longer than wait stops waiting and computes the
value itself: a stuck holder must not stall every reader of the key. The
slot is then set aside, in this process, for another wait: its keys
are computed without locking meanwhile rather than wait on it in turn,
and it is tried again after. A key keeps its slot whatever is set aside,
so every process agrees on which lock guards it.
A computation reading another key of the slot it holds — keys share slots — computes that key at once, without locking: it would otherwise wait on itself.
Take slots' locks from locks.
Parameters:
-
locks(LockFactory) –Where the locks come from; its store decides who shares them.
-
slots(int, default:DEFAULT_SLOTS) –How many values may be computed at once.
-
wait(float, default:DEFAULT_WAIT) –How long to wait for another caller's computation, in seconds.
-
prefix(str, default:'xtr-cache.') –Put in front of each slot's number to name its lock.
-
clock(ClockInterface | None, default:None) –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
slotsorwaitis not positive.
compute
async
¶
compute(key: str, compute: Callable[[], Awaitable[T]], read: Callable[[], Awaitable[ItemInterface]], *, force: bool = False) -> T
Return the value for key, computed here or by whoever held its slot.
Parameters:
-
key(str) –The key whose value is missing.
-
compute(Callable[[], Awaitable[T]]) –Computes the value and saves it, holding the slot.
-
read(Callable[[], Awaitable[ItemInterface]]) –Reads the key again, once another holder has released it.
-
force(bool, default:False) –Compute even when another holder saved a value meanwhile.
Returns:
-
T–The value computed here, or the one read after waiting.
DefaultMarshaller ¶
Bases: MarshallerInterface
Encodes values with :mod:pickle, the one format every Python object can take.
A cache holds values of any type and reads them back without being told which, so the format has to carry the type itself: a dataclass comes back a dataclass, not a dictionary.
Unpickling runs code named by the bytes. That is safe as long as only
this application can write to the backend. When anything else can — a
Redis server shared with other applications — wrap this marshaller in a
:class:~xtr_cache.marshaller.sodium_marshaller.SodiumMarshaller, which
refuses bytes not encrypted with its key before they reach pickle.
DeflateMarshaller ¶
Bases: MarshallerInterface
Compresses the bytes another marshaller produces, trading CPU for backend memory.
Reading bytes that are not compressed hands them to the inner marshaller as they are, so a pool can start compressing without being cleared first.
Compress what marshaller encodes.
unmarshall ¶
Inflate value and decode it; bytes never compressed are decoded as they are.
Raises:
-
MarshallingError–If
valueis compressed but corrupt.
MarshallerInterface ¶
Bases: Protocol
Encodes values for a backend that stores bytes, and decodes what it returns.
Encoding is batched and never raises: a value that cannot be encoded is reported by key, and the pool logs it and saves the rest. Decoding one value raises when the bytes cannot be read, and the pool treats that value as a miss. Stored bytes outlive a deployment, so an implementation must keep reading what an earlier version of itself wrote.
SodiumMarshaller ¶
SodiumMarshaller(decryption_keys: Sequence[bytes | str], marshaller: MarshallerInterface | None = None)
Bases: MarshallerInterface
Encrypts stored values with libsodium's authenticated secret-key encryption.
What it writes can be neither read nor forged without a key: a Redis server shared with other applications sees only ciphertext, and bytes anyone else wrote fail authentication before they reach the inner marshaller — so pickle never unpickles them. Such a value reads as a miss, and the pool computes it again.
Keys rotate: the first encrypts, and every one of them decrypts. To rotate, put the new key first and keep the old one until what it encrypted has expired.
Needs the sodium extra: xtr-cache[sodium].
Encrypt with the first of decryption_keys, decrypt with any of them.
Parameters:
-
decryption_keys(Sequence[bytes | str]) –32-byte keys, raw or base64-encoded, the one to encrypt with first. :meth:
generate_keymakes one. -
marshaller(MarshallerInterface | None, default:None) –What encodes the values before they are encrypted. Pickle when omitted.
Raises:
-
InvalidArgumentError–When no key is given, a key is not 32 bytes, or the
sodiumextra is not installed.
generate_key
staticmethod
¶
Return a new random key, base64-encoded, for configuration or an environment variable.
Raises:
-
InvalidArgumentError–When the
sodiumextra is not installed.
PruneableInterface ¶
Bases: Protocol
A pool whose backend does not expire values on its own.
Files stay on disk after their value expires: reading one again treats it as a miss and removes it, but a key nobody reads keeps its file. Pruning removes every expired value at once; run it from a scheduled job.
ValueWrapper
dataclass
¶
What a pool stores when a value carries metadata: the value, and the metadata.
Values stored without metadata are stored as they are, so this wrapper costs nothing to a pool that never records any. It is part of the stored format: its module and name must not change, or values already stored would no longer be read back.
Attributes:
-
value(object) –The cached value.
-
metadata(Metadata) –Its expiry, how long it took to compute, its tags.