Module

compiler.stream_transform

Block render-mode planning and sync-to-stream Python AST transformation.

Transforms compiled sync block stmts (_append calls) into streaming stmts (yield expressions). This eliminates a redundant full Kida AST compilation per block by deriving the stream variant from the sync compilation output.

The immutable plan selects direct compilation or transformation for each streaming variant. The transform replaces: _append(expr) → yield expr return ''.join(buf) → (removed)

The transformed block builders preserve preamble/cache ordering and append the return/generator sentinel required by the runtime dispatch contract.

Uses copy-on-write: only nodes on the path to_appendcall sites are copied. Unchanged subtrees are shared with the original AST, making this safe to call multiple times on the same input (e.g. for stream + async stream variants).

4Classes6Functions

Classes

BlockLoweringStrategy 0 ▼
How one streaming block variant is produced.

How one streaming block variant is produced.

BlockRenderModePlan 2 ▼
Lowering strategies for the stream and async-stream block variants.

Lowering strategies for the stream and async-stream block variants.

Attributes

Name Type Description
stream BlockLoweringStrategy —
async_stream BlockLoweringStrategy —
BlockFunctionVariants 3 ▼
The sync, stream, and async-stream functions lowered for one block.

The sync, stream, and async-stream functions lowered for one block.

Attributes

Name Type Description
sync ast.FunctionDef —
stream ast.FunctionDef —
async_stream ast.AsyncFunctionDef —
_AppendToYield 2 ▼
Replace ``_append(expr)`` with ``yield expr`` in Python AST. Overrides ``generic_visit`` with a co…

Replace_append(expr) with yield exprin Python AST.

Overridesgeneric_visitwith a copy-on-write strategy: only nodes whose children actually changed are shallow-copied. Unchanged subtrees are returned as-is (identity), so the original AST is never mutated.

Methods

visit_Expr 1 ast.Expr ▼
Transform _append(x) expression statements to yield x.
def visit_Expr(self, node: ast.Expr) -> ast.Expr
Parameters
Name Type Description
node —
Returns
ast.Expr
generic_visit 1 ast.AST ▼
Copy-on-write: only copy nodes whose children changed.
def generic_visit(self, node: ast.AST) -> ast.AST
Parameters
Name Type Description
node —
Returns
ast.AST

Functions

plan_block_render_modes 4 BlockRenderModePlan ▼
Choose direct compilation or sync-AST transformation for each variant.
def plan_block_render_modes(*, is_region: bool, rebinds_append: bool, template_has_regions: bool, template_has_async: bool) -> BlockRenderModePlan
Parameters
Name Type Description
is_region bool
rebinds_append bool
template_has_regions bool
template_has_async bool
Returns
BlockRenderModePlan
sync_body_to_stream 1 list[ast.stmt] ▼
Transform compiled sync body statements into streaming equivalents. Walks the …
def sync_body_to_stream(stmts: list[ast.stmt]) -> list[ast.stmt]

Transform compiled sync body statements into streaming equivalents.

Walks the AST and replaces_append(expr) calls with yield expr. Uses copy-on-write so the original stmts are never modified — safe to call repeatedly on the same input.

Parameters
Name Type Description
stmts list[ast.stmt]

Compiled Python AST statements from sync block compilation.
Returns
list[ast.stmt]
_build_transformed_block_body 3 list[ast.stmt] ▼
Assemble one transformed block body in runtime contract order.
def _build_transformed_block_body(*, preamble: list[ast.stmt], cache_assignments: list[ast.stmt], compiled_stmts: list[ast.stmt]) -> list[ast.stmt]
Parameters
Name Type Description
preamble list[ast.stmt]
cache_assignments list[ast.stmt]
compiled_stmts list[ast.stmt]
Returns
list[ast.stmt]
_block_arguments 0 ast.arguments ▼
Build the shared ``(ctx, _blocks)`` block function signature.
def _block_arguments() -> ast.arguments
Returns
ast.arguments
build_stream_block_function 4 ast.FunctionDef ▼
Build a sync generator block from compiled StringBuilder statements.
def build_stream_block_function(name: str, *, preamble: list[ast.stmt], cache_assignments: list[ast.stmt], compiled_stmts: list[ast.stmt]) -> ast.FunctionDef
Parameters
Name Type Description
name str
preamble list[ast.stmt]
cache_assignments list[ast.stmt]
compiled_stmts list[ast.stmt]
Returns
ast.FunctionDef
build_async_stream_block_function 4 ast.AsyncFunctionDef ▼
Build an async generator block from compiled StringBuilder statements.
def build_async_stream_block_function(name: str, *, preamble: list[ast.stmt], cache_assignments: list[ast.stmt], compiled_stmts: list[ast.stmt]) -> ast.AsyncFunctionDef
Parameters
Name Type Description
name str
preamble list[ast.stmt]
cache_assignments list[ast.stmt]
compiled_stmts list[ast.stmt]
Returns
ast.AsyncFunctionDef