mongoose.core.cache

class mongoose.core.cache.Cache(*args, **kwargs)

Bases: Generic[K, V]

Sharded LRU cache with optional TTL implemented as a singleton per class.

The cache partitions keys into a fixed number of shards. Each shard maintains its own OrderedDict and lock so operations for different shards can proceed concurrently without contending on a single global lock. Each shard enforces its own capacity (approximately max_size / num_shards), so the global max_size is a soft bound but should be close when keys distribute evenly.

This design provides better concurrency for high-contention workloads while preserving LRU semantics within each shard.

Return type:

Any

__contains__(key)

True if key exists and is not expired.

Return type:

bool

__init__(max_size=1024, ttl_seconds=None, num_shards=1)

Initialize the sharded cache.

Parameters:

• max_size (int) – Global maximum number of entries (positive int).

• ttl_seconds (float | None) – Optional TTL in seconds for entries. If None, no time expiry.

• num_shards (int) – Number of independent shards to partition the keyspace.

__len__()

Return the total number of non-expired items across all shards.

Return type:

int

clear()

Clear all shards.

get(key)

Retrieve a key from its shard and mark it as recently used.

Returns None if missing or expired.

Return type:

V | None

get_stats()

Return current stats snapshot: hits, misses, evictions.

Return type:

Dict[str, int]

items()

Yield (key, value) pairs across shards (LRU within each shard).

Return type:

Iterator[tuple[K, V]]

reset_stats()

Zero all statistics.

set(key, value)

Insert or update a key in its shard and enforce shard-level capacity.

class mongoose.core.cache.SeverityCache(*args, **kwargs)

Bases: Cache[str, int]

Specialization of Cache for community_id -> severity mappings.

Provides convenience methods set_severity and get_severity that validate input types and keep the simple, explicit API used by the rest of the codebase.

Return type:

Any

get_severity(community_id)

Retrieve the cached severity for a community_id or None if missing.

Parameters:

community_id (str) – String identifier for the community.

Returns:

The severity integer if present, otherwise None.

Raises:

TypeError – If community_id is not a str.

Return type:

int | None

set_severity(community_id, severity)

Store severity for a community_id. Always keep the highest severity value if the key already exists.

This method performs the comparison and update under the shard lock to avoid extra cache hits and to ensure correctness under concurrent updates.

Parameters:

• community_id (str) – String identifier for the community.

• severity (int) – Integer severity value.

Raises:

TypeError – If arguments are of incorrect types.

class mongoose.core.cache.SingletonMeta

Bases: type

Thread-safe metaclass implementing a per-class singleton.

Each class that uses this metaclass will only ever have a single instance created. The first construction’s args/kwargs are used to initialize the singleton; later constructions return the same instance and ignore new args.

mongoose.core.cache.reset_singletons()

Clear the internal singleton instance registry.

This is primarily intended for use in unit tests so different tests can instantiate singletons with different constructor parameters and get fresh instances. Use with care in production code as clearing singletons while other threads hold references can be unsafe.