Module

render_context

Kida RenderContext — per-render state isolated from user context.

This module implements ContextVar-based render state management, replacing the internal keys (_template, _line, _include_depth, _cached_blocks, _cached_stats) that were previously injected into the user's ctx dict.

Benefits:

  • Clean user context (no internal key pollution)
  • No key collision risk (user can use _template as variable)
  • Centralized state management
  • Thread-safe via ContextVar
  • Async-safe (ContextVars propagate to asyncio.to_thread in Python 3.14)

RFC: kida-contextvar-patterns

1Class6Functions

Classes

RenderContext 16 ▼
Per-render state isolated from user context. Replaces the _template, _line, _include_depth, _cache…

Per-render state isolated from user context.

Replaces the _template, _line, _include_depth, _cached_blocks, and _cached_stats keys that were previously injected into the user's ctx dict.

Thread Safety: ContextVars are thread-local by design. Each thread/async task has its own RenderContext instance.

Async Safety: ContextVars propagate correctly to asyncio.to_thread() in Python 3.14, so render_async() works without special handling.

Attributes

Name Type Description
template_name str | None

Current template name for error messages
filename str | None

Source file path for error messages
source str | None —
line int

Current line number (updated during render by generated code)
include_depth int

Current include/embed depth (DoS protection)
max_include_depth int

Maximum allowed include depth
template_stack list[tuple[str, int]]

Stack of (template_name, line) for error traces
cached_blocks dict[str, str]

Site-scoped block cache (shared across includes)
cached_block_names frozenset[str]

Frozenset of cached block names for O(1) lookup
cache_stats dict[str, int] | None

Optional dict for cache hit/miss tracking
import_stack list[str] —
_meta dict[str, object] —

Methods

get_meta 2 object ▼
Get framework-specific metadata. Used by frameworks (like Chirp) to pass reque…
def get_meta(self, key: str, default: object = None) -> object

Get framework-specific metadata.

Used by frameworks (like Chirp) to pass request context into templates.

Commonly used for:

  • HTMX headers: hx_request, hx_target, hx_trigger, hx_boosted
  • Security: csrf_token
  • User context: current_user, permissions
Parameters
Name Type Description
key —

Metadata key
default —

Value to return if key not found

Default:None
Returns
object Metadata value or default
set_meta 2 ▼
Set framework-specific metadata.
def set_meta(self, key: str, value: object) -> None
Parameters
Name Type Description
key —

Metadata key
value —

Metadata value
check_include_depth 1 ▼
Check if include depth limit exceeded.
def check_include_depth(self, template_name: str) -> None
Parameters
Name Type Description
template_name —

Name of template being included
child_context 1 RenderContext ▼
Create child context for include/embed with incremented depth. Shares cached_b…
def child_context(self, template_name: str | None = None) -> RenderContext

Create child context for include/embed with incremented depth.

Shares cached_blocks, cache_stats, and _meta with parent (they're document-wide). Appends current location to template_stack for error traces.

Parameters
Name Type Description
template_name —

Optional override for child template name

Default:None
Returns
RenderContext New RenderContext with incremented include_depth and updated stack

Functions

get_render_context 0 RenderContext | None ▼
Get current render context (None if not in render).
def get_render_context() -> RenderContext | None
Returns
RenderContext | None
get_render_context_required 0 RenderContext ▼
Get current render context, raise if not in render. Used by generated code for…
def get_render_context_required() -> RenderContext

Get current render context, raise if not in render.

Used by generated code for line tracking.

Returns
RenderContext
render_context 6 Iterator[RenderContext] ▼
Context manager for render-scoped state. Creates a new RenderContext and sets …
def render_context(template_name: str | None = None, filename: str | None = None, source: str | None = None, cached_blocks: dict[str, str] | None = None, cache_stats: dict[str, int] | None = None, parent_meta: dict[str, object] | None = None) -> Iterator[RenderContext]

Context manager for render-scoped state.

Creates a new RenderContext and sets it as the current context for the duration of the with block. Automatically restores the previous context when exiting.

Parameters
Name Type Description
template_name str | None

Template name for error messages

Default:None
filename str | None

Source file path for error messages

Default:None
source str | None

Template source for runtime error snippets

Default:None
cached_blocks dict[str, str] | None

Site-scoped block cache

Default:None
cache_stats dict[str, int] | None

Optional dict for cache hit/miss tracking

Default:None
parent_meta dict[str, object] | None

Metadata from parent context to inherit (for framework integration)

Default:None
Returns
Iterator[RenderContext]
async_render_context 6 AsyncIterator[RenderCont… ▼
Async context manager for render-scoped state. Identical to render_context() b…
async
async def async_render_context(template_name: str | None = None, filename: str | None = None, source: str | None = None, cached_blocks: dict[str, str] | None = None, cache_stats: dict[str, int] | None = None, parent_meta: dict[str, object] | None = None) -> AsyncIterator[RenderContext]

Async context manager for render-scoped state.

Identical to render_context() but for use withasync with. ContextVar reset is synchronous — the async wrapper is structural only.

Part of RFC: rfc-async-rendering.

Parameters
Name Type Description
template_name str | None

Template name for error messages

Default:None
filename str | None

Source file path for error messages

Default:None
source str | None

Template source for runtime error snippets

Default:None
cached_blocks dict[str, str] | None

Site-scoped block cache

Default:None
cache_stats dict[str, int] | None

Optional dict for cache hit/miss tracking

Default:None
parent_meta dict[str, object] | None

Metadata from parent context to inherit (for framework integration)

Default:None
Returns
AsyncIterator[RenderContext]
set_render_context 1 Token[RenderContext | No… ▼
Set a RenderContext and return the reset token. Low-level function for cases w…
def set_render_context(ctx: RenderContext) -> Token[RenderContext | None]

Set a RenderContext and return the reset token.

Low-level function for cases where the context manager isn't suitable (e.g., nested include/embed calls that need to restore context manually).

Parameters
Name Type Description
ctx RenderContext

The RenderContext to set
Returns
Token[RenderContext | None]
reset_render_context 1 None ▼
Reset render context using a token from set_render_context.
def reset_render_context(token: Token[RenderContext | None]) -> None
Parameters
Name Type Description
token Token[RenderContext | None]

Token returned from set_render_context()