Description

Pystache ======== |ci| |conda| |coverage| |bandit| |release| |pre| |cov| |pylint| |tag| |license| |python| This updated fork of Pystache is currently tested on Python 3.8+ and in Conda, on Linux, Macos, and Windows. |logo| `Pystache <https://github.com/PennyDreadfulMTG/pystache>`__ is a Python implementation of `Mustache <https://github.com/mustache/mustache/>`__. Mustache is a framework-agnostic, logic-free templating system inspired by `ctemplate <https://code.google.com/p/google-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) <https://mustache.github.io/mustache.5.html>`__ 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 <https://github.com/mustache/spec>`__. Pystache is `semantically versioned <https://semver.org>`__ and older versions can still be found on `PyPI <https://pypi.python.org/pypi/pystache>`__. This version of Pystache now passes all tests in `version 1.1.3 <https://github.com/mustache/spec/tree/v1.1.3>`__ of the spec. Requirements ============ Pystache is tested with: - Python 3.8 - Python 3.9 - Python 3.10 - Python 3.11 - Python 3.12 - Python 3.13 - Conda (py38 and py310) JSON support is needed only for the command-line interface and to run the spec tests; PyYAML can still be used (see the Develop section). Official support for Python 2 has ended with Pystache version 0.6.0. .. note:: This project uses setuptools_scm_ to generate and maintain the version file, which only gets included in the sdist/wheel packages. In a fresh clone, running any of the tox_ commands should generate the current version file. .. _setuptools_scm: https://github.com/pypa/setuptools_scm .. _tox: https://github.com/tox-dev/tox Quick Start =========== Be sure to get the latest release from either Pypi or Github. Install It ---------- From Pypi:: $ pip install pystache Or Github:: $ pip install -U pystache -f https://github.com/PennyDreadfulMTG/pystache/releases/ And test it:: $ pystache-test To install and test from source (e.g. from GitHub), see the Develop section. Use It ------ Open a python console:: >>> import pystache >>> print(pystache.render('Hi {{person}}!', {'person': 'Mom'})) Hi Mom! You can also create dedicated view classes to hold your view logic. Here's your view class (in ../pystache/tests/examples/readme.py): :: class SayHello(object): def to(self): return "Pizza" Instantiating like so: :: >>> from pystache.tests.examples.readme import SayHello >>> hello = SayHello() Then your template, say_hello.mustache (by default in the same directory as your class definition): :: Hello, {{to}}! Pull it together: :: >>> renderer = pystache.Renderer() >>> print(renderer.render(hello)) Hello, Pizza! For greater control over rendering (e.g. to specify a custom template directory), use the ``Renderer`` class like above. One can pass attributes to the Renderer class constructor or set them on a Renderer instance. To customize template loading on a per-view basis, subclass ``TemplateSpec``. See the docstrings of the `Renderer <https://github.com/PennyDreadfulMTG/pystache/blob/master/pystache/renderer.py>`__ class and `TemplateSpec <https://github.com/PennyDreadfulMTG/pystache/blob/master/pystache/template_spec.py>`__ class for more information. You can also pre-parse a template: :: >>> parsed = pystache.parse(u"Hey {{#who}}{{.}}!{{/who}}") >>> print(parsed) ['Hey ', _SectionNode(key='who', index_begin=12, index_end=18, parsed=[_EscapeNode(key='.'), '!'])] And then: :: >>> print(renderer.render(parsed, {'who': 'Pops'})) Hey Pops! >>> print(renderer.render(parsed, {'who': 'you'})) Hey you! Unicode ------- This section describes how Pystache handles unicode, strings, and encodings. Internally, Pystache uses `only unicode strings`_ (``str`` in Python 3). For input, Pystache accepts byte strings (``bytes`` in Python 3). For output, Pystache's template rendering methods return only unicode. .. _only unicode strings: https://docs.python.org/howto/unicode.html#tips-for-writing-unicode-aware-programs Pystache's ``Renderer`` class supports a number of attributes to control how Pystache converts byte 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 any other byte strings encountered during the rendering process into unicode (e.g. context values that are encoded byte strings). The ``decode_errors`` attribute is what the renderer passes as the ``errors`` argumen