API Reference

class cache.async_cache.AsyncCache(maxsize=128, default_ttl=None, batch_window_ms=5, max_batch_size=100)

Bases: object

async get(key, loader=None, batch_loader=None, ttl=None)

Get from cache, loader on miss, with thundering herd protection for concurrent misses on same key. Uses _pending_lock to avoid race conditions when multiple async tasks (e.g., HTTP requests) miss simultaneously. Only one loader executes; others await the future result. Batch mode for multi-key. LRU ops protected by RLock in lru.LRU (prevents eviction races in parallel re-runs/hits near maxsize).

set(key, value, ttl=<object object>)

Set a value in the cache. LRU __setitem__ is protected by RLock internally.

delete(key)

Delete a key from the cache. LRU pop is protected by RLock internally.

clear()

Clear the cache and reset metrics. LRU clear is protected by RLock internally.

get_metrics()

Get cache metrics (hits, misses, size, hit_rate).

async warmup(keys_with_loaders)

Warmup: serial gets (each locks internally for hit/miss).

class cache.async_lru.AsyncLRU(maxsize=128, skip_args=0)

Bases: object

Parameters:

skip_args (int)

clear_cache()

Clears the LRU cache.

This method empties the cache, removing all stored entries and effectively resetting the cache.

Returns:

None

class cache.async_ttl.AsyncTTL(time_to_live=60, maxsize=1024, skip_args=0)

Bases: object

Parameters:

skip_args (int)

clear_cache()

Clears the TTL cache.

This method empties the cache, removing all stored entries and effectively resetting the cache.

Returns:

None

class cache.key.KEY(args, kwargs)

Bases: object

Immutable, hash/eq-stable key for cache (args + kwargs). Fixes prior bugs: - __eq__ was hash-only (violated contract: a==b but hashes differ possible; collisions). - Hash unstable (dict.items() order pre-3.7, str(vars) arbitrary, kwargs.pop mutated caller!). - Now: frozen tuples, recursive _to_hashable (sorted dicts, stable obj repr), no mutation. Guarantees hash(a)==hash(b) iff a==b; stable across runs/Python versions. Used via make_key in decorators/AsyncCache.

cache.key.make_key(func, args, kwargs, skip_args=0)

Reusable key: func name + sliced args + cleaned kwargs. Handles skip_args (e.g., ‘self’); stable for complex types.