Module

render_capture

Kida RenderCapture — opt-in content capture during template rendering.

This module provides render-time data capture for block content, context snapshots, and content hashing. Enables search indexing, block-level caching, and semantic diffing as byproducts of rendering.

Zero overhead when disabled (get_capture() returns None).

RFC: render-capture

Example:

from kida import Environment, FileSystemLoader
from kida.render_capture import captured_render

env = Environment(loader=FileSystemLoader("templates/"), enable_capture=True)
template = env.get_template("page.html")

# Normal render (no overhead)
html = template.render(page=page)

# Captured render (opt-in)
with captured_render(
    capture_blocks=frozenset({"content", "sidebar"}),
    capture_context=frozenset({"page"}),
) as capture:
    html = template.render(page=page)

print(capture.template_name)
# "page.html"
print(capture.blocks["content"].html)
# "<article>...</article>"
print(capture.blocks["content"].content_hash)
# "a1b2c3d4e5f67890"
print(capture.context_keys)
# {"page": <Page object>}
2Classes3Functions

Classes

Fragment 6 ▼
A single block's rendered output with semantic metadata.

A single block's rendered output with semantic metadata.

Attributes

Name Type Description
name str

Block name (e.g., "content", "sidebar")
role str

Semantic role from BlockMetadata.inferred_role (e.g., "content", "navigation", "unknown")
html str

Raw rendered HTML of this block
content_hash str

SHA256[:16] hex digest of the rendered HTML
depends_on frozenset[str]

Context paths this block reads (from BlockMetadata)
cache_scope str

Caching granularity from BlockMetadata.cache_scope ("site", "page", "none", "unknown")
RenderCapture 8 ▼
Collects fragments and context during a single render() call. Populated by compiler-injected hooks…

Collects fragments and context during a single render() call.

Populated by compiler-injected hooks when an active capture exists. Usecaptured_render() to create and activate a capture.

Attributes

Name Type Description
template_name str

Name of the rendered template
blocks dict[str, Fragment]

Block name -> Fragment mapping for captured blocks
context_keys dict[str, Any]

Snapshotted context values (top-level keys only)
_capture_blocks frozenset[str] | None —
_capture_context frozenset[str] | None —
_block_metadata dict[str, Any] | None —

Methods

changed_from 1 dict[str, tuple[Fragment… ▼
Blocks whose content_hash differs between two captures. Returns a dict mapping…
def changed_from(self, other: RenderCapture) -> dict[str, tuple[Fragment, Fragment]]

Blocks whose content_hash differs between two captures.

Returns a dict mapping block name to (old_fragment, new_fragment) for blocks present in both captures with different content.

Parameters
Name Type Description
other —

The earlier capture to compare against.
Returns
dict[str, tuple[Fragment, Fragment]] Dict of block name -> (other's fragment, self's fragment) for changed blocks.
Internal Methods 1 ▼
_record 2 ▼
Record a block's rendered output. Called by compiler-injected hooks at block c…
def _record(self, name: str, html: str) -> None

Record a block's rendered output.

Called by compiler-injected hooks at block call sites. Skips recording if the block is not in the capture set. Pulls role and depends_on from _block_metadata when available.

Parameters
Name Type Description
name —

Block name
html —

Rendered HTML output of the block

Functions

_compute_content_hash 1 str ▼
Compute content hash for a rendered block. Uses SHA256 truncated to 16 hex cha…
def _compute_content_hash(html: str) -> str

Compute content hash for a rendered block.

Uses SHA256 truncated to 16 hex chars, matching the block_hash precedent in kida.analysis.analyzer.

Parameters
Name Type Description
html str
Returns
str
get_capture 0 RenderCapture | None ▼
Get current capture (None if capture not active).
def get_capture() -> RenderCapture | None
Returns
RenderCapture | None
captured_render 2 Iterator[RenderCapture] ▼
Context manager for captured rendering. Creates a RenderCapture and makes it a…
def captured_render(capture_blocks: frozenset[str] | None = None, capture_context: frozenset[str] | None = None) -> Iterator[RenderCapture]

Context manager for captured rendering.

Creates a RenderCapture and makes it available via get_capture() for the duration of the with block. Compiler-injected hooks record block content and context snapshots into the capture.

Parameters
Name Type Description
capture_blocks frozenset[str] | None

Set of block names to capture. None captures all blocks.

Default:None
capture_context frozenset[str] | None

Set of top-level context keys to snapshot. None captures no context (explicit opt-in for context).

Default:None
Returns
Iterator[RenderCapture]