Module

compiler.statements.special_blocks

Special block statement compilation for Kida compiler.

Provides mixin for compiling special block statements (raw, capture, spaceless, embed).

With-blocks are in with_blocks.py; cache/filter_block are in caching.py. Uses inline TYPE_CHECKING declarations for host attributes. See: plan/rfc-mixin-protocol-typing.md

1Class

Classes

SpecialBlockMixin 8 ▼
Mixin for compiling special block statements. Host attributes and cross-mixin dependencies are dec…

Mixin for compiling special block statements.

Host attributes and cross-mixin dependencies are declared via inline TYPE_CHECKING blocks.

Methods

Internal Methods 8 ▼
_compile_flush 1 list[ast.stmt] ▼
Compile {% flush %} — streaming flush boundary. In streaming mode: yield "" to…
def _compile_flush(self, node: Flush) -> list[ast.stmt]

Compile {% flush %} — streaming flush boundary.

In streaming mode: yield "" to create a chunk boundary. In non-streaming mode: no-op.

Parameters
Name Type Description
node —
Returns
list[ast.stmt]
_compile_raw 1 list[ast.stmt] ▼
Compile {% raw %}...{% endraw %. Raw block content is output as literal text.
def _compile_raw(self, node: Raw) -> list[ast.stmt]

Compile {% raw %}...{% endraw %.

Raw block content is output as literal text.

Parameters
Name Type Description
node —
Returns
list[ast.stmt]
_compile_capture 1 list[ast.stmt] ▼
Compile {% capture x %}...{% end %} (Kida) or {% set x %}...{% endset %} (Jinja…
def _compile_capture(self, node: Capture) -> list[ast.stmt]

Compile {% capture x %}...{% end %} (Kida) or {% set x %}...{% endset %} (Jinja).

Captures rendered block content into a variable. In streaming mode, body is compiled in StringBuilder mode (captures into a buffer, not the output stream), then result is assigned to ctx.

Parameters
Name Type Description
node —
Returns
list[ast.stmt]
_compile_spaceless 1 list[ast.stmt] ▼
Compile {% spaceless %}...{% end %}. Removes whitespace between HTML tags. In …
def _compile_spaceless(self, node: Spaceless) -> list[ast.stmt]

Compile {% spaceless %}...{% end %}.

Removes whitespace between HTML tags. In streaming mode: collect into buffer, transform, yield result.

Parameters
Name Type Description
node —
Returns
list[ast.stmt]
_compile_push 1 list[ast.stmt] ▼
Compile {% push "name" %}...{% end %}. Captures body content into a buffer, th…
def _compile_push(self, node: Push) -> list[ast.stmt]

Compile {% push "name" %}...{% end %}.

Captures body content into a buffer, then appends the result to the named stack on the RenderContext.

Generates:

_push_buf_N = []
_push_append_N = _push_buf_N.append
<save/redirect _append>
<body>
<restore _append>
_rc._stacks.setdefault("name", []).append("".join(_push_buf_N))
Parameters
Name Type Description
node —
Returns
list[ast.stmt]
_compile_stack 1 list[ast.stmt] ▼
Compile {% stack "name" %}. Emits all content pushed to the named stack. Gene…
def _compile_stack(self, node: Stack) -> list[ast.stmt]

Compile {% stack "name" %}.

Emits all content pushed to the named stack.

Generates:

for _stack_item_N in _rc._stacks.get("name", ()):
    _append(_stack_item_N)
Parameters
Name Type Description
node —
Returns
list[ast.stmt]
_compile_provide 1 list[ast.stmt] ▼
Compile {% provide key = expr %}...{% endprovide %}. Pushes a value onto the R…
def _compile_provide(self, node: Provide) -> list[ast.stmt]

Compile {% provide key = expr %}...{% endprovide %}.

Pushes a value onto the RenderContext provider stack, compiles the body, then pops in a finally block to guarantee cleanup.

Generates:

_rc.provide("key", <value>)
try:
    <body>
finally:
    _rc.unprovide("key")
Parameters
Name Type Description
node —
Returns
list[ast.stmt]
_compile_embed 1 list[ast.stmt] ▼
Compile {% embed 'template.html' %}...{% end %}. Embed is like include but all…
def _compile_embed(self, node: Embed) -> list[ast.stmt]

Compile {% embed 'template.html' %}...{% end %}.

Embed is like include but allows block overrides. Part of RFC: kida-modern-syntax-features.

Generates:

_saved_blocks_N = _blocks.copy()
def _block_name(ctx, _blocks): ...  # For each override
_blocks['name'] = _block_name
_append(_include(template, ctx, _blocks))
_blocks = _saved_blocks_N
Parameters
Name Type Description
node —
Returns
list[ast.stmt]