Module

template.render_helpers

Render helper factories for Template namespace.

Extracted from core.py to reduce Template.init size and improve testability. Each factory takes env_ref and returns a closure used by compiled template code.

1Class4Functions

Classes

MacroWrapper 9 ▼
Callable wrapper for imported macros with source attribution metadata. Used for error attribution:…

Callable wrapper for imported macros with source attribution metadata.

Used for error attribution: template_stack, template_name, and source are set on render_ctx before calling the macro. The kida_source* attributes are available for future error enhancement (e.g. source snippets).

Injects _defining_namespace as _outer_ctx so macros see their defining template's namespace (e.g. tag_list when article_card calls it).

Attributes

Name Type Description
_fn Callable[..., object] —
_defining_namespace dict[str, Any] —
_kida_source_template str —
_kida_source_file str | None —
_source str | None —
_kida_macro_name str | None —
_needs_outer_ctx bool —

Methods

Internal Methods 2 ▼
__call__ 2 object ▼
def __call__(self, *args: object, **kwargs: object) -> object
Parameters
Name Type Description
*args —
**kwargs —
Returns
object
__iter__ 0 Iterator[object] ▼
Raise helpful error when a macro is used in a for loop. This commonly happens …
def __iter__(self) -> Iterator[object]

Raise helpful error when a macro is used in a for loop.

This commonly happens when a macro and context variable share the same name (e.g. route_tabs). The macro shadows the variable, so {% for x in route_tabs %} iterates over the macro instead of the intended list.

Returns
Iterator[object]

Functions

_coerce_ttl_seconds 1 float | None ▼
Convert template ttl argument to seconds. Supports numeric values (seconds) an…
def _coerce_ttl_seconds(ttl: object) -> float | None

Convert template ttl argument to seconds.

Supports numeric values (seconds) and compact duration strings:

  • "30" / "30s" -> 30
  • "5m" -> 300
  • "2h" -> 7200
  • "1d" -> 86400

Returns None for invalid values, negative values, or when ttl is None.

Parameters
Name Type Description
ttl object
Returns
float | None
_wrap_blocks_if_cached 2 dict[str, Any] | CachedB… ▼
Wrap blocks with CachedBlocksDict if render context has cached blocks.
def _wrap_blocks_if_cached(blocks: BlocksDict | dict[str, Any], render_ctx: RenderContext) -> dict[str, Any] | CachedBlocksDict
Parameters
Name Type Description
blocks BlocksDict | dict[str, Any]
render_ctx RenderContext
Returns
dict[str, Any] | CachedBlocksDict
_make_macro_wrapper 6 MacroWrapper ▼
Wrap imported macro to push/pop template_stack for error attribution.
def _make_macro_wrapper(macro_fn: Callable[..., object], source_template: str, source_file: str | None, source: str | None = None, macro_name: str | None = None, defining_namespace: dict[str, Any] | None = None) -> MacroWrapper
Parameters
Name Type Description
macro_fn Callable[..., object]
source_template str
source_file str | None
source str | None Default:None
macro_name str | None Default:None
defining_namespace dict[str, Any] | None Default:None
Returns
MacroWrapper
make_render_helpers 1 dict[str, Any] ▼
Create all render helpers for a Template namespace.
def make_render_helpers(env_ref: Callable[[], Environment | None]) -> dict[str, Any]
Parameters
Name Type Description
env_ref Callable[[], Environment | None]

WeakRef to Environment (callable returning Environment or None)
Returns
dict[str, Any]