# lru_cache URL: /kida/api/utils/lru_cache/ Section: utils Description: 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, ...} --- > For a complete page index, fetch /kida/llms.txt. Open LLM text (/kida/api/utils/lru_cache/index.txt) Share with AI Ask Claude (https://claude.ai/new?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Futils%2Flru_cache%2Findex.txt) Ask ChatGPT (https://chatgpt.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Futils%2Flru_cache%2Findex.txt) Ask Gemini (https://gemini.google.com/app?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Futils%2Flru_cache%2Findex.txt) Ask Copilot (https://copilot.microsoft.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Futils%2Flru_cache%2Findex.txt) 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, ...} 2Classes ## Classes `CacheStats` 8 ▼ Statistics returned by `stats`(). Statistics returned by`stats`(). #### Attributes Name Type Description `hits` `int` — `misses` `int` — `hit_rate` `float` — `size` `int` — `max_size` `int` — `ttl` `float | None` — `enabled` `bool` — `name` `str | None` — `LRUCache` 19 ▼ 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` 3 `V` ▼ `def get_or_set(self, key: K, factory: Callable[[], V], *, ttl: float | None = None) -> V` ##### Parameters Name Type Description `key` `—` `factory` `—` `ttl` `—` Default:`None` ##### Returns `V` `get_or_set` 4 `V` ▼ `def get_or_set(self, key: K, factory: Callable[[K], V], *, pass_key: bool, ttl: float | None = None) -> V` ##### Parameters Name Type Description `key` `—` `factory` `—` `pass_key` `—` `ttl` `—` Default:`None` ##### Returns `V` `get_or_set` 4 `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], *, pass_key: bool = False, ttl: float | None = None) -> 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 `pass_key` `—` If True, passes key to factory as argument Default:`False` `ttl` `—` Default:`None` ##### Returns `V` Cached or newly computed value `set` 3 ▼ Set value, evicting LRU entries if at capacity. `def set(self, key: K, value: V, *, ttl: float | None = None) -> None` ##### Parameters Name Type Description `key` `—` `value` `—` `ttl` `—` Default:`None` `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 `CacheStats` ▼ Get cache statistics. `def stats(self) -> CacheStats` ##### Returns `CacheStats` `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 5 ▼ `__init__` 3 ▼ Initialize LRU cache. `def __init__(self, maxsize: int = 128, ttl: float | None = None, *, name: str | 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` `name` `—` Optional name for debugging (shown in repr) Default:`None` `_entry_ttl` 1 `float | None` ▼ Return effective TTL for key (override or cache default). `def _entry_ttl(self, key: K) -> float | None` ##### Parameters Name Type Description `key` `—` ##### Returns `float | 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`