# template

URL: /api/template/
Section: api

--------------------------------------------------------------------------------

template - 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 template Kida Template — compiled template object ready for rendering. The Template class wraps a compiled code object and provides the render() API. Templates are immutable and thread-safe for concurrent rendering. Architecture: ``` Template ├── _env_ref: WeakRef[Environment] # Prevents circular refs ├── _code: code object # Compiled Python bytecode ├── _render_func: callable # Extracted render() function └── _name, _filename # For error messages ``` StringBuilder Pattern: Generated code uses buf.append() + ''.join(buf): python def render(ctx, _blocks=None): buf = [] _append = buf.append _append("Hello, ") _append(_e(_s(ctx["name"]))) return ''.join(buf) This is O(n) vs O(n²) for string concatenation. Memory Safety: Uses weakref.ref(env) to break potential cycles: Template → (weak) → Environment → cache → Template Thread-Safety: Templates are immutable after construction render() creates only local state (buf list) Multiple threads can call render() concurrently Complexity: render(): O(n) where n = output size _escape(): O(n) single-pass via str.translate() 4Classes Classes LoopContext 13 ▼ Loop iteration metadata accessible as `loop` inside `{% for %}` blocks. Provides index tracking, b… Loop iteration metadata accessible as loop inside {% for %} blocks. Provides index tracking, boundary detection, and utility methods for common iteration patterns. All properties are computed on-access. Properties: index: 1-based iteration count (1, 2, 3, ...) index0: 0-based iteration count (0, 1, 2, ...) first: True on the first iteration last: True on the final iteration length: Total number of items in the sequence revindex: Reverse 1-based index (counts down to 1) revindex0: Reverse 0-based index (counts down to 0) previtem: Previous item in sequence (None on first) nextitem: Next item in sequence (None on last) Methods: cycle(*values): Return values[index % len(values)] Output: <ul> <li class="odd">1/3: Apple ← First</li> <li class="even">2/3: Banana</li> <li class="odd">3/3: Cherry ← Last</li> </ul> ``` Methods index 0 int ▼ 1-based iteration count. property def index(self) -> int Returns int index0 0 int ▼ 0-based iteration count. property def index0(self) -> int Returns int first 0 bool ▼ True if this is the first iteration. property def first(self) -> bool Returns bool last 0 bool ▼ True if this is the last iteration. property def last(self) -> bool Returns bool length 0 int ▼ Total number of items in the sequence. property def length(self) -> int Returns int revindex 0 int ▼ Reverse 1-based index (counts down to 1). property def revindex(self) -> int Returns int revindex0 0 int ▼ Reverse 0-based index (counts down to 0). property def revindex0(self) -> int Returns int previtem 0 Any ▼ Previous item in the sequence, or None if first. property def previtem(self) -> Any Returns Any nextitem 0 Any ▼ Next item in the sequence, or None if last. property def nextitem(self) -> Any Returns Any cycle 0 Any ▼ Cycle through the given values. def cycle(self, *values: Any) -> Any Returns Any Internal Methods 3 ▼ __init__ 1 ▼ def __init__(self, items: list[Any]) -> None Parameters Name Type Description items — __iter__ 0 Any ▼ Iterate through items, updating index for each. def __iter__(self) -> Any Returns Any __repr__ 0 str ▼ def __repr__(self) -> str Returns str CachedBlocksDict 8 ▼ Dict wrapper that returns cached HTML for site-scoped blocks. Used by Kida's block cache optimizat… Dict wrapper that returns cached HTML for site-scoped blocks. Used by Kida's block cache optimization to intercept .get() calls from templates and return pre-rendered HTML for site-wide blocks (nav, footer, etc.). Complexity: O(1) for lookups. Methods get 2 Any ▼ Intercept .get() calls to return cached HTML when available. def get(self, key: str, default: Any = None) -> Any Parameters Name Type Description key — default — Default: None Returns Any setdefault 2 Any ▼ Preserve setdefault() behavior for block registration. Kida templates use .set… def setdefault(self, key: str, default: Any = None) -> Any Preserve setdefault() behavior for block registration. Kida templates use .setdefault() to register their own block functions if not already overridden by a child template. Parameters Name Type Description key — default — Default: None Returns Any keys 0 set[str] ▼ Support .keys() iteration. def keys(self) -> set[str] Returns set[str] copy 0 dict[str, Any] ▼ Support .copy() for embed/include operations. def copy(self) -> dict[str, Any] Returns dict[str, Any] Internal Methods 4 ▼ __init__ 4 ▼ def __init__(self, original: dict[str, Any] | None, cached: dict[str, str], cached_names: set[str], stats: dict[str, int] | None = None) Parameters Name Type Description original — cached — cached_names — stats — Default: None __getitem__ 1 Any ▼ Support dict[key] access. def __getitem__(self, key: str) -> Any Parameters Name Type Description key — Returns Any __setitem__ 2 ▼ Support dict[key] = value assignment. def __setitem__(self, key: str, value: Any) -> None Parameters Name Type Description key — value — __contains__ 1 bool ▼ Support 'key in dict' checks. def __contains__(self, key: str) -> bool Parameters Name Type Description key — Returns bool Template 19 ▼ Compiled template ready for rendering. Wraps a compiled code object containing a `render(ctx, _blo… Compiled template ready for rendering. Wraps a compiled code object containing a render(ctx, _blocks) function. Templates are immutable and thread-safe for concurrent render() calls. Thread-Safety: Template object is immutable after construction Each render() call creates local state only (buf list) Multiple threads can render the same template simultaneously Memory Safety: Uses weakref.ref(env) to prevent circular reference leaks: Template → (weak) → Environment → _cache → Template Methods: render(**context): Render template with given variables render_async(**context): Async render for templates with await Error Enhancement: Runtime errors are caught and enhanced with template context: ``` TemplateRuntimeError: 'NoneType' has no attribute 'title' Location: article.html:15 Expression: {{ post.title }} Values: post = None (NoneType) Suggestion: Check if 'post' is defined before accessing .title ``` Attributes Name Type Description name — Template identifier (for error messages) filename — Source file path (for error messages) Methods name 0 str | None ▼ Template name. property def name(self) -> str | None Returns str | None filename 0 str | None ▼ Source filename. property def filename(self) -> str | None Returns str | None render 0 str ▼ Render template with given context. def render(self, *args: Any, **kwargs: Any) -> str Returns str Rendered template as string render_block 1 str ▼ Render a single block from the template. Renders just the named block, useful … def render_block(self, block_name: str, *args: Any, **kwargs: Any) -> str Render a single block from the template. Renders just the named block, useful for caching blocks that only depend on site-wide context (e.g., navigation, footer). Parameters Name Type Description block_name — Name of the block to render (e.g., "nav", "footer") *args: Single dict of context variables **kwargs: Context variables as keyword arguments Returns str Rendered block HTML as string list_blocks 0 list[str] ▼ List all blocks defined in this template. def list_blocks(self) -> list[str] Returns list[str] List of block names available for render_block() render_async 0 str ▼ Async wrapper for synchronous render. Runs the synchronous `render()` method i… async async def render_async(self, *args: Any, **kwargs: Any) -> str Async wrapper for synchronous render. Runs the synchronous render() method in a thread pool to avoid blocking the event loop. This is useful when calling from async code (e.g., FastAPI, aiohttp handlers). Returns str Rendered template as string block_metadata 0 dict[str, Any] ▼ Get metadata about template blocks. Returns a mapping of block name → BlockMet… def block_metadata(self) -> dict[str, Any] Get metadata about template blocks. Returns a mapping of block name → BlockMetadata with: depends_on: Context paths the block may access is_pure: Whether output is deterministic cache_scope: Recommended caching granularity inferred_role: Heuristic classification Results are cached after first call. Returns empty dict if: AST was not preserved (preserve_ast=False) Template was loaded from bytecode cache without source Returns dict[str, Any] template_metadata 0 Any ▼ Get full template metadata including inheritance info. **Returns TemplateMetad… def template_metadata(self) -> Any Get full template metadata including inheritance info. Returns TemplateMetadata with: name: Template identifier extends: Parent template name (if any) blocks: Mapping of block name → BlockMetadata top_level_depends_on: Context paths used outside blocks Returns None if AST was not preserved (preserve_ast=False or loaded from bytecode cache without source). Returns Any depends_on 0 frozenset[str] ▼ Get all context paths this template may access. Convenience method combining a… def depends_on(self) -> frozenset[str] Get all context paths this template may access. Convenience method combining all block dependencies and top-level dependencies. Returns empty frozenset if AST was not preserved. Returns frozenset[str] Internal Methods 8 ▼ _env 0 Environment ▼ Get the Environment (dereferences weak reference). property def _env(self) -> Environment Returns Environment __init__ 5 ▼ Initialize template with compiled code. def __init__(self, env: Environment, code: Any, name: str | None, filename: str | None, optimized_ast: Any = None) Parameters Name Type Description env — Parent Environment (stored as weak reference) code — Compiled Python code object name — Template name (for error messages) filename — Source filename (for error messages) optimized_ast — Optional preserved AST for introspection. If None, introspection methods return empty results. Default: None _enhance_error 2 Exception ▼ Enhance a generic exception with template context. Converts generic Python exc… def _enhance_error(self, error: Exception, ctx: dict[str, Any]) -> Exception Enhance a generic exception with template context. Converts generic Python exceptions into TemplateRuntimeError with template name and line number context. Parameters Name Type Description error — ctx — Returns Exception _escape 1 str ▼ HTML-escape a value. Uses optimized html_escape from utils.html module. Comple… staticmethod def _escape(value: Any) -> str HTML-escape a value. Uses optimized html_escape from utils.html module. Complexity: O(n) single-pass using str.translate(). Parameters Name Type Description value — Returns str _safe_getattr 2 Any ▼ Get attribute with dict fallback and None-safe handling. Handles both: - obj.a… staticmethod def _safe_getattr(obj: Any, name: str) -> Any Get attribute with dict fallback and None-safe handling. Handles both: obj.attr for objects with attributes dict['key'] for dict-like objects None Handling (like Hugo/Go templates): If obj is None, returns "" (prevents crashes) If attribute value is None, returns "" (normalizes output) Complexity: O(1) Parameters Name Type Description obj — name — Returns Any _getattr_preserve_none 2 Any ▼ Get attribute with dict fallback, preserving None values. Like _safe_getattr b… staticmethod def _getattr_preserve_none(obj: Any, name: str) -> Any Get attribute with dict fallback, preserving None values. Like _safe_getattr but preserves None values instead of converting to empty string. Used for optional chaining (?.) so that null coalescing (??) can work correctly. Part of RFC: kida-modern-syntax-features Handles both: obj.attr for objects with attributes dict['key'] for dict-like objects Complexity: O(1) Parameters Name Type Description obj — name — Returns Any _analyze 0 ▼ Perform static analysis and cache results. def _analyze(self) -> None __repr__ 0 str ▼ def __repr__(self) -> str Returns str RenderedTemplate 3 ▼ Lazy rendered template (for streaming). Allows iteration over rendered chunks for streaming output… Lazy rendered template (for streaming). Allows iteration over rendered chunks for streaming output. Not implemented in initial version. Methods Internal Methods 3 ▼ __init__ 2 ▼ def __init__(self, template: Template, context: dict[str, Any]) Parameters Name Type Description template — context — __str__ 0 str ▼ Render and return full string. def __str__(self) -> str Returns str __iter__ 0 Any ▼ Iterate over rendered chunks. def __iter__(self) -> Any Returns Any ← Previous nodes Next → tstring 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: 2338
- Reading Time: 12 minutes