Classes
OOBBlockInfo
4
▼
AST-derived metadata for a single OOB block in a layout template.
OOBBlockInfo
4
▼
AST-derived metadata for a single OOB block in a layout template.
Attributes
| Name | Type | Description |
|---|---|---|
block_name |
str
|
— |
target_id |
str
|
— |
cache_scope |
str
|
— |
depends_on |
frozenset[str]
|
— |
LayoutContract
2
▼
Cached contract describing which OOB blocks a layout template provides.
LayoutContract
2
▼
Cached contract describing which OOB blocks a layout template provides.
Attributes
| Name | Type | Description |
|---|---|---|
template_name |
str
|
— |
oob_blocks |
tuple[OOBBlockInfo, ...]
|
— |
RenderPlan
11
▼
Plan for what to render based on composition and request.
RenderPlan
11
▼
Plan for what to render based on composition and request.
Attributes
| Name | Type | Description |
|---|---|---|
intent |
RenderIntent
|
— |
main_view |
ViewRef
|
— |
render_full_template |
bool
|
— |
apply_layouts |
bool
|
— |
layout_chain |
LayoutChain | None
|
— |
layout_start_index |
int
|
— |
layout_context |
dict[str, Any]
|
— |
region_updates |
tuple[RegionUpdate, ...]
|
— |
response_headers |
dict[str, str]
|
— |
include_layout_oob |
bool
|
— |
oob_scope |
str | None
|
— |
RenderedPlan
2
▼
Result of execute_render_plan — main HTML and region HTML by id.
RenderedPlan
2
▼
Result of execute_render_plan — main HTML and region HTML by id.
Attributes
| Name | Type | Description |
|---|---|---|
main_html |
str
|
— |
region_htmls |
dict[str, str]
|
— |
Functions
_capture_render
2
None
▼
Record (template, context) for ``chirp freeze`` live-block rewriting.
Outside …
_capture_render
2
None
▼
def _capture_render(template_name: str, context: dict[str, Any]) -> None
Record (template, context) forchirp freezelive-block rewriting.
Outside of freeze the capture ContextVar isNoneand this is a no-op.
Parameters
| Name | Type | Description |
|---|---|---|
template_name |
str |
|
context |
dict[str, Any] |
_resolve_fragment_block
3
str
▼
Resolve fragment block: explicit > htmx partial > HX-Target registry lookup > f…
_resolve_fragment_block
3
str
▼
def _resolve_fragment_block(composition: PageComposition, request: Request | None, *, fragment_target_registry: FragmentTargetRegistry | None = None) -> str
Resolve fragment block: explicit > htmx partial > HX-Target registry lookup > fallback.
Parameters
| Name | Type | Description |
|---|---|---|
composition |
PageComposition |
|
request |
Request | None |
|
fragment_target_registry |
FragmentTargetRegistry | None |
Default:None
|
Returns
str
_fragment_block_for_request
5
str
▼
Choose block for htmx fragment response.
_fragment_block_for_request
5
str
▼
def _fragment_block_for_request(composition: PageComposition, request: Request | None, *, layout_chain: LayoutChain | None = None, layout_start_index: int = 0, fragment_target_registry: FragmentTargetRegistry | None = None) -> str
Parameters
| Name | Type | Description |
|---|---|---|
composition |
PageComposition |
|
request |
Request | None |
|
layout_chain |
LayoutChain | None |
Default:None
|
layout_start_index |
int |
Default:0
|
fragment_target_registry |
FragmentTargetRegistry | None |
Default:None
|
Returns
str
_should_render_page_block
1
bool
▼
Whether request needs page-level root instead of narrow fragment.
_should_render_page_block
1
bool
▼
def _should_render_page_block(request: Request | None) -> bool
Parameters
| Name | Type | Description |
|---|---|---|
request |
Request | None |
Returns
bool
_compute_layout_start_index
4
int
▼
Compute layout start index for HX-Target-aware depth.
``htmx_target`` may be e…
_compute_layout_start_index
4
int
▼
def _compute_layout_start_index(layout_chain: LayoutChain | None, htmx_target: str | None, is_history_restore: bool, *, fragment_target_registry: FragmentTargetRegistry | None = None) -> int
Compute layout start index for HX-Target-aware depth.
htmx_target may be either #idor bare-id form; both are
normalized downstream byFragmentTargetRegistryand
LayoutChain. New callers should prefer passing the bare form
fromrequest.htmx_target_id.
Parameters
| Name | Type | Description |
|---|---|---|
layout_chain |
LayoutChain | None |
|
htmx_target |
str | None |
|
is_history_restore |
bool |
|
fragment_target_registry |
FragmentTargetRegistry | None |
Default:None
|
Returns
int
normalize_to_composition
1
PageComposition | None
▼
Convert Page, LayoutPage, or PageComposition to PageComposition.
Returns None …
normalize_to_composition
1
PageComposition | None
▼
def normalize_to_composition(value: Any) -> PageComposition | None
Convert Page, LayoutPage, or PageComposition to PageComposition.
Returns None for values that are not page-like compositions.
Parameters
| Name | Type | Description |
|---|---|---|
value |
Any |
Returns
PageComposition | None
build_render_plan
4
RenderPlan
▼
Build a render plan from composition and request headers.
build_render_plan
4
RenderPlan
▼
def build_render_plan(composition: PageComposition, *, request: Request | None = None, fragment_target_registry: FragmentTargetRegistry | None = None, shell_region_updates: tuple[RegionUpdate, ...] = ()) -> RenderPlan
Parameters
| Name | Type | Description |
|---|---|---|
composition |
PageComposition |
|
request |
Request | None |
Default:None
|
fragment_target_registry |
FragmentTargetRegistry | None |
Default:None
|
shell_region_updates |
tuple[RegionUpdate, ...] |
Default:()
|
Returns
RenderPlan
_oob_block_names
2
set[str]
▼
Return block names ending with _oob for the given template.
Prefers meta.regio…
_oob_block_names
2
set[str]
▼
def _oob_block_names(adapter: TemplateAdapter, template_name: str) -> set[str]
Return block names ending with _oob for the given template.
Prefers meta.regions() when available (region-typed blocks); otherwise filters meta.blocks by *_oob suffix. Falls back to empty set when template_metadata is unavailable (e.g. Jinja2 adapter).
Parameters
| Name | Type | Description |
|---|---|---|
adapter |
TemplateAdapter |
|
template_name |
str |
Returns
set[str]
build_layout_contract
3
LayoutContract
▼
Build a LayoutContract from Kida's AST metadata for a layout template.
Discove…
build_layout_contract
3
LayoutContract
▼
def build_layout_contract(adapter: TemplateAdapter, template_name: str, *, oob_registry: OOBRegistry | None = None) -> LayoutContract
Build a LayoutContract from Kida's AST metadata for a layout template.
Discovers all *_oob blocks and extracts their cache_scope and depends_on
from BlockMetadata. Target IDs resolve through the oob_registry when
available, falling back to theblock_name.removesuffix("_oob")convention.
When template_metadata is unavailable and a registry is present, registered
blocks are used as the fallback set.
Parameters
| Name | Type | Description |
|---|---|---|
adapter |
TemplateAdapter |
|
template_name |
str |
|
oob_registry |
OOBRegistry | None |
Default:None
|
Returns
LayoutContract
_validate_view_ref
2
None
▼
Validate that a view's block exists. Raises BlockNotFoundError if missing.
Blo…
_validate_view_ref
2
None
▼
def _validate_view_ref(adapter: TemplateAdapter, view: ViewRef) -> None
Validate that a view's block exists. Raises BlockNotFoundError if missing.
BlockNotFoundError is a KeyError subclass, soexcept KeyErrorcallers
continue to work unchanged.
Parameters
| Name | Type | Description |
|---|---|---|
adapter |
TemplateAdapter |
|
view |
ViewRef |
execute_render_plan
4
RenderedPlan
▼
Execute a render plan using the template adapter.
execute_render_plan
4
RenderedPlan
▼
def execute_render_plan(plan: RenderPlan, *, adapter: TemplateAdapter, validate_blocks: bool = False, oob_registry: OOBRegistry | None = None) -> RenderedPlan
Parameters
| Name | Type | Description |
|---|---|---|
plan |
RenderPlan |
Render plan from build_render_plan. |
adapter |
TemplateAdapter |
Template engine adapter (e.g., KidaAdapter). |
validate_blocks |
bool |
When True, validate blocks exist before render. Uses adapter.template_metadata() when available. Raises KeyError if a block is missing. Default:False
|
oob_registry |
OOBRegistry | None |
Default:None
|
Returns
RenderedPlan
_block_exists
3
bool
▼
Check template metadata for a named block. Returns False when the template
is m…
_block_exists
3
bool
▼
def _block_exists(adapter: TemplateAdapter, template: str, block: str) -> bool
Check template metadata for a named block. Returns False when the template is missing/unparseable (adapter.template_metadata returns None).
Parameters
| Name | Type | Description |
|---|---|---|
adapter |
TemplateAdapter |
|
template |
str |
|
block |
str |
Returns
bool
_region_is_optional
2
bool
▼
True when the OOB region is explicitly registered as optional.
_region_is_optional
2
bool
▼
def _region_is_optional(block_name: str, oob_registry: OOBRegistry | None) -> bool
Parameters
| Name | Type | Description |
|---|---|---|
block_name |
str |
|
oob_registry |
OOBRegistry | None |
Returns
bool
serialize_rendered_plan
2
str
▼
Serialize rendered plan to final HTML with OOB fragments.
serialize_rendered_plan
2
str
▼
def serialize_rendered_plan(rendered: RenderedPlan, *, oob_registry: OOBRegistry | None = None) -> str
Parameters
| Name | Type | Description |
|---|---|---|
rendered |
RenderedPlan |
|
oob_registry |
OOBRegistry | None |
Default:None
|
Returns
str