compiler.core

Return literal extends target if template uses {% extends "literal" %}, else None.

Recursively walk the AST and reject {% def %} / {% region %} nested inside any control-flow construct.

parent_chaincarries the human-readable tag names of enclosing scoped parents (e.g.("for", "if")). When a Def or Region is reached and the chain is non-empty, raisesTemplateSyntaxError with codeK-TPL-004.

Other container nodes (Block, CallBlock, Embed, Def, Region, ...) are traversed but do not contribute to the chain — defining nested helpers inside them is a supported pattern.

Generate output statement: yield (streaming) or _append (StringBuilder).

All output generation in compiled templates flows through this method, allowing the compiler to switch between StringBuilder and generator modes.

Generate Python module from template.

Produces both StringBuilder functions (render, block) and generator functions (render_stream, block_stream) in a single module. The StringBuilder path is used by Template.render() and the generator path by Template.render_stream().

When async constructs are detected (AsyncFor, Await), also generates async generator functions (render_stream_async, block*_stream_async).

Generate _globals_setup(ctx) from {% globals %}, {% imports %}, and top-level imports.

Scans the template body for:

1. Top-level FromImport and Import nodes (so render_block has macros in scope)
2. Globals and Imports nodes (macros/variables for block context)

This function is called by render_block() to inject macros and variables into the block's context. Returns None if neither globals nor top-level imports exist.

Common setup stmts for block functions.

Non-streaming adds buf and _append for StringBuilder.

Build param_names and keywords for region block delegation.

Returns (param_names, keywords) where keywords includes both the per-param entries and the trailing _outer_ctx / _blocks keywords.

Combined CSE analysis: returns cacheable variable names.

Performs the fast unconditional-expression guard check followed by the full variable reference collection in a single call, deduplicating the pattern used across _make_block_function and _make_render_direct_body.

Generate a block function: _block_name(ctx, _blocks) -> str.

Also stores the raw compiled stmts in_last_block_compiled_stmts so the stream variant can be derived without recompiling the Kida AST.

Generate the render(ctx, _blocks=None) function.

Optimization: Cache global function references as locals for O(1) LOAD_FAST instead of O(1) LOAD_GLOBAL + hash lookup.

For templates with extends:

def render(ctx, _blocks=None):
    if _blocks is None: _blocks = {}
    # Register child blocks
    _blocks.setdefault('name', _block_name)
    # Render parent with blocks
    return _extends('parent.html', ctx, _blocks)

Generate a streaming block: _block_name_stream(ctx, _blocks) -> Generator[str].

Generate render_stream(ctx, _blocks=None) generator function.

For templates with extends:

yield from _extends_stream('parent.html', ctx, _blocks)

For templates without extends:

yield chunks directly

Generate async streaming block: _block_name_stream_async(ctx, _blocks).

Mirrors _make_block_function_stream() but produces an async generator function (async def + yield). Used when the template contains async constructs (AsyncFor, Await).

Part of RFC: rfc-async-rendering.

Generate async render_stream_async(ctx, _blocks=None) function.

Mirrors _make_render_function_stream() but produces an async generator for native async iteration over AsyncFor loops and Await expressions.

For templates with extends:

async for chunk in _extends_stream_async(parent, ctx, _blocks):
    yield chunk

For templates without extends:

yield chunks directly via async generator

Part of RFC: rfc-async-rendering.

Compile a single AST node to Python statements.

Complexity: O(1) type dispatch using class name lookup.

For nodes that can cause runtime errors, injects a line marker statement (ctx['_line'] = N) before the node's code. This enables rich error messages with source line numbers.