cache#

Lightweight LFU cache with an optional size cap.

Notes

  • Only keys with len(key) <= max_number_of_nodes are cached.

  • On cache miss, get() returns None (even if a cached value could be None). If you need to distinguish, wrap your values or add a sentinel in the caller.

This is intentionally minimal; O(n) eviction via a linear scan is acceptable for small caches.

Classes

Cache(max_number_of_nodes[, cache_size])

Least-frequently-used (LFU) cache with an optional capacity.

HashableSized(*args, **kwargs)

Protocol for keys that are both hashable and have a length.
class Cache(max_number_of_nodes, cache_size=None)#

Bases: Generic[K, V]

Least-frequently-used (LFU) cache with an optional capacity.

Parameters:

  • max_number_of_nodes (int) – Only cache keys with len(key) <= max_number_of_nodes.

  • cache_size (int | None) – Maximum number of entries to keep. If None, the cache grows without limit.

cache_size#

The capacity limit or None.

max_number_of_nodes#

Maximum allowed len(key) to be cached.

Notes

  • Eviction policy is LFU using a simple usage counter. Tie-breaking is arbitrary.

  • Updating an existing key bumps its usage counter by 1 (preserves your original behavior).

get(key)#

Return the cached value for key and increment its usage, or None if missing.

Parameters:

key (K)

Return type:

V | None

set(key, value)#

Insert or update key with value, enforcing LFU eviction if at capacity.

Keys with len(key) > max_number_of_nodes are ignored (not cached).

Parameters:

  • key (K)

  • value (V)

Return type:

None

clear()#

Remove all entries.

Return type:

None