# render_helpers

URL: /kida/api/template/render_helpers/
Section: template
Description: 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.

---

> For a complete page index, fetch /kida/llms.txt.

Open LLM text
(/kida/api/template/render_helpers/index.txt)

Share with AI

Ask Claude
(https://claude.ai/new?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Ftemplate%2Frender_helpers%2Findex.txt)

Ask ChatGPT
(https://chatgpt.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Ftemplate%2Frender_helpers%2Findex.txt)

Ask Gemini
(https://gemini.google.com/app?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Ftemplate%2Frender_helpers%2Findex.txt)

Ask Copilot
(https://copilot.microsoft.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Ftemplate%2Frender_helpers%2Findex.txt)

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]`