Module

template.introspection

Template introspection mixin (RFC: kida-template-introspection).

Adds static analysis and metadata methods to the Template class via mixin inheritance.

1Class

Classes

TemplateIntrospectionMixin 7 ▼
Mixin adding static analysis and introspection to Template. Requires the host class to define the …

Mixin adding static analysis and introspection to Template.

Requires the host class to define the following slots:

_optimized_ast: TemplateNode | None
_metadata_cache: TemplateMetadata | None
_name: str | None
_env_ref: weakref.ref[Environment]

Methods

block_metadata 0 dict[str, BlockMetadata] ▼
Get metadata about template blocks. Returns a mapping of block name -> BlockMe…
def block_metadata(self) -> dict[str, BlockMetadata]

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, BlockMetadata]
template_metadata 0 TemplateMetadata | None ▼
Get full template metadata including inheritance info. **Returns TemplateMetad…
def template_metadata(self) -> TemplateMetadata | None

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
TemplateMetadata | None
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]
required_context 0 frozenset[str] ▼
Get the set of context variable names this template requires. Returns top-leve…
def required_context(self) -> frozenset[str]

Get the set of context variable names this template requires.

Returns top-level variable names (without dotted paths) that the template depends on. This is useful for checking whether a context dictionary provides all required variables before rendering.

Returns empty frozenset if AST was not preserved.

Returns
frozenset[str]
is_cacheable 1 bool ▼
Check if a block (or the whole template) can be safely cached.
def is_cacheable(self, block_name: str | None = None) -> bool
Parameters
Name Type Description
block_name —

Specific block to check. If None, returns True only if all blocks are cacheable.

Default:None
Returns
bool True if the target is pure and has a cacheable scope.
validate_context 1 list[str] ▼
Check a context dict for missing variables the template requires. Compares pro…
def validate_context(self, context: dict[str, Any]) -> list[str]

Check a context dict for missing variables the template requires.

Compares provided context keys against the template's dependency analysis to identify variables that the template references but are not present in the context. This catches missing variables before rendering, avoiding runtime UndefinedError.

Note: This checks top-level variable names only. A template that accessespage.title requires pageto be in context, but does not verify thatpage has a titleattribute.

Parameters
Name Type Description
context —

The context dictionary that would be passed to render().
Returns
list[str] List of missing top-level variable names, sorted alphabetically. Empty list if all required variables are present or if AST was not preserved (no analysis available).
Internal Methods 1 ▼
_analyze 0 ▼
Perform static analysis and cache results.
def _analyze(self) -> None