Backend

mongo_ops.cache.backend

Summary

Cache backend abstraction.

Classes

CacheBackend

Bases: ABC

Abstract interface for cache backends.

Implementations store byte-encoded values keyed by string, track usage statistics, and manage their own lifecycle. The in-memory and Redis backends both implement this contract.

Functions

clear_pattern abstractmethod async

clear_pattern(pattern: str) -> None

Remove all keys matching a glob pattern.

Parameters:

Name	Type	Description	Default
pattern	str	Glob-style pattern; a trailing * matches prefixes.	required

delete abstractmethod async

delete(key: str) -> None

Remove a key from the cache.

Parameters:

Name	Type	Description	Default
key	str	The cache key.	required

exists abstractmethod async

exists(key: str) -> bool

Check whether a key is present.

Parameters:

Name	Type	Description	Default
key	str	The cache key.	required

Returns:

Name	Type	Description
bool	bool	True if the key exists, False otherwise.

get abstractmethod async

get(key: str) -> bytes | None

Fetch a value from the cache.

Parameters:

Name	Type	Description	Default
key	str	The cache key.	required

Returns:

Type	Description
bytes | None	Optional[bytes]: The cached bytes, or None on a miss.

get_stats abstractmethod async

get_stats() -> CacheStats

Return a snapshot of cache statistics.

Returns:

Name	Type	Description
CacheStats	CacheStats	A copy of the current stats counters.

initialize abstractmethod async

initialize() -> None

Start background resources owned by the backend.

Should be called once during application startup, after the repositories are connected.

set abstractmethod async

set(key: str, value: bytes, ttl: int | None = None) -> None

Store a value in the cache.

Parameters:

Name	Type	Description	Default
key	str	The cache key.	required
value	bytes	The byte-encoded value to store.	required
ttl	Optional[int]	Time-to-live in seconds. When None, the backend default applies.	None

shutdown abstractmethod async

shutdown() -> None

Stop and release background resources.

Should be called once during application shutdown.

CacheStats dataclass

CacheStats(
    hits: int = 0,
    misses: int = 0,
    sets: int = 0,
    deletes: int = 0,
    current_size: int = 0,
    max_size: int = 0,
)

Snapshot of cache usage and activity counters.

Attributes:

Name	Type	Description
hits	int	Number of get() calls that found a value.
misses	int	Number of get() calls that returned None.
sets	int	Number of values written to the cache.
deletes	int	Number of keys removed.
current_size	int	Number of entries currently held.
max_size	int	Maximum number of entries the cache allows (0 = unbounded).

CircularReferenceError

CircularReferenceError(
    collection: str, doc_id: ObjectId, path: list[str]
)

Bases: ValueError

Raised when population detects a cycle in the reference graph.

Attributes:

Name	Type	Description
collection	str	Collection where the cycle was detected.
doc_id	ObjectId	Document ID where the cycle was detected.
path	list[str]	Ordered labels describing the visited reference path.

Initialize the error with cycle metadata.

Parameters:

Name	Type	Description	Default
collection	str	Collection where the cycle was detected.	required
doc_id	ObjectId	Document ID where the cycle was detected.	required
path	list[str]	Ordered labels describing the visited reference path.	required

Functions