Skip to content

Getting started

Chevron requires Python 3.11 or later. The core package renders synchronously. Async rendering additionally needs the anyio extra; applications that run on Trio also need the trio extra.

The following example renders a useful page fragment rather than a single replacement. The template can stay with the application, while the view data is a normal Python mapping.

import chevron

template = """<article>
  <h1>{{title}}</h1>
  {{#summary}}<p>{{summary}}</p>{{/summary}}
  <ul>{{#tags}}<li>{{.}}</li>{{/tags}}</ul>
</article>"""

page = chevron.render(
    template,
    {
        "title": "Release notes",
        "summary": "Changes ready for review.",
        "tags": ["documentation", "mustache"],
    },
)

The result is one complete string. Values are HTML-escaped by default, sections repeat or omit content according to their value, and {{.}} means the current list item. Continue with values and contexts for those rules.

A useful division of responsibility

Templates decide presentation. Application code decides which data, partial mappings, filesystem directory, lambda mapping, and logger are safe to expose. Chevron does not turn a template into a sandbox: do not place secrets or powerful application objects in template data merely because a template is untrusted.

For an application that keeps reusable components in memory, pass partials_dict; for a controlled template directory, pass partials_path. The partials and layouts chapter covers both patterns.