Module

composition

Public composition API for template structure and block validation.

Provides validation helpers for frameworks like Chirp that compose templates via block rendering and layout assembly. Use these to validate block existence and structure before rendering, enabling clearer errors and composition planning.

Example:

>>> from kida import Environment
>>> from kida.composition import validate_block_exists, get_structure
>>> env = Environment(loader=FileSystemLoader("templates/"))
>>> if validate_block_exists(env, "page.html", "content"):
...     html = env.get_template("page.html").render_block("content", ...)
>>> struct = get_structure(env, "page.html")
>>> if struct and "page_root" in struct.block_names:
...     ...
4Functions

Functions

validate_block_exists 3 bool ▼
Check if a block exists in a template (including inherited blocks). Uses list_…
def validate_block_exists(env: Environment, template_name: str, block_name: str) -> bool

Check if a block exists in a template (including inherited blocks).

Uses list_blocks() which reflects the effective block map after inheritance. Useful for frameworks to validate ViewRef/block_name before calling render_block().

Parameters
Name Type Description
env Environment

Kida Environment.
template_name str

Template identifier (e.g., "page.html").
block_name str

Block to check (e.g., "content", "page_root").
Returns
bool
validate_template_block 2 bool ▼
Check if a block exists in a Template instance. Convenience when you already h…
def validate_template_block(template: Template, block_name: str) -> bool

Check if a block exists in a Template instance.

Convenience when you already have a loaded Template. Uses list_blocks() which includes inherited blocks.

Parameters
Name Type Description
template Template

Loaded Kida Template.
block_name str

Block to check.
Returns
bool
get_structure 2 TemplateStructureManifes… ▼
Get lightweight structure manifest for a template. Returns block names, extend…
def get_structure(env: Environment, template_name: str) -> TemplateStructureManifest | None

Get lightweight structure manifest for a template.

Returns block names, extends parent, block hashes, and dependencies. Cached by Environment for reuse. Returns None if template not found or analysis unavailable (e.g., no preserved AST).

Parameters
Name Type Description
env Environment

Kida Environment.
template_name str

Template identifier.
Returns
TemplateStructureManifest | None
block_role_for_framework 3 str | None ▼
Classify block metadata into framework-relevant roles. Maps BlockMetadata.infe…
def block_role_for_framework(block_metadata: Any, *, content_roles: frozenset[str] = frozenset({'content', 'main', 'page_content'}), root_roles: frozenset[str] = frozenset({'page_root', 'root', 'layout'})) -> str | None

Classify block metadata into framework-relevant roles.

Maps BlockMetadata.inferred_role and block name to Chirp-style roles:

  • "fragment": suitable for narrow fragment (content, main)
  • "page_root": suitable for boosted page root
  • None: unknown or not applicable
Parameters
Name Type Description
block_metadata Any

BlockMetadata from template_metadata().blocks.
content_roles frozenset[str]

Block names treated as content/fragment.

Default:frozenset({'content', 'main', 'page_content'})
root_roles frozenset[str]

Block names treated as page root.

Default:frozenset({'page_root', 'root', 'layout'})
Returns
str | None