Chevron extensions¶
Chevron extensions are opt-in behaviour beyond the Mustache specification. They leave ordinary Mustache templates unchanged and are disabled by default. This chapter is the reference for choosing and configuring them; the template-language chapters explain how their syntax behaves in a template.
Enable extensions once at startup¶
Configure extensions before the application performs its first render:
The first Extension.enable() call selects the complete, process-wide extension mask and freezes it. A later call raises RuntimeError. Chevron deliberately has no per-template or per-render switch, and changing the setting while rendering is not supported. Choose the mask once during application startup, alongside other application-wide configuration.
Extension.NONE is the default. Enable more than one extension with |:
Extension.ALL enables every extension implemented by the installed Chevron version:
Use an explicit mask when an application needs a deliberately stable set of behaviours. Use ALL when adopting every extension supplied by the installed version is intended.
Enhanced iterators¶
Extension.ENHANCED_ITERATORS adds two related behaviours for Python iterators and asynchronous iterables:
- An empty streaming value selects its inverted section, as an empty list does.
- A repeated section exposes positional metadata for its current item.
Empty streaming values¶
Without the extension, an iterator object is truthy even after it has yielded its last value. With the extension, Chevron may observe one value to determine whether a stream is empty. That observed value remains available when the ordinary section renders later in the same supplying context.
With events set to iter(()), the output is:
With events set to iter(["created", "published"]), it is:
Chevron does not materialise a stream or clone it. A streaming iterator or asynchronous iterable has one traversal for a given name in its supplying context during a render. Once it is exhausted, a later ordinary section using that name has no items. Lists and tuples remain normally reusable and can be repeated in separate sections.
Positional metadata¶
Inside a repeated section, Chevron reserves leading-dot names other than {{.}} for metadata. The original item remains available as {{.}}.
For steps=["draft", "review", "publish"], this renders:
| Name | Value |
|---|---|
.first |
True for the first item. |
.last |
True for the final item when Chevron can determine it. |
.index |
Zero-based position. |
.ordinal |
One-based position. |
.length |
Source length when __len__ is available; otherwise None. |
.0, .1, … |
Values at non-negative indexes when the source supports both __len__ and __getitem__; otherwise None. |
For example, .first and .last can format a comma-separated list without a trailing comma:
With names=["Ari", "Blake", "Casey"], this produces Contributors: Ari, Blake, Casey. Metadata is scoped to the nearest repeated section. Mapping sections retain normal Mustache context behaviour: Chevron does not iterate a mapping's keys or entries to create metadata.
Conditional sections¶
Extension.CONDITIONAL_SECTIONS enables {{?name}}...{{/name}}. It tests a value and renders its body once only when the value is truthy. Unlike an ordinary section, it neither changes the active context nor repeats its body for a collection.
Given:
the output is ## 0.18.0. changes establishes whether the body renders, but it does not become the current context. {{release_name}} therefore continues to resolve from the surrounding data, and a non-empty changes collection still renders the body only once. A callable is tested as a value and is not invoked by a conditional section.
When this extension is disabled, ? remains part of an ordinary variable name. For example, {{?changes}} can interpolate a context value stored under the literal key "?changes". A paired {{?changes}}...{{/changes}} is structurally invalid until the extension is enabled; Chevron logs a warning naming Extension.CONDITIONAL_SECTIONS before raising its ordinary template error.
For an unsized iterator or asynchronous iterable, a conditional section may observe one item to establish truthiness and retains it for a later ordinary section using the identical lookup name in the same render frame. Conditional sections do not expose positional metadata; enable ENHANCED_ITERATORS separately when a repeated section needs it.
Other Chevron APIs¶
The following opt-in APIs are not extensions and do not use Extension.enable():
- Lambdas documents
chevron.func,chevron.section, andchevron.compat. - Async rendering documents
async_render()and its optional AnyIO support. render()documents filesystem-partial confinement.- The tokenizer API documents pre-parsed token streams.
For release-to-release differences from Chevron 0.14.0, see the compatibility reference.