Skip to main content

PyPI version

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)

Source distribution for chevron-ng 0.15.0
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)

Table of built distributions (wheels) for chevron-ng 0.15.0
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page