A Python implementation of the Mustache templating language.
This is a direct fork of the now-unmaintained noahmorrison/chevron. It builds on that implementation, modernising the project, closing potential security gaps around template extensions, and bringing Mustache compliance up to date.
Future work includes asynchronous rendering and asynchronous partial handling.
Why chevron?
I'm glad you asked!
chevron is fast
Chevron runs in less than half the time of pystache (Which is not even up to date on the spec). And in about 70% the time of Stache (A 'trimmed' version of mustache, also not spec compliant).
chevron is spec compliant
Chevron includes a pinned copy of the Mustache specification fixtures, including lambda cases. See the fixture attribution README.
If you find a test that Chevron does not pass, please report it.
chevron supports modern Python
Chevron requires Python 3.11 or later.
Development and verification
Install the development environment with uv sync --dev, then run uv run pytest. Chevron's own behavioural tests are separate from the vendored Mustache specification fixtures, which are retained unchanged as the deterministic conformance suite. Bounded Hypothesis properties complement those examples by exercising renderer and tokenizer invariants over generated input.
USAGE
Commandline usage: (if installed via pypi)
usage: chevron [-h] [-v] [-d DATA] [-p PARTIALS_PATH] [-e PARTIALS_EXT]
[-l DEF_LDEL] [-r DEF_RDEL]
template
positional arguments:
template The mustache file
optional arguments:
-h, --help show this help message and exit
-v, --version show program's version number and exit
-d DATA, --data DATA The json data file
-p PARTIALS_PATH, --path PARTIALS_PATH
The directory where your partials reside
-e PARTIALS_EXT, --ext PARTIALS_EXT
The extension for your mustache partials, 'mustache'
by default
-l DEF_LDEL, --left-delimiter DEF_LDEL
The default left delimiter, "{{" by default.
-r DEF_RDEL, --right-delimiter DEF_RDEL
The default right delimiter, "}}" by default.
Python usage with strings
import chevron
chevron.render("Hello, {{ mustache }}!", {"mustache": "World"})
Python usage with file
import chevron
with open("file.mustache", "r") as f:
chevron.render(f, {"mustache": "World"})
Python usage with unpacking
import chevron
args = {"template": "Hello, {{ mustache }}!", "data": {"mustache": "World"}}
chevron.render(**args)
chevron supports partials (via dictionaries)
import chevron
args = {"template": "Hello, {{> thing }}!", "partials_dict": {"thing": "World"}}
chevron.render(**args)
chevron supports partials (via the filesystem)
import chevron
args = {
"template": "Hello, {{> thing }}!",
# filesystem lookup is enabled only when this path is supplied
"partials_path": "partials/",
# defaults to mustache
"partials_ext": "ms",
}
# ./partials/thing.ms will be read and rendered
chevron.render(**args)
chevron supports lambdas
For new code, use the lambdas= mapping to declare the callable protocol for each render. Registered names are resolved before template data, and template-data callables are rejected in explicit mode. This keeps executable extensions separate from the data exposed to a template. This is the recommended mode for untrusted templates, although it is not a general template sandbox.
Use @chevron.func for a zero-argument interpolation lambda. Chevron renders its returned text with the render's configured default delimiters, then applies the escaping requested by the interpolation tag. The decorator is required for this new protocol whether the callable is supplied through lambdas= or ordinary compatibility-mode template data.
import chevron
@chevron.func
def greeting():
return "{{name}}"
chevron.render("Hello, {{greeting}}!", {"name": "Ada"}, lambdas={"greeting": greeting})
Use @chevron.section for a Mustache-standard one-argument section lambda. It receives the unprocessed text between its section tags and Chevron recursively renders its return value using the delimiters active when that section opens. The decorator is required for this new protocol in both explicit and compatibility modes.
import chevron
@chevron.section
def repeat(text):
return text + text
chevron.render(
"{{#repeat}}{{name}}{{/repeat}}", {"name": "Ada"}, lambdas={"repeat": repeat}
)
Use @chevron.compat for Chevron’s original two-argument section callback. It receives the historical compatibility text and a render() callback which can render it with optional temporary data. That helper starts with the render's configured default delimiters. Undecorated section callbacks continue to use this protocol, but the decorator makes compatibility usage explicit and easy to find.
import chevron
@chevron.compat
def select_first(text, render):
return render(text).split(" || ", 1)[0]
chevron.render(
"{{#select_first}}{{first}} || {{second}}{{/select_first}}",
{"first": "one", "second": "two"},
lambdas={"select_first": select_first},
)
Pass lambdas={} to configure no callable section tags explicitly. In explicit mode, callable values in template data are rejected and render as empty values; with warn=True, Chevron writes a diagnostic (currently to standard error). A lambda which returns None also renders as an empty value and emits that diagnostic when warnings are enabled. Callable values are also lookup leaves, so a template cannot traverse their attributes.
This is intentional for all callable values, including callable instances and classes. For example, {{build.version}} does not traverse a callable build in explicit mode. Expose only the needed plain data through an authorised section lambda instead:
def build(text, render):
return render(text, {"version": Build.version})
chevron.render(
"{{#build}}{{version}}{{/build}}",
{},
lambdas={"build": build},
)
Omitting lambdas (or passing None) retains Chevron's permissive compatibility mode so existing two-argument section callbacks keep working. In this mode, callable values resolved through normal mapping or sequence lookup may execute, including after a non-callable object attribute. A callable obtained directly from an object attribute is still not invoked. Undecorated interpolation callables keep their historic stringification behaviour; use @chevron.func to invoke one.
For untrusted templates, always provide an explicit lambdas mapping, even if it is empty. This controls callable section execution only; it is not a general template sandbox. Keep secrets and rich objects out of template data, supply only plain values where possible.
Library renders now disable filesystem partial lookup by default. Use vetted partial source in partials_dict, or opt in to a trusted filesystem directory:
chevron.render(template, data, partials_path="/srv/app/partials")
Use partials_path="." only when restoring the historic process-current-
directory lookup intentionally, but this can potentially leak server data if poorly crafted or untrusted templates are rendered.
TODO
- get popular
- have people complain
- fix those complaints
Metadata
Release files for chevron-ng 0.15.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| chevron_ng-0.15.0.tar.gz | 15.4 kB | Without provenance | Details for chevron_ng-0.15.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| chevron_ng-0.15.0-py3-none-any.whl | Python 3 | none | any | Details for chevron_ng-0.15.0-py3-none-any.whl |
Total release size: 32.2 kB
Release files / chevron_ng-0.15.0.tar.gz
| Download URL | chevron_ng-0.15.0.tar.gz |
|---|---|
| Size | 15.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
def59c49ba048cd439a0c9a85b74e97510bc0f9fae008f2783b1d29b61358b65
|
|
BLAKE2b-256 checksum How to use checksums |
6c8802b25ab7091d29f5489cfb0e48d21dcf079236dcc6a305116c13e8b85c0f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / chevron_ng-0.15.0-py3-none-any.whl
| Download URL | chevron_ng-0.15.0-py3-none-any.whl |
|---|---|
| Size | 16.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8a2eb3ceedf463bef73a08c66c8a06302752653ad761a90b54324503137c54bb
|
|
BLAKE2b-256 checksum How to use checksums |
1105990ccb69f178bba54e109f3e5b716881582ba454203b2c94e253c16f5dd5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for chevron-ng 0.15.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.