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_onmay include unused paths (over-approximation)
  • is_puredefaults to "unknown" when uncertain
  • inferred_roleis 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 byBlockAnalyzer.validate_calls() when a FuncCalltargets 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.

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 byBlockAnalyzer.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 7 ▼
Metadata about a ``{% def %}`` component, inferred from static analysis. Parallel to `BlockMetadat…

Metadata about a{% def %}component, inferred from static analysis.

Parallel toBlockMetadatafor 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).
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.