Compatibility¶
This page records deliberate public differences from Chevron 0.14.0. It is a concise migration index, not a replacement for the linked feature documentation.
Compatibility callouts¶
| Area | Difference from 0.14.0 | Reason and further reading |
|---|---|---|
| Filesystem partials | Library rendering now defaults to partials_path=None; filesystem lookup is disabled until an application supplies a trusted directory. The CLI retains its current-directory default. |
Avoid accidental access to files relative to the process working directory. See partials and layouts and render(). |
| Falsey values | _CHEVRON_return_scope_when_falsy is no longer read or honoured. |
It was an undocumented private escape hatch that made falsey rendering depend on application object internals. Transform data before rendering instead. |
| Lambda policy | lambdas= enables an explicit callable allow-list. @chevron.func, @chevron.section, and @chevron.compat declare interpolation, standard-section, and compatibility protocols. Omitting lambdas retains legacy callable template-data behaviour. |
Makes the application boundary and callback intent visible. See lambdas. |
| Async rendering | async_render() adds support for declared async lambdas, async readers, and async iterables inside a caller-owned AnyIO runtime. Synchronous render() rejects awaitable reader or lambda results and async iterable section values. |
A synchronous API cannot await those values. See async_render() and render(). |
| Enhanced iterators | Extension.ENHANCED_ITERATORS optionally makes empty iterators and async iterables select their inverted sections, and exposes section iteration metadata. When enabled, a streaming value is traversed once per name in its supplying context during a render. |
This is a non-standard extension that permits useful empty-generator behaviour and positional formatting without materialising a stream. See sections. |
| Conditional sections | Extension.CONDITIONAL_SECTIONS optionally enables {{?name}}...{{/name}}, which tests a value without changing scope or repeating its body. Without it, ? remains part of an ordinary variable name. |
This non-standard syntax lets templates guard larger fragments while retaining their surrounding context. See conditional sections. |
| Extension configuration | Optional extensions are process-wide and disabled by default. Configure them once during application startup with Extension.enable(); the selected mask is then frozen. |
Keeps template and render-call APIs stable. See Chevron extensions. |
| Dynamic and inheritance syntax | *, <, and $ are now reserved tag prefixes for dynamic partial or parent names, parents, and named blocks. Literal partial names beginning with *, and interpolation names beginning with < or $, are no longer available in those tag forms. |
Required for current Mustache dynamic-name and inheritance support. See partials and layouts. |
| Scope handling | Chevron no longer structurally mutates a caller-provided scopes sequence while rendering. |
Nested rendering now has private frame state, preventing caller-visible scope-stack mutation. See render(). |
| Tokenizer input | chevron.tokenizer.tokenize() accepts template source text only; file-like input belongs to render() or async_render(). |
Keeps tokenisation synchronous and makes input I/O a renderer concern. See the tokenizer API. |
| Deep expansion | Engine-owned nested partial, iterable-section, and lambda-result expansion is iterative and bounded; a cyclic expansion raises RecursionError rather than exhausting the Python call stack. |
Provides predictable safety for deeply nested or cyclic templates. Application-initiated compatibility callback recursion remains application-owned. See async_render(). |
Migration notes¶
The filesystem and explicit-lambda changes are the most important security-related migrations. Use partials_dict for an in-memory allow-list, pass an explicit trusted partials_path only when filesystem partials are required, and provide lambdas={} when callable tags are not allowed.
Enhanced iterator behaviour is disabled unless an application enables Extension.ENHANCED_ITERATORS. Leaving it disabled preserves Chevron's earlier iterator truthiness behaviour. When enabled, supply independently constructed iterators under separate names if a template needs more than one traversal of the same underlying collection.
The Mustache language target itself is the pinned upstream Mustache manual. The additions and restrictions above describe Chevron-specific API and compatibility behaviour.