# bytecode_cache URL: /api/bytecode_cache/ Section: api -------------------------------------------------------------------------------- bytecode_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 Reference ᗢ 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 bytecode_cache Template Bytecode Cache. Persists compiled template code objects to disk for near-instant cold-start loading. Uses marshal for code object serialization. Cache Invalidation: Uses source hash in filename. When source changes, hash changes, and old cache entry becomes orphan (cleaned up lazily). Thread-Safety: File writes use atomic rename pattern to prevent corruption. Multiple processes can safely share the cache directory. Example: >>> from pathlib import Path >>> from kida.bytecode_cache import BytecodeCache, hash_source >>> >>> cache = BytecodeCache(Path(".kida-cache")) >>> >>> # Check cache >>> code = cache.get("base.html", source_hash) >>> if code is None: ... code = compile_template(source) ... cache.set("base.html", source_hash, code) >>> >>> # Cache stats >>> stats = cache.stats() >>> print(f"Cached: {stats['file_count']} templates") 1Class1Function Classes BytecodeCache 7 ▼ Persist compiled template bytecode to disk. Uses marshal for code object serialization (Python std… Persist compiled template bytecode to disk. Uses marshal for code object serialization (Python stdlib). Thread-Safety: File writes use atomic rename pattern to prevent corruption. Multiple processes can safely share the cache directory. Cache Invalidation: Uses source hash in filename. When source changes, hash changes, and old cache entry becomes orphan (cleaned up lazily). Methods get 2 CodeType | None ▼ Load cached bytecode if available. def get(self, name: str, source_hash: str) -> CodeType | None Parameters Name Type Description name — Template name source_hash — Hash of template source (for invalidation) Returns CodeType | None Compiled code object, or None if not cached set 3 ▼ Cache compiled bytecode. def set(self, name: str, source_hash: str, code: CodeType) -> None Parameters Name Type Description name — Template name source_hash — Hash of template source code — Compiled code object clear 1 int ▼ Remove cached bytecode. def clear(self, current_version_only: bool = False) -> int Parameters Name Type Description current_version_only — If True, only clear current Python version's cache Default: False Returns int Number of files removed cleanup 1 int ▼ Remove orphaned cache files older than max_age_days. Orphaned files are cache … def cleanup(self, max_age_days: int = 30) -> int Remove orphaned cache files older than max_age_days. Orphaned files are cache entries that are no longer referenced by active templates (e.g., after source changes or template deletion). Parameters Name Type Description max_age_days — Maximum age in days before removal (default: 30) Default: 30 Returns int Number of files removed stats 0 dict[str, int] ▼ Get cache statistics. def stats(self) -> dict[str, int] Returns dict[str, int] Dict with file_count, total_bytes Internal Methods 2 ▼ __init__ 2 ▼ Initialize bytecode cache. def __init__(self, directory: Path, pattern: str = '__kida_{version}_{name}_{hash}.pyc') Parameters Name Type Description directory — Cache directory (created if missing) pattern — Filename pattern with {version}, {name}, {hash} placeholders Default: '__kida_{version}_{name}_{hash}.pyc' _make_path 2 Path ▼ Generate cache file path. Includes Python version in filename to prevent cross… def _make_path(self, name: str, source_hash: str) -> Path Generate cache file path. Includes Python version in filename to prevent cross-version bytecode incompatibility (marshal format is version-specific). Parameters Name Type Description name — source_hash — Returns Path Functions hash_source 1 str ▼ Generate hash of template source for cache key. def hash_source(source: str) -> str Parameters Name Type Description source str Returns str ← Previous _types Next → kida 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: 1016 - Reading Time: 5 minutes