loom.core.cache.gateway

Functions

_is_raw_backend(cache)

Return True when the aiocache backend stores values without serialization.

Classes

CacheGateway(*[, alias])

Facade over aiocache with msgpack serialization for entity data.

class loom.core.cache.gateway.CacheGateway(*, alias='default')

Bases: object

Facade over aiocache with msgpack serialization for entity data.

Two distinct usage modes:

Data gateway — configured with MsgspecSerializer. Used by CachedRepository for entity and list storage. All values are msgpack-encoded on write and decoded on read.

Counter gateway — configured without a serializer (raw backend). Used by GenerationalDependencyResolver for generation counter storage. Values are stored as plain Python integers, enabling atomic native increment on both Redis and SimpleMemoryCache.

The gateway auto-detects which mode it is in at construction time and routes incr() accordingly — no manual configuration needed beyond choosing the right aiocache alias.

Parameters:

alias (str) – Registered aiocache alias to retrieve the backend from.

Example:

data_gateway    = CacheGateway(alias=config.aiocache_alias)
counter_gateway = CacheGateway(alias=config.effective_counter_alias)
resolver = GenerationalDependencyResolver(counter_gateway)

static configure(raw_config)

Apply a configuration mapping to the global aiocache registry.

Parameters:

raw_config (Mapping[str, Any]) – Configuration dict compatible with aiocache.caches.set_config.

Return type:

None

classmethod apply_config(config)

Configure aiocache from a CacheConfig.

Equivalent to configure() but also injects config.max_size into every aiocache.SimpleMemoryCache backend entry that does not already declare its own max_size. Entries for other backend types (Redis, Memcached, …) are forwarded unchanged.

Parameters:

config (CacheConfig) – Resolved cache configuration.

Return type:

None

Example:

cache_cfg = CacheConfig(
    aiocache_alias="cache",
    counter_alias="counters",
    max_size=1000,
    aiocache_config={
        "cache":    {"cache": "aiocache.SimpleMemoryCache", ...},
        "counters": {"cache": "aiocache.SimpleMemoryCache"},
    },
)
CacheGateway.apply_config(cache_cfg)

async get_value(key: str, *, type: type[T]) → T | None

async get_value(key: str, *, type: None = None) → Any

Retrieve a cached value, optionally converting it to the given type.

Parameters:

• key (str) – Cache key.

• type (type[T] | None) – Optional target type for msgspec.convert.

Returns:

The cached value (converted to type if given) or None on miss.

Return type:

T | Any | None

async multi_get_values(keys, *, type=None)

Retrieve multiple values in a single round-trip.

Parameters:

• keys (list[str]) – Cache keys to look up.

• type (type[T] | None) – Optional target type for msgspec.convert on each value.

Returns:

Values in the same order as keys, with None for misses.

Return type:

list[T | Any | None]

async exists(key)

Check whether a key exists in the cache.

Parameters:

key (str) – Cache key to check.

Returns:

True if the key is present.

Return type:

bool

async set_value(key, value, ttl=None)

Store a value under the given key.

Parameters:

• key (str) – Cache key.

• value (Any) – Value to store.

• ttl (int | None) – Time-to-live in seconds. None means no expiration.

Return type:

None

async multi_set_values(pairs, ttl=None)

Store multiple key-value pairs in a single round-trip.

Parameters:

• pairs (list[tuple[str, Any]]) – List of (key, value) tuples.

• ttl (int | None) – Time-to-live in seconds applied to all entries.

Return type:

None

async incr(key, delta=1)

Increment a numeric value at the given key.

Routes to the optimal strategy based on the backend configuration detected at construction time:

• Raw backend (no serializer): delegates to the backend’s native increment method when available. On Redis this is an atomic INCR / INCRBY command; on SimpleMemoryCache it is asyncio-safe. Falls back to GET+SET for backends that do not expose increment.

• Serialized backend (MsgspecSerializer): uses a non-atomic GET+SET. Correct for single-process deployments; the asyncio event loop does not preempt between the two awaits within a single coroutine execution.

Parameters:

• key (str) – Cache key holding an integer value.

• delta (int) – Amount to increment by. Defaults to 1.

Returns:

The new value after incrementing.

Return type:

int

async delete(key)

Delete a single key from the cache.

Parameters:

key (str) – Cache key to remove.

Returns:

Number of keys actually deleted (0 or 1).

Return type:

int

async delete_many(keys)

Delete multiple keys from the cache.

Parameters:

keys (list[str]) – Cache keys to remove.

Returns:

Number of keys actually deleted.

Return type:

int

async clear()

Remove all entries from the cache backend.

Return type:

None

async close()

Release the underlying cache connection resources.

Return type:

None