`NestedCache`: Simple, Recursive In-Memory Caching#

class my.caches.NestedCache.NestedCache(*, signature: tuple[type, ...], children: dict[Hashable, NestedCache] = {}, data: dict[Any, Value] = {}, size: int = 0, max_size: Annotated[int, Gt(gt=0)] = 4096, bucket_size: Annotated[int, Gt(gt=0)] = 256)#

Multi-level hierarchical cache with automatic pruning.

Supports arbitrary nesting depth determined by the signature tuple length. Each level maintains LRU ordering. Pruning is distributed proportionally across child caches based on their sizes.

Examples

Store and retrieve values under two-level key paths:

>>> from my import NestedCache
>>> cache = NestedCache(signature=(str, int))
>>> cache[('user', 1)] = 'robb'
>>> cache.set(('user', 2), 'ada')
1
>>> cache[('user', 1)]
'robb'
>>> len(cache)
2
>>> cache.delete(('user', 2))
1

property NestedCache.depth: int#: The number of key levels in this cache (i.e. the length of its signature).

NestedCache.set(keys: list | tuple, value: Value) → int#

Set a value at the specified key path.

Parameters:

keys – Path through nested levels (length must match depth).
value – Value to store.

Returns:

Number of new items added (0 if key existed, 1 if new).

Raises:

ValueError – If keys length doesn’t match cache depth.

NestedCache.delete(keys: list | tuple) → int#

Delete a value at the specified key path.

Parameters:: keys – Path through nested levels (length must match depth).
Returns:: Number of items deleted (0 if not found, 1 if deleted).

NestedCache.items() → Iterator[tuple[Keys, Value]]#: Iterator over all key-value pairs in the cache.

NestedCache.keys() → Iterator#: Iterator over all keys in the cache.

NestedCache.values() → Iterator#: Iterator over all values in the cache.

NestedCache.prune(n: int) → int#

Remove approximately n items from the cache.

For nested caches, distributes pruning proportionally across children based on their relative sizes.

Parameters:: n – Target number of items to remove.
Returns:: Actual number of items removed.

NestedCache: Simple, Recursive In-Memory Caching#

`NestedCache`: Simple, Recursive In-Memory Caching#