orionis.cache.CacheRepository

THE ORIONIS API

Build with clarity.

Explore the building blocks of an async-first Python framework. Every module, class, and method — connected, searchable, and ready to build with.

Explore modules View classes

class documentation

class CacheRepository(ICacheRepository): (source)

Constructor: CacheRepository(backend, prefix)

View In Hierarchy

Async cache repository backed by a configurable storage backend.

Wraps a low-level backend with optional key-prefix support and exposes a higher-level API (get, set, remember, lock, …).

Method	`__init__`	Initialise the repository with a backend and an optional key prefix.
Method	`_k`	Return the prefixed form of key.
Async Method	`add`	Store value under key only when the key does not already exist.
Async Method	`clear`	Remove all entries from the cache store.
Async Method	`decrement`	Decrement the integer stored at key by amount.
Async Method	`delete`	Remove key from the cache store.
Async Method	`get`	Return the cached value for key, or `None` when absent.
Async Method	`getMany`	Return a mapping of key → value for all requested keys.
Async Method	`has`	Return `True` if key exists and has not expired.
Async Method	`increment`	Increment the integer stored at key by amount.
Method	`lock`	Return an async context manager that acquires a distributed lock.
Async Method	`pull`	Return the cached value for key and immediately remove it.
Async Method	`remember`	Return the cached value for key, computing it on a cache miss.
Async Method	`rememberForever`	Cache the value for key indefinitely, resolving on a miss.
Async Method	`replace`	Replace a live entry without resurrecting a deleted key.
Async Method	`set`	Store value under key with an optional time-to-live.
Async Method	`setMany`	Store multiple key/value pairs with an optional shared TTL.
Class Variable	`__slots__`	Undocumented
Instance Variable	`_backend`	Undocumented
Instance Variable	`_prefix`	Undocumented

def __init__(self, backend: Any, prefix: str = ''): (source) ¶

Initialise the repository with a backend and an optional key prefix.

Parameters
backend:`Any`	Storage backend implementing the low-level cache protocol.
prefix:`str, optional`	String prepended to every key, separated by `:`.

Returns
`None`	Complete the documented operation without returning a value.

def _k(self, key: str) -> str: (source) ¶

Return the prefixed form of key.

Parameters
key:`str`	Raw cache key.

Returns
`str`	Prefixed key, or the original key when no prefix is configured.

async def add(self, key: str, value: Any, ttl: float | None = None) -> bool: (source) ¶

overrides orionis.cache.contracts.ICacheRepository.add

Store value under key only when the key does not already exist.

Parameters
key:`str`	Cache key.
value:`Any`	Value to store.
ttl:`float \| None, optional`	Optional time-to-live in seconds.

Returns
`bool`	`True` on success, `False` when the key already exists.

async def clear(self) -> bool: (source) ¶

overrides orionis.cache.contracts.ICacheRepository.clear

Remove all entries from the cache store.

Returns
`bool`	`True` on success.

async def decrement(self, key: str, amount: int = 1) -> int: (source) ¶

overrides orionis.cache.contracts.ICacheRepository.decrement

Decrement the integer stored at key by amount.

Parameters
key:`str`	Cache key.
amount:`int, optional`	Positive integer to subtract. Defaults to `1`.

Returns
`int`	New value after the decrement.

async def delete(self, key: str) -> bool: (source) ¶

overrides orionis.cache.contracts.ICacheRepository.delete

Remove key from the cache store.

Parameters
key:`str`	Cache key.

Returns
`bool`	`True` if the key existed and was removed, `False` otherwise.

async def get(self, key: str) -> Any: (source) ¶

overrides orionis.cache.contracts.ICacheRepository.get

Return the cached value for key, or None when absent.

Parameters
key:`str`	Cache key.

Returns
`Any`	Cached value, or `None` when the key does not exist.

async def getMany(self, keys: list[str]) -> dict[str, Any]: (source) ¶

overrides orionis.cache.contracts.ICacheRepository.getMany

