template.helpers

Sentinel for failed attribute access on objects.

• str(_Undefined()) returns ""(template output unchanged)
• bool(_Undefined()) returns False(falsy guard works)
• is_defined()recognises it as "not defined"

Get attribute with dict fallback and None-safe handling.

Resolution order:

• Dicts: subscript first (user data), getattr fallback (methods). This prevents dict method names likeitems, keys, values, getfrom shadowing user data keys.
• Objects: getattr first, subscript fallback.

None Handling (like Hugo/Go templates):

• If obj is None, returns UNDEFINED (prevents crashes)
• If attribute value is None, returns "" (normalizes output)

Not-Found Handling:

• Returns theUNDEFINEDsentinel when the attribute/key is not found.UNDEFINED stringifies as ""(so template output is unchanged) butis_defined()recognises it as not defined, fixingx.missing is defined→ False.

Complexity: O(1)

Get attribute with dict fallback, preserving None values.

Like safe_getattr but preserves None values instead of converting to empty string. Used for optional chaining (?.) so that null coalescing (??) can work correctly.

Resolution order matches safe_getattr: dicts try subscript first.

Complexity: O(1)

Like safe_getattr but raises UndefinedError on missing attributes.

Used when Environment(strict_undefined=True) to catch typos in attribute access at render time.

Concatenate for ~ operator, preserving Markup safety.

If either operand is Markup, the result is Markup and the non-Markup operand is HTML-escaped via Markup.add/radd. If neither is Markup, both are converted to plain strings.

Record filter usage for profiling, returning the result unchanged.

Called by compiled code for every filter invocation. When profiling is disabled (acc is None), the cost is a single falsy check + return.

Record macro ({% def %}) call for profiling, returning the result unchanged.

Called by compiled code for every macro invocation. When profiling is disabled (acc is None), the cost is a single falsy check + return.

Look up a variable in strict mode.

In strict mode, undefined variables raise UndefinedError instead of silently returning None. This catches typos and missing variables early, improving debugging experience.

Performance:

• Fast path (defined var): O(1) dict lookup, no imports
• Error path: Raises UndefinedError with template context

Lookup variable in scope stack (top to bottom), then ctx.

Checks scopes from innermost to outermost, then falls back to ctx. Raises UndefinedError if not found (strict mode).

Safe default filter that works with strict mode.

In strict mode, the value expression might raise UndefinedError. This helper catches that and returns the default value.

Check if a value is defined in strict mode.

In strict mode, we need to catch UndefinedError to determine if a variable is defined.

A value is considered undefined when:

• The variable doesn't exist (raises UndefinedError)
• The value isNone
• The value is the_Undefinedsentinel (failed attribute access)

This meansobj.missing_attr is definedcorrectly returns False even whenobj itself exists, because _safe_getattrreturns theUNDEFINEDsentinel for missing attributes.

Safe null coalescing that handles undefined variables.

In strict mode, the left expression might raise UndefinedError. This helper catches that and returns the right value.

Unlike the default filter:

• Returns right ONLY if left is None or undefined
• Does NOT treat falsy values (0, '', False, []) as needing replacement

Polymorphic + operator with safe string-concatenation fallback.

Goals:

• Keep natural Python behavior for compatible operand types (list + list, tuple + tuple, etc.).
• Support Jinja-style string ergonomics (count + " items").
• Avoid silently stringifying collection arithmetic, which can explode output.

Coerce value to numeric type for arithmetic operations.

Handles Markup objects (from macros) and strings that represent numbers. This prevents string multiplication when doing arithmetic with macro results.

Convert value to string, treating None as empty string.

This is used for template output so that optional chaining expressions that evaluate to None produce empty output rather than the literal string 'None'.

Preserves Markup instances (and objects with html) so that the escape function can detect them and avoid double-escaping.

RFC: kida-modern-syntax-features — needed for optional chaining.

Read a value from the nearest{% provide %}ancestor.

Template-level function that reads from the RenderContext provider stack. Returns default if no provider is active for key.

Example::

{% provide color = "red" %}
    {{ consume("color") }}  {# outputs: red #}
{% end %}

Call callee only if it is not None or UNDEFINED.

Used for obj?.method() so that when obj is None or obj.attr is UNDEFINED, the call short-circuits and returns UNDEFINED (outputs as "").