Pystache

Pystache is a Python implementation of Mustache, the framework-agnostic, logic-free templating system. It renders Mustache templates from plain dictionaries, arbitrary Python objects, or dedicated view classes, deliberately keeping application logic out of the presentation layer.

This maintained fork tracks the official Mustache spec (passing version 1.1.3) and runs on modern Python 3.8+ across Linux, macOS, and Windows. It ships both a simple render() helper for one-off use and a configurable Renderer class for template loading, partials, and custom escaping.

What You Get

• A pystache.render(template, context) helper for rendering strings in a single call
• A configurable Renderer class for custom template directories, partials, and escaping
• View class support via TemplateSpec for binding templates to Python objects
• A template pre-parser (pystache.parse) that returns a reusable parsed tree
• A pystache-test command-line runner that validates against the Mustache spec

Common Use Cases

• Generating HTML, config files, or emails from logic-free templates
• Sharing a single set of Mustache templates across Python and other languages
• Rendering per-object views by pairing template files with view classes
• Producing text output in projects that want strict logic/presentation separation

Under The Hood

Architecture - Pystache splits rendering into a clear pipeline: parser.py tokenizes a template string into a parsed tree of nodes (parsed.py), renderengine.py walks that tree against a context.py stack that resolves keys from dicts and objects, and renderer.py provides the public Renderer facade that ties loading, parsing, and escaping together. Template-to-view binding is handled separately by template_spec.py and specloader.py, keeping file discovery out of the core engine.

Tech Stack - The library is pure Python with no runtime dependencies beyond importlib-metadata on older interpreters. It targets Python 3.8+, uses setuptools with setuptools_scm for versioning, and is tested with tox across Linux, macOS, and Windows plus Conda.

Code Quality - Correctness is anchored to the official Mustache spec: the bundled pystache-test runner and test_pystache.py execute the spec suite (passing version 1.1.3) alongside the project’s own tests. The module boundaries (parser, engine, context, loader) are well separated, though the codebase is a long-lived fork and carries some older Python idioms.

API Design - The surface is intentionally tiny: pystache.render() covers the common case in one line, while the Renderer class exposes escaping, encoding, partial loading, and template directories for advanced use. pystache.parse() returns a reusable tree for hot paths, and TemplateSpec subclassing gives per-view control without touching the engine.