Skip to content

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

PoolProvider = CacheItemPoolInterface | Callable[[], 'Awaitable[CacheItemPoolInterface]']

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; 0 keeps it until it is deleted.

  • clock (ClockInterface | None, default: None ) –

    What lifetimes are counted from. None reads the clock in force.

Raises:

  • InvalidArgumentError –

    When namespace is not a valid key once its separators are removed, or has an empty sub-namespace.

NS_SEPARATOR class-attribute

NS_SEPARATOR: str = ':'

What separates a namespace from what follows it in an identifier.

namespace property

namespace: str

What every identifier starts with, separator included; empty for none.

default_lifetime property

default_lifetime: float

Seconds a value lives when its item sets no expiry; 0 for no limit.

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

validate(connection: str) -> None

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

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.

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.

get_item async

get_item(key: str) -> CacheItem

Return the item for key, a hit or a miss.

get_items async

get_items(keys: Iterable[str]) -> Mapping[str, CacheItem]

Return an item for each of keys, in the order asked.

reset async

reset() -> None

End a unit of work: store what was saved as deferred, and forget per-unit state.

What a long-running process calls between messages or requests, so deferred items do not wait for a commit that nothing will call.

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; 0 for 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; 0 for no cap.

  • max_items (int, default: 0 ) –

    How many values to keep, dropping the least recently used beyond; 0 for 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. None reads the clock in force.

Raises:

values

values() -> dict[str, object]

Return every live value by identifier, as stored; for tests.

prune async

prune() -> bool

Drop every value whose expiry has passed.

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; 0 leaves it to that pool's own default.

  • clock (ClockInterface | None, default: None ) –

    What lifetimes are counted from. None reads the clock in force.

Raises:

adapters property

adapters: tuple[AdapterInterface, ...]

The pools, in the order they are read.

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 (beta infinite) 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.

get_item abstractmethod async

get_item(key: str) -> CacheItem

Return the item for key, a hit or a miss.

set_lock_registry

set_lock_registry(registry: LockRegistry | None) -> None

Compute missing values under registry's locks; None for this process alone.

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; 0 for no limit.

  • directory (str | PathLike[str] | None, default: None ) –

    Where the files go. None uses xtr-cache under 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. None reads the clock in force.

Raises:

directory property

directory: Path

The directory this pool's files go in.

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:clear unlinks 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; 0 for 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. None reads the clock in force.

Raises:

  • InvalidArgumentError –

    When namespace is empty, or the client decodes replies into text — stored values are bytes, and would never read back.

MISSING_CLIENT class-attribute

MISSING_CLIENT: str = 'A Redis cache pool needs the redis client; install "xtr-cache[redis]".'

What a Redis DSN is refused with when the client library is not installed.

owns_connection property

owns_connection: bool

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:

create_connection staticmethod

create_connection(dsn: str) -> Redis

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 redis extra is not installed. The message names the scheme only, never credentials.

close async

close() -> None

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_pool when 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; 0 reads it every time.

  • clock (ClockInterface | None, default: None ) –

    What lifetimes are counted from. None reads 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

TaggedValue(value: object, versions: Mapping[str, str])

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_after counts from. None reads the clock in force.

expiry property

expiry: float | None

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

pending_tags: tuple[str, ...]

The tags added since the item was read, in the order they were added.

taggable property

taggable: bool

Whether the pool this item belongs to can store tags.

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

validate_key(key: object) -> str

Return key when it is a valid key or tag.

Raises:

  • InvalidArgumentError –

    When key is not a string, is empty, holds a non-printable character, or holds one of :data:~xtr_cache_contracts.RESERVED_CHARACTERS.

tag

tag(tags: str | Iterable[str]) -> Self

Add one tag, or several.

Raises:

record_computation

record_computation(ctime: int) -> Self

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

carry_metadata(metadata: Metadata) -> Self

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

pack(default_expiry: float | None = None) -> object

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; None when 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.

has_pool

has_pool(name: str) -> bool

Tell whether a pool is known by name.

pool_names

pool_names() -> tuple[str, ...]

Return every pool's name, sorted.

is_tag_aware

is_tag_aware(name: str) -> bool

Tell whether the pool name can be invalidated by tag, without building it.

is_prunable

is_prunable(name: str) -> bool

Tell whether the pool known by name keeps expired values, without building it.

get_pool async

get_pool(name: str) -> CacheItemPoolInterface

Return the pool known by name, building it the first time.

Raises:

clear_pool async

clear_pool(name: str, prefix: str = '') -> bool

Clear the pool known by name, or its keys starting with prefix.

Raises:

clear async

clear(prefix: str = '') -> bool

Clear every pool, or their keys starting with prefix.

LogicError

LogicError(reason: str)

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

MarshallingError(reason: str)

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:

slots property

slots: int

How many values may be computed at once.

wait property

wait: float

How long a caller waits for another's computation, in seconds.

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

DeflateMarshaller(marshaller: MarshallerInterface)

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

unmarshall(value: bytes) -> object

Inflate value and decode it; bytes never compressed are decoded as they are.

Raises:

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.

marshall

marshall(values: Mapping[str, object]) -> tuple[dict[str, bytes], list[str]]

Encode values.

Returns:

  • dict[str, bytes] –

    The encoded values by key, and the keys of the values that could

  • list[str] –

    not be encoded.

unmarshall

unmarshall(value: bytes) -> object

Decode one stored value.

Raises:

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_key makes 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 sodium extra is not installed.

is_supported staticmethod

is_supported() -> bool

Tell whether PyNaCl is installed.

generate_key staticmethod

generate_key() -> str

Return a new random key, base64-encoded, for configuration or an environment variable.

Raises:

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.

prune async

prune() -> bool

Remove every expired value.

Returns:

  • bool –

    False when the backend failed for any of them; True

  • bool –

    otherwise.

ValueWrapper dataclass

ValueWrapper(value: object, metadata: Metadata)

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.