# metadata URL: /kida/api/analysis/metadata/ Section: analysis Description: Metadata dataclasses for template introspection. Immutable, frozen dataclasses representing analysis results. All fields are conservative estimates — may over-approximate but never under. --- > For a complete page index, fetch /kida/llms.txt. Open LLM text (/kida/api/analysis/metadata/index.txt) Share with AI Ask Claude (https://claude.ai/new?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Fanalysis%2Fmetadata%2Findex.txt) Ask ChatGPT (https://chatgpt.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Fanalysis%2Fmetadata%2Findex.txt) Ask Gemini (https://gemini.google.com/app?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Fanalysis%2Fmetadata%2Findex.txt) Ask Copilot (https://copilot.microsoft.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Fanalysis%2Fmetadata%2Findex.txt) Module # `analysis.metadata` Metadata dataclasses for template introspection. Immutable, frozen dataclasses representing analysis results. All fields are conservative estimates — may over-approximate but never under. 7Classes ## Classes `BlockMetadata` 14 ▼ Metadata about a template block, inferred from static analysis. **All fields are conservative esti… Metadata about a template block, inferred from static analysis. All fields are conservative estimates: - `depends_on`may include unused paths (over-approximation) - `is_pure`defaults to "unknown" when uncertain - `inferred_role`is heuristic, not semantic truth Thread-safe: Immutable after creation. #### Attributes Name Type Description `name` `str` Block identifier (e.g., "nav", "content", "sidebar") `emits_html` `bool` True if block produces any output. Used to detect empty blocks. `emits_landmarks` `frozenset[str]` HTML5 landmark elements emitted (nav, main, header, etc.). Detected from static HTML in Data nodes. `inferred_role` `Literal['navigation', 'content', 'sidebar', 'header', 'footer', 'unknown']` Heuristic classification based on name and landmarks. One of: "navigation", "content", "sidebar", "header", "footer", "unknown" `depends_on` `frozenset[str]` Context paths this block may access (conservative superset). `is_pure` `Literal['pure', 'impure', 'unknown']` Whether block output is deterministic for same inputs. - "pure": Deterministic, safe to cache - "impure": Uses random/shuffle/etc, must re-render - "unknown": Cannot determine, treat as potentially impure `cache_scope` `Literal['none', 'page', 'site', 'unknown']` Recommended caching granularity. - "site": Cache once per site build (no page-specific deps) - "page": Cache per page (has page-specific deps) - "none": Cannot cache (impure) - "unknown": Cannot determine `block_hash` `str` — `is_region` `bool` — `region_params` `tuple[str, ...]` — `Example` — frozenset({"page.title", "site.pages", "config.theme"}) #### Methods `is_cacheable` 0 `bool` ▼ Check if this block can be safely cached. **Returns True if:** - Block is pure… `def is_cacheable(self) -> bool` Check if this block can be safely cached. Returns True if: - Block is pure (deterministic) - Cache scope is not "none" ##### Returns `bool` True if block can be cached, False otherwise. `depends_on_page` 0 `bool` ▼ Check if block depends on page-specific context. `def depends_on_page(self) -> bool` ##### Returns `bool` True if any dependency starts with common page prefixes. `depends_on_site` 0 `bool` ▼ Check if block depends on site-wide context. `def depends_on_site(self) -> bool` ##### Returns `bool` True if any dependency starts with common site prefixes. `TemplateMetadata` 10 ▼ Metadata about a complete template. Aggregates block metadata and tracks template-level informatio… Metadata about a complete template. Aggregates block metadata and tracks template-level information like inheritance and top-level dependencies. #### Attributes Name Type Description `name` `str | None` Template identifier (e.g., "page.html") `extends` `str | None` Parent template name from {% extends %}, or None. `blocks` `dict[str, BlockMetadata]` Mapping of block name → BlockMetadata. All blocks defined in this template. `top_level_depends_on` `frozenset[str]` Context paths used outside blocks. Captures dependencies from: - Code before/after blocks - Dynamic extends expressions - Template-level set/let statements `Example` — "base.html" #### Methods `all_dependencies` 0 `frozenset[str]` ▼ Return all context paths used anywhere in template. Combines top-level depende… `def all_dependencies(self) -> frozenset[str]` Return all context paths used anywhere in template. Combines top-level dependencies with all block dependencies. ##### Returns `frozenset[str]` Frozen set of all context paths. `get_block` 1 `BlockMetadata | None` ▼ Get metadata for a specific block. `def get_block(self, name: str) -> BlockMetadata | None` ##### Parameters Name Type Description `name` `—` Block name to look up. ##### Returns `BlockMetadata | None` BlockMetadata if found, None otherwise. `cacheable_blocks` 0 `list[BlockMetadata]` ▼ Return all blocks that can be safely cached. `def cacheable_blocks(self) -> list[BlockMetadata]` ##### Returns `list[BlockMetadata]` List of BlockMetadata where is_cacheable() is True. `site_cacheable_blocks` 0 `list[BlockMetadata]` ▼ Return blocks that can be cached site-wide. `def site_cacheable_blocks(self) -> list[BlockMetadata]` ##### Returns `list[BlockMetadata]` List of BlockMetadata where cache_scope is "site". `regions` 0 `dict[str, BlockMetadata]` ▼ Return only region-typed blocks (RFC: kida-regions). `def regions(self) -> dict[str, BlockMetadata]` ##### Returns `dict[str, BlockMetadata]` `CallValidation` 7 ▼ Result of validating a single call site against a function definition. Produced by ``BlockAnalyzer… Result of validating a single call site against a function definition. Produced by`BlockAnalyzer.validate_calls()` when a `FuncCall`targets a`{% def %}`in the same compilation unit. #### Attributes Name Type Description `def_name` `str` Name of the called`{% def %}`. `lineno` `int` Source line of the call site. `col_offset` `int` Source column of the call site. `unknown_params` `tuple[str, ...]` Keyword argument names not in the definition's parameters. `missing_required` `tuple[str, ...]` Required parameters (no default) not provided by the call. `duplicate_params` `tuple[str, ...]` Keyword argument names supplied more than once. Parser-produced ASTs reject duplicate keyword arguments before validation; this field remains for callers validating externally constructed ASTs. #### Methods `is_valid` 0 `bool` ▼ Return True if no issues were found. property `def is_valid(self) -> bool` ##### Returns `bool` `TypeMismatch` 7 ▼ Result of a type mismatch at a call site. Produced by ``BlockAnalyzer.validate_call_types()`` when… Result of a type mismatch at a call site. Produced by`BlockAnalyzer.validate_call_types()`when a literal argument's type doesn't match the`{% def %}`parameter's annotation. Only literal arguments (strings, ints, floats, bools, None) are checked. Variable arguments are skipped since their type can't be known statically. #### Attributes Name Type Description `def_name` `str` Name of the called`{% def %}`. `param_name` `str` Parameter with the type mismatch. `expected` `str` Annotation string from the def signature (e.g.`"int"`). `actual_type` `str` Python type name of the literal (e.g.`"str"`). `actual_value` `str | int | float | bool | None` The literal value that was passed. `lineno` `int` Source line of the call site. `col_offset` `int` Source column of the call site. `DefParamInfo` 4 ▼ Metadata about a single parameter in a ``{% def %}`` component. Metadata about a single parameter in a`{% def %}`component. #### Attributes Name Type Description `name` `str` Parameter name. `annotation` `str | None` Type annotation string from template source (e.g.`"str"`), or None if untyped. `has_default` `bool` True if the parameter has a default value. `is_required` `bool` True if the parameter must be provided by callers. `DefMetadata` 9 ▼ Metadata about a ``{% def %}`` component, inferred from static analysis. Parallel to `BlockMetadat… Metadata about a`{% def %}`component, inferred from static analysis. Parallel to`BlockMetadata`for blocks — makes defs first-class citizens in Kida's introspection API. Thread-safe: Immutable after creation. #### Attributes Name Type Description `name` `str` Def identifier (e.g.`"card"`, `"button"`). `template_name` `str | None` Template where this def is defined. `lineno` `int` Source line number of the`{% def %}`tag. `params` `tuple[DefParamInfo, ...]` Parameter metadata in declaration order. `slots` `tuple[str, ...]` Named slots referenced in the def body (excludes`"default"`). `has_default_slot` `bool` True if the body contains an unnamed`{% slot %}`. `depends_on` `frozenset[str]` Context paths the def body may access (conservative superset). `vararg` `str | None` Name of the`*args`parameter, if declared. `kwarg` `str | None` Name of the`**kwargs`parameter, if declared. `TemplateStructureManifest` 5 ▼ Lightweight template structure for schedulers and dependency planners. Lightweight template structure for schedulers and dependency planners. #### Attributes Name Type Description `name` `str | None` Template name. `extends` `str | None` Parent template name from`{% extends %}`. `block_names` `tuple[str, ...]` Ordered block names in this template. `block_hashes` `dict[str, str]` Deterministic per-block structural hashes. `dependencies` `frozenset[str]` Top-level + block context dependencies.