# composition

URL: /kida/api/composition/
Section: api
Description: 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:
    ...     ...

---

> For a complete page index, fetch /kida/llms.txt.

Open LLM text
(/kida/api/composition/index.txt)

Share with AI

Ask Claude
(https://claude.ai/new?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Fcomposition%2Findex.txt)

Ask ChatGPT
(https://chatgpt.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Fcomposition%2Findex.txt)

Ask Gemini
(https://gemini.google.com/app?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Fcomposition%2Findex.txt)

Ask Copilot
(https://copilot.microsoft.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Fcomposition%2Findex.txt)

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`