Return a mapping of key → value for all requested keys.

Parameters
keys:`list[str]`	Cache keys to fetch.

Returns
`dict[str, Any]`	Mapping that preserves the original (un-prefixed) key names.

async def has(self, key: str) -> bool: (source) ¶

overrides orionis.cache.contracts.ICacheRepository.has

Return True if key exists and has not expired.

Parameters
key:`str`	Cache key.

Returns
`bool`	`True` when the key is present and still valid.

async def increment(self, key: str, amount: int = 1) -> int: (source) ¶

overrides orionis.cache.contracts.ICacheRepository.increment

Increment the integer stored at key by amount.

Parameters
key:`str`	Cache key.
amount:`int, optional`	Positive integer to add. Defaults to `1`.

Returns
`int`	New value after the increment.

def lock(self, key: str, timeout: float | None = None) -> CacheLock: (source) ¶

Return an async context manager that acquires a distributed lock.

Parameters
key:`str`	Resource key to lock.
timeout:`float \| None, optional`	Maximum lock duration in seconds. `None` means no timeout.

Returns
`CacheLock`	Async context manager for the requested lock.

async def pull(self, key: str) -> Any: (source) ¶

overrides orionis.cache.contracts.ICacheRepository.pull

Return the cached value for key and immediately remove it.

Parameters
key:`str`	Cache key.

Returns
`Any`	Cached value, or `None` when the key is absent.

async def remember(self, key: str, ttl: float | None, resolver: Callable) -> Any: (source) ¶

overrides orionis.cache.contracts.ICacheRepository.remember

Return the cached value for key, computing it on a cache miss.

If the key is absent, call resolver (sync or async), persist the result for ttl seconds, and return it.

Parameters
key:`str`	Cache key.
ttl:`float \| None`	TTL applied when storing the resolved value. `None` means no expiry.
resolver:`Callable`	Zero-argument callable that produces the value. May be async.

Returns
`Any`	Cached value, or the freshly computed value on a miss.

async def rememberForever(self, key: str, resolver: Callable) -> Any: (source) ¶

overrides orionis.cache.contracts.ICacheRepository.rememberForever

Cache the value for key indefinitely, resolving on a miss.

Parameters
key:`str`	Cache key.
resolver:`Callable`	Zero-argument callable that produces the value. May be async.

Returns
`Any`	Cached value, or the freshly computed value on a miss.

async def replace(self, key: str, value: Any, ttl: float | None = None) -> bool: (source) ¶

overrides orionis.cache.contracts.ICacheRepository.replace

Replace a live entry without resurrecting a deleted key.

Parameters
key:`str`	Existing cache key.
value:`Any`	Replacement value.
ttl:`float \| None`	New lifetime in seconds, or None for no expiry.

Returns
`bool`	True when the backend atomically accepted the replacement.

Raises
`CacheStoreException`	If the backend has no atomic replacement primitive.

async def set(self, key: str, value: Any, ttl: float | None = None) -> bool: (source) ¶

overrides orionis.cache.contracts.ICacheRepository.set

Store value under key with an optional time-to-live.

Parameters
key:`str`	Cache key.
value:`Any`	Value to store.
ttl:`float \| None, optional`	Time-to-live in seconds. `None` means no expiry.

Returns
`bool`	`True` on success.

async def setMany(self, values: dict[str, Any], ttl: float | None = None) -> bool: (source) ¶

overrides orionis.cache.contracts.ICacheRepository.setMany

Store multiple key/value pairs with an optional shared TTL.

Parameters
values:`dict[str, Any]`	Mapping of key → value to store.
ttl:`float \| None, optional`	Shared time-to-live in seconds. `None` means no expiry.

Returns
`bool`	`True` on success.

__slots__: tuple[str, ...] = (source) ¶

overrides orionis.cache.contracts.ICacheRepository.__slots__

Undocumented

_backend = (source) ¶

Undocumented

_prefix = (source) ¶

Undocumented