# lru_cache URL: /api/utils/lru_cache/ Section: utils -------------------------------------------------------------------------------- lru_cache - Kida window.BENGAL_THEME_DEFAULTS = { appearance: 'light', palette: 'brown-bengal' }; window.Bengal = window.Bengal || {}; window.Bengal.enhanceBaseUrl = '/kida/assets/js/enhancements'; window.Bengal.watchDom = true; window.Bengal.debug = false; window.Bengal.enhanceUrls = { 'toc': '/kida/assets/js/enhancements/toc.632a9783.js', 'docs-nav': '/kida/assets/js/enhancements/docs-nav.57e4b129.js', 'tabs': '/kida/assets/js/enhancements/tabs.aac9e817.js', 'lightbox': '/kida/assets/js/enhancements/lightbox.1ca22aa1.js', 'interactive': '/kida/assets/js/enhancements/interactive.fc077855.js', 'mobile-nav': '/kida/assets/js/enhancements/mobile-nav.d991657f.js', 'action-bar': '/kida/assets/js/enhancements/action-bar.d62417f4.js', 'copy-link': '/kida/assets/js/enhancements/copy-link.7d9a5c29.js', 'data-table': '/kida/assets/js/enhancements/data-table.1f5bc1eb.js', 'lazy-loaders': '/kida/assets/js/enhancements/lazy-loaders.a5c38245.js', 'holo': '/kida/assets/js/enhancements/holo.ee13c841.js', 'link-previews': '/kida/assets/js/enhancements/link-previews.8d906535.js' }; (function () { try { var defaults = window.BENGAL_THEME_DEFAULTS || { appearance: 'system', palette: '' }; var defaultAppearance = defaults.appearance; if (defaultAppearance === 'system') { defaultAppearance = (window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) ? 'dark' : 'light'; } var storedTheme = localStorage.getItem('bengal-theme'); var storedPalette = localStorage.getItem('bengal-palette'); var theme = storedTheme ? (storedTheme === 'system' ? defaultAppearance : storedTheme) : defaultAppearance; var palette = storedPalette ?? defaults.palette; document.documentElement.setAttribute('data-theme', theme); if (palette) { document.documentElement.setAttribute('data-palette', palette); } } catch (e) { document.documentElement.setAttribute('data-theme', 'light'); } })(); { "prerender": [ { "where": { "and": [ { "href_matches": "/docs/*" }, { "not": { "selector_matches": "[data-external], [target=_blank], .external" } } ] }, "eagerness": "conservative" } ], "prefetch": [ { "where": { "and": [ { "href_matches": "/*" }, { "not": { "selector_matches": "[data-external], [target=_blank], .external" } } ] }, "eagerness": "conservative" } ] } Skip to main content Magnifying Glass ESC Recent Clear Magnifying Glass No results for "" Start typing to search... ↑↓ Navigate ↵ Open ESC Close Powered by Lunr )彡 DocumentationInfoAboutArrow ClockwiseGet StartedCodeSyntaxTerminalUsageNoteTutorialsStarburstExtendingBookmarkReferenceTroubleshootingReleasesDevGitHubKida API Reference Magnifying Glass Search ⌘K Palette Appearance Chevron Down Mode Monitor System Sun Light Moon Dark Palette Snow Lynx Brown Bengal Silver Bengal Charcoal Bengal Blue Bengal List )彡 Magnifying Glass Search X Close Documentation Caret Down Info About Arrow Clockwise Get Started Code Syntax Terminal Usage Note Tutorials Starburst Extending Bookmark Reference Troubleshooting Releases Dev Caret Down GitHub Kida API Reference Palette Appearance Chevron Down Mode Monitor System Sun Light Moon Dark Palette Snow Lynx Brown Bengal Silver Bengal Charcoal Bengal Blue Bengal Kida API Reference Caret Right Analysis analyzer cache config dependencies landmarks metadata purity roles Caret Right Compiler Caret Right Statements basic control_flow functions special_blocks template_structure variables _protocols coalescing core expressions utils Caret Right Environment core exceptions filters loaders protocols registry tests Caret Right Parser Caret Right Blocks control_flow core functions special_blocks template_structure variables _protocols core errors expressions statements tokens Caret Right Utils html lru_cache workers _types bytecode_cache kida lexer nodes template tstring Kida API ReferenceUtils ᗢ Caret Down Link Copy URL External Open LLM text Copy Copy LLM text Share with AI Ask Claude Ask ChatGPT Ask Gemini Ask Copilot 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 ← Previous html Next → utils List © 2026 Kida built in ᓚᘏᗢ { "linkPreviews": { "enabled": true, "hoverDelay": 200, "hideDelay": 150, "showSection": true, "showReadingTime": true, "showWordCount": true, "showDate": true, "showTags": true, "maxTags": 3, "includeSelectors": [".prose"], "excludeSelectors": ["nav", ".toc", ".breadcrumb", ".pagination", ".card", "[class*='-card']", ".tab-nav", "[class*='-widget']", ".child-items", ".content-tiles"], "allowedHosts": [], "allowedSchemes": ["https"], "hostFailureThreshold": 3 } } window.BENGAL_LAZY_ASSETS = { tabulator: '/kida/assets/js/tabulator.min.js', dataTable: '/kida/assets/js/data-table.js', mermaidToolbar: '/kida/assets/js/mermaid-toolbar.9de5abba.js', mermaidTheme: '/kida/assets/js/mermaid-theme.344822c5.js', graphMinimap: '/kida/assets/js/graph-minimap.ff04e939.js', graphContextual: '/kida/assets/js/graph-contextual.355458ba.js' }; window.BENGAL_ICONS = { close: '/kida/assets/icons/close.911d4fe1.svg', enlarge: '/kida/assets/icons/enlarge.652035e5.svg', copy: '/kida/assets/icons/copy.3d56e945.svg', 'download-svg': '/kida/assets/icons/download.04f07e1b.svg', 'download-png': '/kida/assets/icons/image.c34dfd40.svg', 'zoom-in': '/kida/assets/icons/zoom-in.237b4a83.svg', 'zoom-out': '/kida/assets/icons/zoom-out.38857c77.svg', reset: '/kida/assets/icons/reset.d26dba29.svg' }; Arrow Up -------------------------------------------------------------------------------- Metadata: - Word Count: 1207 - Reading Time: 6 minutes