# nodes

URL: /api/nodes/
Section: api

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

nodes - 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 nodes Kida AST node definitions. Immutable, frozen dataclass nodes representing the Kida template AST. All nodes track source location (lineno, col_offset) for error reporting. Kida-Native Features: Unified endings: {% end %} closes any block (like Go templates) Functions: {% def %} with true lexical scoping (not Jinja macros) Pipeline: |> for readable filter chains Pattern matching: {% match %}...{% case %}...{% end %} Caching: {% cache key %}...{% end %} with TTL support Explicit scoping: {% let %} (template), {% set %} (block), {% export %} Node Categories: Template Structure: Template: Root node containing body Extends, Block, Include: Inheritance and composition Import, FromImport: Function imports Control Flow: If, For, While: Standard control flow AsyncFor: Native async iteration Match: Pattern matching Variables: Set: Block-scoped assignment Let: Template-scoped assignment Export: Export from inner scope to enclosing scope Capture: Capture block output to variable Functions: Def: Function definition CallBlock: Call function with body content Slot: Content placeholder in components Expressions: Const, Name: Literals and identifiers Getattr, Getitem: Attribute and subscript access FuncCall, Filter, Pipeline: Function calls and filters BinOp, UnaryOp, Compare, BoolOp: Operators CondExpr: Ternary conditional Test: is test expressions Output: Output: Expression output {{ expr }} Data: Raw text between template constructs Thread-Safety: All nodes are frozen dataclasses, making the AST immutable and safe for concurrent access. The Parser produces a new AST on each call. 60Classes Classes Node 2 ▼ Base class for all AST nodes. All nodes track their source location for error reporting. Nodes are… Base class for all AST nodes. All nodes track their source location for error reporting. Nodes are immutable for thread-safety. Attributes Name Type Description lineno int — col_offset int — Template 3 ▼ Root node representing a complete template. Root node representing a complete template. Attributes Name Type Description body Sequence[Node] Sequence of top-level nodes extends Extends | None Optional parent template path context_type TemplateContext | None Optional type declaration from {% template %} TemplateContext 1 ▼ Type declaration: {% template page: Page, site: Site %} Kida-native feature for type-aware validat… Type declaration: {% template page: Page, site: Site %} Kida-native feature for type-aware validation. Attributes Name Type Description declarations Sequence[tuple[str, str]] — Extends 1 ▼ Template inheritance: {% extends "base.html" %} Template inheritance: {% extends "base.html" %} Attributes Name Type Description template Expr — Block 4 ▼ Named block for inheritance: {% block name %}...{% end %} Kida uses unified {% end %} for all bloc… Named block for inheritance: {% block name %}...{% end %} Kida uses unified {% end %} for all block closings. Attributes Name Type Description name str Block identifier body Sequence[Node] Block content scoped bool If True, block has its own variable scope required bool If True, child templates must override this block Include 3 ▼ Include another template: {% include "partial.html" %} Include another template: {% include "partial.html" %} Attributes Name Type Description template Expr Template path expression with_context bool If True, pass current context to included template ignore_missing bool If True, silently skip if template doesn't exist Import 3 ▼ Import functions from template: {% import "funcs.html" as f %} Import functions from template: {% import "funcs.html" as f %} Attributes Name Type Description template Expr — target str — with_context bool — FromImport 3 ▼ Import specific functions: {% from "funcs.html" import button, card %} Import specific functions: {% from "funcs.html" import button, card %} Attributes Name Type Description template Expr — names Sequence[tuple[str, str | None]] — with_context bool — Output 2 ▼ Output expression: {{ expr }} Output expression: {{ expr }} Attributes Name Type Description expr Expr Expression to output escape bool If True, HTML-escape the result Data 1 ▼ Raw text data between template constructs. Raw text data between template constructs. Attributes Name Type Description value str — If 4 ▼ Conditional: {% if cond %}...{% elif cond %}...{% else %}...{% end %} Kida uses unified {% end %} … Conditional: {% if cond %}...{% elif cond %}...{% else %}...{% end %} Kida uses unified {% end %} instead of {% endif %}. Attributes Name Type Description test Expr Condition expression body Sequence[Node] Nodes to render if condition is true elif_ Sequence[tuple[Expr, Sequence[Node]]] Sequence of (condition, body) pairs else_ Sequence[Node] Nodes to render if all conditions are false For 6 ▼ For loop: {% for x in items %}...{% empty %}...{% end %} Kida uses {% empty %} (not {% else %}) an… For loop: {% for x in items %}...{% empty %}...{% end %} Kida uses {% empty %} (not {% else %}) and {% end %} (not {% endfor %}). Attributes Name Type Description target Expr Loop variable(s) - can be tuple for unpacking iter Expr Iterable expression body Sequence[Node] Loop body empty Sequence[Node] Rendered if iterable is empty (Kida uses 'empty' not 'else') recursive bool Enable recursive loop calls test Expr | None Optional filter condition (like Python's if in comprehensions) AsyncFor 4 ▼ Async for loop: {% async for x in async_items %}...{% end %} Native async iteration without wrappe… Async for loop: {% async for x in async_items %}...{% end %} Native async iteration without wrapper adapters. Attributes Name Type Description target Expr — iter Expr — body Sequence[Node] — empty Sequence[Node] — While 2 ▼ While loop: {% while cond %}...{% end %} Kida-native feature. While loop: {% while cond %}...{% end %} Kida-native feature. Attributes Name Type Description test Expr — body Sequence[Node] — Match 2 ▼ Pattern matching: {% match expr %}{% case pattern [if guard] %}...{% end %} Kida-native feature fo… Pattern matching: {% match expr %}{% case pattern [if guard] %}...{% end %} Kida-native feature for cleaner branching than if/elif chains. Supports optional guard clauses for conditional matching. With guards: {% match api_type %} {% case _ if 'python' in api_type %}Python API {% case _ if 'rest' in api_type %}REST API {% case _ %}Other {% end %} Attributes Name Type Description subject Expr — cases Sequence[tuple[Expr, Expr | None, Sequence[Node]]] — Let 2 ▼ Template-scoped variable: {% let x = expr %} or {% let a, b = 1, 2 %} Variables declared with 'let… Template-scoped variable: {% let x = expr %} or {% let a, b = 1, 2 %} Variables declared with 'let' persist across the template and can be modified within inner scopes. Supports tuple unpacking on the left-hand side. Kida-native replacement for Jinja's confusing namespace() workaround. Attributes Name Type Description name Expr — value Expr — Set 2 ▼ Block-scoped variable: {% set x = expr %} or {% set a, b = 1, 2 %} Variable is scoped to current b… Block-scoped variable: {% set x = expr %} or {% set a, b = 1, 2 %} Variable is scoped to current block. Use 'let' for template-wide scope. Supports tuple unpacking on the left-hand side. Attributes Name Type Description target Expr Assignment target - can be a Name or Tuple of Names value Expr Value expression to assign Export 2 ▼ Export variable from inner scope: {% export x = expr %} or {% export a, b = 1, 2 %} Explicitly exp… Export variable from inner scope: {% export x = expr %} or {% export a, b = 1, 2 %} Explicitly exports a variable from an inner scope (like a for loop) to the enclosing scope. Makes scope behavior explicit and predictable. Supports tuple unpacking on the left-hand side. Attributes Name Type Description name Expr — value Expr — Capture 3 ▼ Capture block content: {% capture x %}...{% end %} Kida-native name (clearer than Jinja's {% set x… Capture block content: {% capture x %}...{% end %} Kida-native name (clearer than Jinja's {% set x %}...{% endset %}). Attributes Name Type Description name str — body Sequence[Node] — filter Filter | None — Def 4 ▼ Function definition: {% def name(args) %}...{% end %} Kida uses functions with true lexical scopin… Function definition: {% def name(args) %}...{% end %} Kida uses functions with true lexical scoping instead of macros. Functions can access variables from their enclosing scope. Attributes Name Type Description name str Function name args Sequence[str] Argument names body Sequence[Node] Function body defaults Sequence[Expr] Default argument values Slot 1 ▼ Slot for component content: {% slot %} Used inside {% def %} to mark where caller content goes. Slot for component content: {% slot %} Used inside {% def %} to mark where caller content goes. Attributes Name Type Description name str — CallBlock 3 ▼ Call function with body content: {% call name(args) %}body{% end %} The body content fills the {% … Call function with body content: {% call name(args) %}body{% end %} The body content fills the {% slot %} in the function. Attributes Name Type Description call Expr — body Sequence[Node] — args Sequence[Expr] — Cache 4 ▼ Fragment caching: {% cache key %}...{% end %} Kida-native built-in caching. No external dependenci… Fragment caching: {% cache key %}...{% end %} Kida-native built-in caching. No external dependencies required. Attributes Name Type Description key Expr Cache key expression body Sequence[Node] Content to cache ttl Expr | None Optional time-to-live expression depends Sequence[Expr] Optional dependency expressions for invalidation With 2 ▼ Jinja2-style context manager: {% with x = expr %}...{% end %} Always renders body with variable bi… Jinja2-style context manager: {% with x = expr %}...{% end %} Always renders body with variable bindings. Attributes Name Type Description targets Sequence[tuple[str, Expr]] — body Sequence[Node] — WithConditional 4 ▼ Conditional with block: {% with expr as name %}...{% end %} Renders body only if expr is truthy. B… Conditional with block: {% with expr as name %}...{% end %} Renders body only if expr is truthy. Binds the evaluated expression to the specified variable name(s). This provides nil-resilience: the block is silently skipped when the expression evaluates to None, empty collections, or other falsy values. Syntax: {% with page.author as author %} <span>{{ author.name }}</span> {% end %} {% with page.author %} <span>{{ it.name }}</span> {% end %} {% with a, b as x, y %} {{ x }}, {{ y }} {% end %} Behavior: Evaluates expr once If truthy: binds result to target, renders body If falsy: renders empty block (if provided), or skips entirely Restores previous variable binding after block Contrast with standard With node: With: Always renders body with variable bindings WithConditional: Only renders if expression is truthy Attributes Name Type Description expr Expr — target Expr — body Sequence[Node] — empty Sequence[Node] — FilterBlock 2 ▼ Apply filter to block: {% filter upper %}...{% end %} Apply filter to block: {% filter upper %}...{% end %} Attributes Name Type Description filter Filter — body Sequence[Node] — Autoescape 2 ▼ Control autoescaping: {% autoescape true %}...{% end %} Control autoescaping: {% autoescape true %}...{% end %} Attributes Name Type Description enabled bool — body Sequence[Node] — Raw 1 ▼ Raw block (no template processing): {% raw %}...{% end %} Raw block (no template processing): {% raw %}...{% end %} Attributes Name Type Description value str — Trim 1 ▼ Whitespace control block: {% trim %}...{% end %} Kida-native replacement for Jinja's {%- -%} modif… Whitespace control block: {% trim %}...{% end %} Kida-native replacement for Jinja's {%- -%} modifiers. Content inside is trimmed of leading/trailing whitespace. Attributes Name Type Description body Sequence[Node] — Break 0 ▼ Break out of loop: {% break %} Exits the innermost for/while loop. Part of RFC: kida-modern-syntax… Break out of loop: {% break %} Exits the innermost for/while loop. Part of RFC: kida-modern-syntax-features. Continue 0 ▼ Skip to next iteration: {% continue %} Skips to the next iteration of the innermost for/while loop… Skip to next iteration: {% continue %} Skips to the next iteration of the innermost for/while loop. Part of RFC: kida-modern-syntax-features. Spaceless 1 ▼ Remove whitespace between HTML tags: {% spaceless %}...{% end %} Removes whitespace between > and … Remove whitespace between HTML tags: {% spaceless %}...{% end %} Removes whitespace between > and <, preserving content whitespace. Part of RFC: kida-modern-syntax-features. Attributes Name Type Description body Sequence[Node] — Embed 3 ▼ Embed template with block overrides: {% embed 'card.html' %}...{% end %} Like include, but allows … Embed template with block overrides: {% embed 'card.html' %}...{% end %} Like include, but allows overriding blocks in the embedded template. Part of RFC: kida-modern-syntax-features. Attributes Name Type Description template Expr Template path expression blocks dict[str, Block] Block overrides defined in embed body with_context bool Pass current context to embedded template Expr 0 ▼ Base class for expressions. Base class for expressions. Const 1 ▼ Constant value: string, number, boolean, None. Constant value: string, number, boolean, None. Attributes Name Type Description value str | int | float | bool | None — Name 2 ▼ Variable reference: {{ user }} Variable reference: {{ user }} Attributes Name Type Description name str — ctx Literal['load', 'store', 'del'] — Tuple 2 ▼ Tuple expression: (a, b, c) Tuple expression: (a, b, c) Attributes Name Type Description items Sequence[Expr] — ctx Literal['load', 'store'] — List 1 ▼ List expression: [a, b, c] List expression: [a, b, c] Attributes Name Type Description items Sequence[Expr] — Dict 2 ▼ Dict expression: {a: b, c: d} Dict expression: {a: b, c: d} Attributes Name Type Description keys Sequence[Expr] — values Sequence[Expr] — Getattr 2 ▼ Attribute access: obj.attr Attribute access: obj.attr Attributes Name Type Description obj Expr — attr str — OptionalGetattr 2 ▼ Optional attribute access: obj?.attr Returns None if obj is None/undefined, otherwise obj.attr. Pa… Optional attribute access: obj?.attr Returns None if obj is None/undefined, otherwise obj.attr. Part of RFC: kida-modern-syntax-features. Attributes Name Type Description obj Expr — attr str — Getitem 2 ▼ Subscript access: obj[key] Subscript access: obj[key] Attributes Name Type Description obj Expr — key Expr — OptionalGetitem 2 ▼ Optional subscript access: obj?[key] Returns None if obj is None/undefined, otherwise obj[key]. Pa… Optional subscript access: obj?[key] Returns None if obj is None/undefined, otherwise obj[key]. Part of RFC: kida-modern-syntax-features. Attributes Name Type Description obj Expr — key Expr — Slice 3 ▼ Slice expression: [start:stop:step] Slice expression: [start:stop:step] Attributes Name Type Description start Expr | None — stop Expr | None — step Expr | None — FuncCall 5 ▼ Function call: func(args, **kwargs) Function call: func(args, **kwargs) Attributes Name Type Description func Expr — args Sequence[Expr] — kwargs dict[str, Expr] — dyn_args Expr | None — dyn_kwargs Expr | None — Filter 4 ▼ Filter application: expr | filter(args) Filter application: expr | filter(args) Attributes Name Type Description value Expr — name str — args Sequence[Expr] — kwargs dict[str, Expr] — Pipeline 2 ▼ Pipeline operator: expr |> filter1 |> filter2 Kida-native syntax for readable filter chains. More … Pipeline operator: expr |> filter1 |> filter2 Kida-native syntax for readable filter chains. More readable than deeply nested Jinja filters. Attributes Name Type Description value Expr — steps Sequence[tuple[str, Sequence[Expr], dict[str, Expr]]] — Test 5 ▼ Test application: expr is test(args) or expr is not test(args) Test application: expr is test(args) or expr is not test(args) Attributes Name Type Description value Expr — name str — args Sequence[Expr] — kwargs dict[str, Expr] — negated bool — BinOp 3 ▼ Binary operation: left op right Binary operation: left op right Attributes Name Type Description op str — left Expr — right Expr — UnaryOp 2 ▼ Unary operation: op operand Unary operation: op operand Attributes Name Type Description op str — operand Expr — Compare 3 ▼ Comparison: left op1 right1 op2 right2 ... Supports chained comparisons like: 1 < x < 10 Comparison: left op1 right1 op2 right2 ... Supports chained comparisons like: 1 < x < 10 Attributes Name Type Description left Expr — ops Sequence[str] — comparators Sequence[Expr] — BoolOp 2 ▼ Boolean operation: expr1 and/or expr2 Boolean operation: expr1 and/or expr2 Attributes Name Type Description op Literal['and', 'or'] — values Sequence[Expr] — CondExpr 3 ▼ Conditional expression: a if cond else b Conditional expression: a if cond else b Attributes Name Type Description test Expr — if_true Expr — if_false Expr — NullCoalesce 2 ▼ Null coalescing: a ?? b Returns b if a is None/undefined, otherwise a. Unlike 'or', doesn't treat … Null coalescing: a ?? b Returns b if a is None/undefined, otherwise a. Unlike 'or', doesn't treat falsy values (0, '', False, []) as missing. Part of RFC: kida-modern-syntax-features. Attributes Name Type Description left Expr — right Expr — Range 4 ▼ Range literal: start..end or start...end Part of RFC: kida-modern-syntax-features. Range literal: start..end or start...end Part of RFC: kida-modern-syntax-features. Attributes Name Type Description start Expr Start value (inclusive) end Expr End value (inclusive if inclusive=True) inclusive bool True for .., False for ... step Expr | None Optional step value (from 'by' keyword) Await 1 ▼ Await expression: await expr Native async support without auto_await() wrappers. Await expression: await expr Native async support without auto_await() wrappers. Attributes Name Type Description value Expr — Concat 1 ▼ String concatenation: a ~ b ~ c Multiple ~ operators are collapsed into a single Concat node for e… String concatenation: a ~ b ~ c Multiple ~ operators are collapsed into a single Concat node for efficient string building. Attributes Name Type Description nodes Sequence[Expr] — MarkSafe 1 ▼ Mark expression as safe (no escaping): {{ expr | safe }} Mark expression as safe (no escaping): {{ expr | safe }} Attributes Name Type Description value Expr — LoopVar 1 ▼ Loop variable access: {{ loop.index }} Provides access to loop iteration state. Loop variable access: {{ loop.index }} Provides access to loop iteration state. Attributes Name Type Description attr str — InlinedFilter 3 ▼ Inlined filter as direct method call (optimization). Generated by FilterInliner for common pure fi… Inlined filter as direct method call (optimization). Generated by FilterInliner for common pure filters like upper, lower, strip. The compiler generates str(value).method() instead of filter dispatch. Attributes Name Type Description value Expr — method str — args Sequence[Expr] — ← Previous lexer Next → template 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: 3484
- Reading Time: 17 minutes