# introspection URL: /kida/api/template/introspection/ Section: template Description: Template introspection mixin (RFC: kida-template-introspection). Adds static analysis and metadata methods to the Template class via mixin inheritance. --- > For a complete page index, fetch /kida/llms.txt. Open LLM text (/kida/api/template/introspection/index.txt) Share with AI Ask Claude (https://claude.ai/new?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Ftemplate%2Fintrospection%2Findex.txt) Ask ChatGPT (https://chatgpt.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Ftemplate%2Fintrospection%2Findex.txt) Ask Gemini (https://gemini.google.com/app?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Ftemplate%2Fintrospection%2Findex.txt) Ask Copilot (https://copilot.microsoft.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Ftemplate%2Fintrospection%2Findex.txt) 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` 11 ▼ 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 _def_metadata_cache: dict[str, DefMetadata] | 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]` `def_metadata` 0 `dict[str, DefMetadata]` ▼ Get metadata about ``{% def %}`` components in this template. Returns a mappin… `def def_metadata(self) -> dict[str, DefMetadata]` Get metadata about`{% def %}`components in this template. Returns a mapping of def name → DefMetadata with: - params: Parameter names, annotations, and defaults - slots: Named slots used in the def body - has_default_slot: Whether an unnamed`{% slot %}`exists - depends_on: Context paths read by the def body outside its params Results are cached after first call. Returns empty dict if AST was not preserved (preserve_ast=False). ##### Returns `dict[str, DefMetadata]` `list_defs` 0 `list[str]` ▼ List all ``{% def %}`` names defined in this template. `def list_defs(self) -> list[str]` ##### Returns `list[str]` List of def names defined in this template. `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]` `dependencies` 0 `dict[str, list[str]]` ▼ Get template dependency graph: extends, includes, embeds, imports. Returns a d… `def dependencies(self) -> dict[str, list[str]]` Get template dependency graph: extends, includes, embeds, imports. Returns a dict with keys "extends", "includes", "embeds", "imports", each mapping to a list of template names (string literals only). Dynamic template names (e.g. {{ var }}) are not included. Returns empty dict if AST was not preserved. ##### Returns `dict[str, list[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 accesses`page.title` requires `page`to be in context, but does not verify that`page` has a `title`attribute. ##### 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 2 ▼ `_analyze` 0 ▼ Perform static analysis and cache results. `def _analyze(self) -> None` `_analyze_defs` 0 ▼ Walk the AST to extract DefMetadata for all {% def %} nodes. `def _analyze_defs(self) -> None`