Module

utils.lru_cache

Thread-safe LRU cache with optional TTL and statistics.

Kida's standard LRU cache implementation. Use it for any in-memory caching with size limits and optional time-based expiry.

Design Goals:

  • Zero external dependencies (pure Python)
  • Generic type parameters for type safety
  • Full-featured: stats, TTL, enable/disable, get_or_set
  • Thread-safe with RLock for reentrant access

Example:

>>> from kida.utils.lru_cache import LRUCache
>>> cache: LRUCache[str, Template] = LRUCache(maxsize=400, ttl=300)
>>> cache.set("key", value)
>>> cache.get("key")
>>> template = cache.get_or_set("other", lambda: compile_template())
>>> cache.stats()

{'hits': 10, 'misses': 2, 'hit_rate': 0.83, ...}

1Class

Classes

LRUCache 18 ▼
Thread-safe LRU cache with optional TTL support. Uses OrderedDict + RLock for O(1) operations with…

Thread-safe LRU cache with optional TTL support.

Uses OrderedDict + RLock for O(1) operations with thread safety.

Eviction Strategy: True LRU - move_to_end() on every access, popitem(last=False) for eviction. This provides better hit rates than FIFO for workloads with temporal locality.

Complexity:

  • get: O(1) average
  • set: O(1) average
  • get_or_set: O(1) + factory cost on miss
  • clear: O(n)

Methods

enabled 0 bool ▼
Whether caching is enabled.
property
def enabled(self) -> bool
Returns
bool
maxsize 0 int ▼
Maximum cache size.
property
def maxsize(self) -> int
Returns
int
get 1 V | None ▼
Get value by key, returning None if not found or expired. Updates LRU order on…
def get(self, key: K) -> V | None

Get value by key, returning None if not found or expired.

Updates LRU order on hit. Counts as miss if disabled.

Parameters
Name Type Description
key —
Returns
V | None
get_or_set 2 V ▼
def get_or_set(self, key: K, factory: Callable[[], V]) -> V
Parameters
Name Type Description
key —
factory —
Returns
V
get_or_set 2 V ▼
def get_or_set(self, key: K, factory: Callable[[K], V]) -> V
Parameters
Name Type Description
key —
factory —
Returns
V
get_or_set 2 V ▼
Get value or compute and cache it. This is the preferred pattern for cache usa…
def get_or_set(self, key: K, factory: Callable[[], V] | Callable[[K], V]) -> V

Get value or compute and cache it.

This is the preferred pattern for cache usage - avoids the check-then-set race condition and reduces boilerplate.

Parameters
Name Type Description
key —

Cache key
factory —

Callable that returns the value to cache on miss
Returns
V Cached or newly computed value
set 2 ▼
Set value, evicting LRU entries if at capacity.
def set(self, key: K, value: V) -> None
Parameters
Name Type Description
key —
value —
delete 1 bool ▼
Delete a key from the cache.
def delete(self, key: K) -> bool
Parameters
Name Type Description
key —
Returns
bool True if key was present and deleted, False otherwise.
clear 0 ▼
Clear all entries and reset statistics.
def clear(self) -> None
enable 0 ▼
Enable caching.
def enable(self) -> None
disable 0 ▼
Disable caching (get returns None, set is no-op).
def disable(self) -> None
stats 0 dict[str, Any] ▼
Get cache statistics.
def stats(self) -> dict[str, Any]
Returns
dict[str, Any] Dictionary with: - hits: Number of cache hits - misses: Number of cache misses - hit_rate: Cache hit rate (0.0 to 1.0) - size: Current cache size - max_size: Maximum cache size - ttl: Time-to-live in seconds (None if disabled) - enabled: Whether caching is enabled - name: Cache name (if set)
reset_stats 0 ▼
Reset hit/miss statistics without clearing cache.
def reset_stats(self) -> None
keys 0 list[K] ▼
Return list of all keys (snapshot, may include expired).
def keys(self) -> list[K]
Returns
list[K]
Internal Methods 4 ▼
__init__ 2 ▼
Initialize LRU cache.
def __init__(self, maxsize: int = 128, ttl: float | None = None) -> None
Parameters
Name Type Description
maxsize —

Maximum entries (0 = unlimited, default 128)

Default:128
ttl —

Time-to-live in seconds (None = no expiry)

Default:None
__contains__ 1 bool ▼
Check if key exists and is not expired. Does NOT update LRU order or stats. Us…
def __contains__(self, key: K) -> bool

Check if key exists and is not expired.

Does NOT update LRU order or stats. Use for existence checks only.

Parameters
Name Type Description
key —
Returns
bool
__len__ 0 int ▼
Return number of entries (may include expired if TTL set).
def __len__(self) -> int
Returns
int
__repr__ 0 str ▼
def __repr__(self) -> str
Returns
str