render_plan - Chirp

Render-plan layer — decides what to render before serialization.

Pipeline: normalize_to_composition → build_render_plan → execute_render_plan → serialize_rendered_plan. Keeps request-aware decisions in one place.

templating.render_plan

Name	Type	Default	Description
`type`		—
`qualified_name`		—
`element_type`		—
`description`		—
`source_file`		—
`line_number`		—
`is_autodoc`		—
`autodoc_element`		—
`_autodoc_template`		—
`_autodoc_url_path`		—
`_autodoc_page_type`		—
`title`		—
`doc_content_hash`		—

Symbols on this page

function _capture_render

Record (template, context) forchirp freezelive-block rewriting.

Outside of freeze the capture ContextVar isNoneand this is a no-op.

class OOBBlockInfo

AST-derived metadata for a single OOB block in a layout template.

class LayoutContract

Cached contract describing which OOB blocks a layout template provides.

class RenderPlan

Plan for what to render based on composition and request.

class RenderedPlan

Result of execute_render_plan — main HTML and region HTML by id.

function _resolve_fragment_block

Resolve fragment block: explicit > htmx partial > HX-Target registry lookup > fallback.

function _fragment_block_for_request

Choose block for htmx fragment response.

function _should_render_page_block

Whether request needs page-level root instead of narrow fragment.

function _compute_layout_start_index

Compute layout start index for HX-Target-aware depth.

htmx_target may be either #idor bare-id form; both are normalized downstream byFragmentTargetRegistryand LayoutChain.…

function _needs_omitted_outlet_reselect

Return whether htmx 2 needs its inherited selector neutralized.

A replace-mode shell (or a target withomit_outer_layouts) deliberately omits the layout that owns…

function normalize_to_composition

Convert Page, LayoutPage, or PageComposition to PageComposition.

Returns None for values that are not page-like compositions.

function build_render_plan

Build a render plan from composition and request headers.

function _oob_block_names

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…

function build_layout_contract

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…

function _validate_view_ref

Validate that a view's block exists. Raises BlockNotFoundError if missing.

BlockNotFoundError is a KeyError subclass, soexcept KeyErrorcallers continue to work unchanged.

function execute_render_plan

Execute a render plan using the template adapter.

function _block_exists

Check template metadata for a named block. Returns False when the template is missing/unparseable (adapter.template_metadata returns None).

function _region_is_optional

True when the OOB region is explicitly registered as optional.

function serialize_rendered_plan

Serialize rendered plan to final HTML with OOB fragments.

_capture_render

function

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	Default	Description
`template_name`	`str`	—
`context`	`dict[str, Any]`	—

OOBBlockInfo

class

AST-derived metadata for a single OOB block in a layout template.

LayoutContract

class

Cached contract describing which OOB blocks a layout template provides.

RenderPlan

class

Plan for what to render based on composition and request.

RenderedPlan

class

Result of execute_render_plan — main HTML and region HTML by id.

_resolve_fragment_block

function

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	Default
`composition`	`PageComposition`	—
`request`	`Request \| None`	—
`fragment_target_registry`	`FragmentTargetRegistry \| None`	`None`

_fragment_block_for_request

function

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

Choose block for htmx fragment response.

Parameters

Name	Type	Default
`composition`	`PageComposition`	—
`request`	`Request \| None`	—
`layout_chain`	`LayoutChain \| None`	`None`
`layout_start_index`	`int`	`0`
`fragment_target_registry`	`FragmentTargetRegistry \| None`	`None`

_should_render_page_block

function

def _should_render_page_block(request: Request | None) -> bool

Whether request needs page-level root instead of narrow fragment.

Parameters

Name	Type	Default	Description
`request`	`Request \| None`	—

_compute_layout_start_index

function

def _compute_layout_start_index(layout_chain: LayoutChain | None, htmx_target: str | None, is_history_restore: bool, *, fragment_target_registry: FragmentTargetRegistry | None = None, force_partial: bool = False) -> 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	Default
`layout_chain`	`LayoutChain \| None`	—
`htmx_target`	`str \| None`	—
`is_history_restore`	`bool`	—
`fragment_target_registry`	`FragmentTargetRegistry \| None`	`None`
`force_partial`	`bool`	`False`

_needs_omitted_outlet_reselect

function

def _needs_omitted_outlet_reselect(*, request: Request | None, layout_chain: LayoutChain | None, layout_start_index: int, fragment_target_registry: FragmentTargetRegistry | None) -> bool

Return whether htmx 2 needs its inherited selector neutralized.

A replace-mode shell (or a target withomit_outer_layouts) deliberately omits the layout that owns an inheritedhx-selectwrapper. The fragment is valid, but the browser would select nothing and blank the outlet unless the response overrides that stale selector. Htmx 4 partial requests carry explicit target/partial metadata and do not use this compatibility path.

Parameters

Name	Type	Default
`request`	`Request \| None`	—
`layout_chain`	`LayoutChain \| None`	—
`layout_start_index`	`int`	—
`fragment_target_registry`	`FragmentTargetRegistry \| None`	—

normalize_to_composition

function

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	Default	Description
`value`	`Any`	—

build_render_plan

function

def build_render_plan(composition: PageComposition, *, request: Request | None = None, fragment_target_registry: FragmentTargetRegistry | None = None, shell_region_updates: tuple[RegionUpdate, ...] = ()) -> RenderPlan

Build a render plan from composition and request headers.

Parameters

Name	Type	Default
`composition`	`PageComposition`	—
`request`	`Request \| None`	`None`
`fragment_target_registry`	`FragmentTargetRegistry \| None`	`None`
`shell_region_updates`	`tuple[RegionUpdate, ...]`	`()`

_oob_block_names

function

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	Default	Description
`adapter`	`TemplateAdapter`	—
`template_name`	`str`	—

build_layout_contract

function

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	Default
`adapter`	`TemplateAdapter`	—
`template_name`	`str`	—
`oob_registry`	`OOBRegistry \| None`	`None`

_validate_view_ref

function

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	Default	Description
`adapter`	`TemplateAdapter`	—
`view`	`ViewRef`	—

execute_render_plan

function

def execute_render_plan(plan: RenderPlan, *, adapter: TemplateAdapter, validate_blocks: bool = False, oob_registry: OOBRegistry | None = None) -> RenderedPlan

Execute a render plan using the template adapter.

Parameters

Name	Type	Default	Description
`plan`	`RenderPlan`	—	Render plan from build_render_plan.
`adapter`	`TemplateAdapter`	—	Template engine adapter (e.g., KidaAdapter).
`validate_blocks`	`bool`	`False`	When True, validate blocks exist before render. Uses adapter.template_metadata() when available. Raises KeyError if a block is missing.
`oob_registry`	`OOBRegistry \| None`	`None`

_block_exists

function

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	Default
`adapter`	`TemplateAdapter`	—
`template`	`str`	—
`block`	`str`	—

_region_is_optional

function

def _region_is_optional(block_name: str, oob_registry: OOBRegistry | None) -> bool

True when the OOB region is explicitly registered as optional.

Parameters

Name	Type	Default	Description
`block_name`	`str`	—
`oob_registry`	`OOBRegistry \| None`	—

serialize_rendered_plan

function

def serialize_rendered_plan(rendered: RenderedPlan, *, oob_registry: OOBRegistry | None = None) -> str

Serialize rendered plan to final HTML with OOB fragments.

Parameters

Name	Type	Default	Description
`rendered`	`RenderedPlan`	—
`oob_registry`	`OOBRegistry \| None`	`None`

View source · /home/runner/work/chirp/chirp/site/../src/chirp/templating/render_plan.py:1