Module

template.core

Kida Template — compiled template object ready for rendering.

The Template class wraps a compiled code object and provides therender() API. Templates are immutable and thread-safe for concurrent rendering.

Architecture:

```
Template
├── _env_ref: WeakRef[Environment]  # Prevents circular refs
├── _code: code object              # Compiled Python bytecode
├── _render_func: callable          # Extracted render() function
└── _name, _filename                # For error messages
```

StringBuilder Pattern:

Generated code usesbuf.append() + ''.join(buf): python def render(ctx, _blocks=None): buf = [] _append = buf.append _append("Hello, ") _append(_e(_s(ctx["name"]))) return ''.join(buf) This is O(n) vs O(n²) for string concatenation.

Memory Safety:

Usesweakref.ref(env)to break potential cycles: Template → (weak) → Environment → cache → Template

Thread-Safety:

  • Templates are immutable after construction
  • render()creates only local state (buf list)
  • Multiple threads can callrender()concurrently

Complexity:

  • render(): O(n) where n = output size
  • _escape(): O(n) single-pass via str.translate()
3Classes1Function

Classes

ErrorDict 4 ▼
Error context exposed to ``{% fallback name %}`` blocks.

Error context exposed to{% fallback name %}blocks.

Attributes

Name Type Description
message str —
type str —
template str | None —
line int | None —
Template 23 ▼
Compiled template ready for rendering. Wraps a compiled code object containing a ``render(ctx, _bl…

Compiled template ready for rendering.

Wraps a compiled code object containing arender(ctx, _blocks)function. Templates are immutable and thread-safe for concurrentrender()calls.

Thread-Safety:

  • Template object is immutable after construction
  • Eachrender()call creates local state only (buf list)
  • Multiple threads can render the same template simultaneously

Memory Safety: Usesweakref.ref(env)to prevent circular reference leaks: Template → (weak) → Environment → _cache → Template

Methods: render(**context): Render template with given variables render_async(**context): Async render for templates with await

Error Enhancement:

Runtime errors are caught and enhanced with template context:

    ```
    TemplateRuntimeError: 'NoneType' has no attribute 'title'
      Location: article.html:15
      Expression: {{ post.title }}
      Values:
        post = None (NoneType)
      Suggestion: Check if 'post' is defined before accessing .title
    ```

Attributes

Name Type Description
name —

Template identifier (for error messages)
filename —

Source file path (for error messages)

Methods

warnings 0 list ▼
Compile-time warnings for this template.
property
def warnings(self) -> list
Returns
list
name 0 str | None ▼
Template name.
property
def name(self) -> str | None
Returns
str | None
filename 0 str | None ▼
Source filename.
property
def filename(self) -> str | None
Returns
str | None
is_async 0 bool ▼
True if this template uses async constructs (async for / await). Part of RFC: …
property
def is_async(self) -> bool

True if this template uses async constructs (async for / await).

Part of RFC: rfc-async-rendering.

Returns
bool
render 2 str ▼
Render template with given context. Context is passed as keyword arguments. Co…
def render(self, *args: Any, **kwargs: Any) -> str

Render template with given context.

Context is passed as keyword arguments. Common keys include page, site, user— types vary by template.

User context is now CLEAN - no internal keys injected. Internal state (_template, _line, _include_depth, _cached_blocks, _cached_stats) is managed via RenderContext ContextVar.

Parameters
Name Type Description
*args —
**kwargs —
Returns
str Rendered template as string
render_block 3 str ▼
Render a single block from the template. Context is passed as keyword argument…
def render_block(self, block_name: str, *args: Any, **kwargs: Any) -> str

Render a single block from the template.

Context is passed as keyword arguments. Common keys include page, site, user— types vary by template.

Renders just the named block, useful for caching blocks that only depend on site-wide context (e.g., navigation, footer). Supports inherited blocks: descendant templates can render blocks defined only in a parent by name (e.g. render_block("sidebar") on a child that extends a base defining a sidebar block it does not override).

Parameters
Name Type Description
block_name —

Name of the block to render (e.g., "nav", "footer") *args: Single dict of context variables **kwargs: Context variables as keyword arguments
*args —
**kwargs —
Returns
str Rendered block HTML as string
render_with_blocks 3 str ▼
Render this template with pre-rendered HTML injected into blocks. Enables prog…
def render_with_blocks(self, block_overrides: dict[str, str], *args: Any, **kwargs: Any) -> str

Render this template with pre-rendered HTML injected into blocks.

Enables programmatic layout composition: render a page's content, then inject it as thecontentblock of a parent layout template, without needing{% extends %}in the template source.

Each key in block_overrides names a block; the value is a pre-rendered HTML string that replaces that block's default content.

Parameters
Name Type Description
block_overrides —

Mapping of block name → pre-rendered HTML string. *args: Single dict of context variables. **kwargs: Context variables as keyword arguments.
*args —
**kwargs —
Returns
str Rendered template as string with block overrides applied.
render_stream 2 Iterator[str] ▼
Render template as a generator of HTML chunks. Yields chunks at every statemen…
def render_stream(self, *args: Any, **kwargs: Any) -> Iterator[str]

Render template as a generator of HTML chunks.

Yields chunks at every statement boundary, enabling progressive delivery via chunked transfer encoding.

Parameters
Name Type Description
*args —
**kwargs —
Returns
Iterator[str]
list_blocks 0 list[str] ▼
List all blocks available for render_block() (including inherited).
def list_blocks(self) -> list[str]
Returns
list[str] List of block names available for render_block()
render_async 2 str ▼
Async wrapper for synchronous templates. Runs ``render()`` in a thread pool to…
async
async def render_async(self, *args: Any, **kwargs: Any) -> str

Async wrapper for synchronous templates.

Runsrender()in a thread pool to avoid blocking the event loop. Async templates (those with{% async for %} or {{ await ... }}) are not supported by this method. Userender_stream_async()for native async template rendering.

Parameters
Name Type Description
*args —
**kwargs —
Returns
str
render_stream_async 2 AsyncIterator[str] ▼
Render template as an async generator of HTML chunks. For templates with async…
async
async def render_stream_async(self, *args: Any, **kwargs: Any) -> AsyncIterator[str]

Render template as an async generator of HTML chunks.

For templates with async constructs ({% async for %}, {{ await }}), this calls the native async render function. For sync templates, it wraps the sync render_stream() in an async generator.

Parameters
Name Type Description
*args —
**kwargs —
Returns
AsyncIterator[str]
render_block_stream_async 3 AsyncIterator[str] ▼
Render a single block as an async stream. Looks up the async streaming block f…
async
async def render_block_stream_async(self, block_name: str, *args: Any, **kwargs: Any) -> AsyncIterator[str]

Render a single block as an async stream.

Looks up the async streaming block function first, falls back to the sync streaming block function wrapped in an async generator. Supports inherited blocks like render_block().

Parameters
Name Type Description
block_name —

Name of the block to render *args: Single dict of context variables **kwargs: Context variables as keyword arguments
*args —
**kwargs —
Returns
AsyncIterator[str]
Internal Methods 9 ▼
_env 0 Environment ▼
Get the Environment (dereferences weak reference).
property
def _env(self) -> Environment
Returns
Environment
__init__ 7 ▼
Initialize template with compiled code.
def __init__(self, env: Environment, code: types.CodeType, name: str | None, filename: str | None, optimized_ast: TemplateNode | None = None, source: str | None = None, precomputed: list[Any] | None = None)
Parameters
Name Type Description
env —

Parent Environment (stored as weak reference)
code —

Compiled Python code object
name —

Template name (for error messages)
filename —

Source filename (for error messages)
optimized_ast —

Optional preserved AST for introspection. If None, introspection methods return empty results.

Default:None
source —

Template source for runtime error snippets. Stored for use by enhance_template_error() to provide source context in TemplateRuntimeError exceptions.

Default:None
precomputed —

Values that the partial evaluator folded but that cannot be stored inast.Constant nodes (dict, list, etc.). Injected into the exec namespace as _pc_0, _pc_1, ...

Default:None
_get_env_limits 0 tuple[int, int] ▼
Get max_extends_depth and max_include_depth from Environment (or defaults).
def _get_env_limits(self) -> tuple[int, int]
Returns
tuple[int, int]
_get_max_output_size 0 int | None ▼
Get max_output_size from sandbox policy, if any.
def _get_max_output_size(self) -> int | None
Returns
int | None
_check_output_size 1 str ▼
Enforce max_output_size if sandbox policy sets one.
def _check_output_size(self, output: str) -> str
Parameters
Name Type Description
output —
Returns
str
_build_context 3 dict[str, Any] ▼
Build render context from args and kwargs. Shared by render, render_block, ren…
def _build_context(self, args: tuple[Any, ...], kwargs: dict[str, Any], method_name: str) -> dict[str, Any]

Build render context from args and kwargs.

Shared by render, render_block, render_with_blocks, render_stream, render_stream_async, render_block_stream_async.

Parameters
Name Type Description
args —
kwargs —
method_name —
Returns
dict[str, Any]
_run_globals_setup_chain 1 ▼
Apply ``_globals_setup`` along the ``{% extends %}`` chain. ``_inheritance_cha…
def _run_globals_setup_chain(self, ctx: dict[str, Any]) -> None

Apply_globals_setup along the {% extends %}chain.

_inheritance_chain() is [leaf, parent, …, root]. Full render() runs each template's top-level statements (imports, defs,{% let %}, …) before calling_extends, so effective order is leaf → root; later templates win onctxname clashes, matching full-page render.

render_block / render_with_blocksmust mirror that order so fragment scope matches a full page render for HTMX partials.

Parameters
Name Type Description
ctx —
_render_scaffold 5 Iterator[tuple[dict[str,… ▼
Common setup for sync render methods. Builds context, sets up RenderContext, p…
def _render_scaffold(self, args: tuple[Any, ...], kwargs: dict[str, Any], method_name: str, *, use_cached_blocks: bool = False, enhance_errors: bool = True) -> Iterator[tuple[dict[str, Any], Any, Any]]

Common setup for sync render methods.

Builds context, sets up RenderContext, prepares blocks arg, and optionally enhances exceptions.

Parameters
Name Type Description
args —
kwargs —
method_name —
use_cached_blocks — Default:False
enhance_errors — Default:True
Returns
Iterator[tuple[dict[str, Any], Any, Any]]
__repr__ 0 str ▼
def __repr__(self) -> str
Returns
str
RenderedTemplate 3 ▼
Lazy rendered template with streaming support. Wraps a Template + context pair. Supports both full…

Lazy rendered template with streaming support.

Wraps a Template + context pair. Supports both full rendering viastr() and chunk-by-chunk iteration via for chunk in rt.

Methods

Internal Methods 3 ▼
__init__ 2 ▼
def __init__(self, template: Template, context: dict[str, Any])
Parameters
Name Type Description
template —
context —
__str__ 0 str ▼
Render and return full string.
def __str__(self) -> str
Returns
str
__iter__ 0 ▼
Iterate over rendered HTML chunks via render_stream().
def __iter__(self)

Functions

_make_error_dict 1 ErrorDict ▼
Build error dict for {% try %}...{% fallback name %} error binding.
def _make_error_dict(exc: BaseException) -> ErrorDict
Parameters
Name Type Description
exc BaseException
Returns
ErrorDict