`Cache`: Basic, Extensible In-Memory Caching#

class my.caches.Cache.Cache(*, data: dict[Key, Value] = {}, maxsize: Annotated[int, Gt(gt=0)] = 4096, bucket_size: Annotated[int, Gt(gt=0)] = 256)#

Simple LRU cache with automatic pruning when size limits are exceeded.

Maintains insertion order with most recently accessed items at the end. When maxsize is reached, removes items in buckets from the front (oldest first).

Examples

Fill a small cache, refresh one key, and watch the oldest bucket get pruned:

>>> from my import Cache
>>> cache = Cache[str, int](maxsize=4, bucket_size=2)
>>> for i, key in enumerate('abcd'):
...     cache[key] = i
>>> _ = cache['a']  # Refresh 'a', moving it to the back of the LRU order
>>> cache['e'] = 4  # At maxsize: prunes one bucket ('b' and 'c') first
>>> cache.keys()
['d', 'a', 'e']

Cache.items() → list[tuple[Key, Value]]#: Return this cache’s content as a list of key-value pairs.

Cache.keys() → list[Key]#: Return this cache’s keys as a list.

Cache.values() → list[Value]#: Return this cache’s values as a list.

Cache.prune(n: int) → None#

Remove the n oldest items from the cache (front of the insertion order).

Snapshots the keys before mutating: a live dict.keys() view raises if another thread inserts or evicts mid-iteration, and a bare del raises if a key was already evicted by a concurrent prune. Iterating a list snapshot and using pop(..., None) makes pruning safe under concurrent access without a lock, since individual dict operations are atomic under the GIL.

Parameters:: n – The number of items to remove.

Examples

Drop the two oldest entries:

>>> from my import Cache
>>> cache = Cache[str, int]()
>>> for i, key in enumerate('abc'):
...     cache[key] = i
>>> cache.prune(2)
>>> cache.keys()
['c']

Cache: Basic, Extensible In-Memory Caching#

`Cache`: Basic, Extensible In-Memory Caching#