Skip to main content

Mustache for Python

Project description

Pystache is a Python implementation of Mustache. Mustache is a framework-agnostic, logic-free templating system inspired by ctemplate and et. Like ctemplate, Mustache “emphasizes separating logic from presentation: it is impossible to embed application logic in this template language.”

The mustache(5) man page provides a good introduction to Mustache’s syntax. For a more complete (and more current) description of Mustache’s behavior, see the official Mustache spec.

Pystache is semantically versioned and can be found on PyPI. This version of Pystache passes all tests in version 1.0.3 of the spec.

Logo: David Phillips


Pystache is tested with the following versions of Python:

  • Python 2.4 (requires simplejson version 2.0.9 or earlier)
  • Python 2.5 (requires simplejson)
  • Python 2.6
  • Python 2.7

JSON support is needed only for the command-line interface and to run the spec tests. Python’s json module is new as of Python 2.6. Python’s simplejson package works with earlier versions of Python. Because simplejson stopped officially supporting Python 2.4 as of version 2.1.0, Python 2.4 requires an earlier version.

Install It

pip install pystache

Use It

>>> import pystache
>>> pystache.render('Hi {{person}}!', {'person': 'Mom'})
u'Hi Mom!'

You can also create dedicated view classes to hold your view logic.

Here’s your view class (in examples/

class SayHello(object):

    def to(self):
        return "Pizza"

Like so:

>>> from examples.readme import SayHello
>>> hello = SayHello()

Then your template, say_hello.mustache:

Hello, {{to}}!

Pull it together:

>>> renderer = pystache.Renderer()
>>> renderer.render(hello)
u'Hello, Pizza!'

Unicode Handling

This section describes Pystache’s handling of unicode (e.g. strings and encodings).

Internally, Pystache uses only unicode strings. For input, Pystache accepts both unicode and str strings. For output, Pystache’s template rendering methods return only unicode.

Pystache’s Renderer class supports a number of attributes that control how Pystache converts str strings to unicode on input. These include the file_encoding, string_encoding, and decode_errors attributes.

The file_encoding attribute is the encoding the renderer uses to convert to unicode any files read from the file system. Similarly, string_encoding is the encoding the renderer uses to convert to unicode any other strings of type str encountered during the rendering process (e.g. context values of type str).

The decode_errors attribute is what the renderer passes as the errors argument to Python’s built-in unicode function unicode() when converting. The valid values for this argument are strict, ignore, and replace.

Each of these attributes can be set via the Renderer class’s constructor using a keyword argument of the same name. See the Renderer class’s docstrings for further details. In addition, the file_encoding attribute can be controlled on a per-view basis by subclassing the TemplateSpec class. When not specified explicitly, these attributes default to values set in Pystache’s defaults module.

Test It

nose works great!

pip install nose
cd pystache

Depending on your Python version and nose installation, you may need to type, for example


To include tests from the Mustache spec in your test runs:

git submodule init
git submodule update

To run all available tests (including doctests):

nosetests --with-doctest --doctest-extension=rst

or alternatively (using setup.cfg):

python nosetests

To run a subset of the tests, you can use this pattern, for example:

nosetests --tests tests/

Mailing List

As of November 2011, there’s a mailing list,


Note: There’s a bit of a delay in seeing the latest emails appear in the archive.


>>> context = { 'author': 'Chris Wanstrath', 'email': '' }
>>> pystache.render("{{author}} :: {{email}}", context)
u'Chris Wanstrath ::'


0.5.0 (2012-04-03)

This version represents a major rewrite and refactoring of the code base that also adds features and fixes many bugs. All functionality and nearly all unit tests have been preserved. However, some backwards incompatible changes to the API have been made.

Below is a selection of some of the changes (not exhaustive).


  • Pystache now passes all tests in version 1.0.3 of the Mustache spec. [pvande]
  • Removed View class: it is no longer necessary to subclass from View or from any other class to create a view.
  • Replaced Template with Renderer class: template rendering behavior can be modified via the Renderer constructor or by setting attributes on a Renderer instance.
  • Added TemplateSpec class: template rendering can be specified on a per-view basis by subclassing from TemplateSpec.
  • Introduced separation of concerns and removed circular dependencies (e.g. between Template and View classes, cf. issue #13).
  • Unicode now used consistently throughout the rendering process.
  • Expanded test coverage: nosetests now runs doctests and ~105 test cases from the Mustache spec (increasing the number of tests from 56 to ~315).
  • Added a rudimentary benchmarking script to gauge performance while refactoring.
  • Extensive documentation added (e.g. docstrings).

Other changes:

  • Added a command-line interface. [vrde]
  • The main rendering class now accepts a custom partial loader (e.g. a dictionary) and a custom escape function.
  • Non-ascii characters in str strings are now supported while rendering.
  • Added string encoding, file encoding, and errors options for decoding to unicode.
  • Removed the output encoding option.
  • Removed the use of markupsafe.

Bug fixes:

  • Context values no longer processed as template strings. [jakearchibald]
  • Whitespace surrounding sections is no longer altered, per the spec. [heliodor]
  • Zeroes now render correctly when using PyPy. [alex]
  • Multline comments now permitted. [fczuardi]
  • Extensionless template files are now supported.
  • Passing **kwargs to Template() no longer modifies the context.
  • Passing **kwargs to Template() with no context no longer raises an exception.

0.4.1 (2012-03-25)

  • Added support for Python 2.4. [wangtz, jvantuyl]

0.4.0 (2011-01-12)

  • Add support for nested contexts (within template and view)
  • Add support for inverted lists
  • Decoupled template loading

0.3.1 (2010-05-07)

  • Fix package

0.3.0 (2010-05-03)

  • View.template_path can now hold a list of path
  • Add {{& blah}} as an alias for {{{ blah }}}
  • Higher Order Sections
  • Inverted sections

0.2.0 (2010-02-15)

  • Bugfix: Methods returning False or None are not rendered
  • Bugfix: Don’t render an empty string when a tag’s value is 0. [enaeseth]
  • Add support for using non-callables as View attributes. [joshthecoder]
  • Allow using View instances as attributes. [joshthecoder]
  • Support for Unicode and non-ASCII-encoded bytestring output. [enaeseth]
  • Template file encoding awareness. [enaeseth]

0.1.1 (2009-11-13)

  • Ensure we’re dealing with strings, always
  • Tests can be run by executing the test file directly

0.1.0 (2009-11-12)

  • First release

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pystache-0.5.0.tar.gz (24.3 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page