README.rst 5.35 KB
Newer Older
1
========
Chris Wanstrath committed
2 3 4
Pystache
========

arkany committed
5 6
.. image:: https://s3.amazonaws.com/webdev_bucket/pystache.png

7 8 9
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
10 11
separating logic from presentation: it is impossible to embed application
logic in this template language."
Chris Wanstrath committed
12

13 14
The `mustache(5)`_ man page provides a good introduction to Mustache's
syntax.  For a more complete (and more current) description of Mustache's
15
behavior, see the official `Mustache spec`_.
Chris Wanstrath committed
16

17
Pystache is `semantically versioned`_ and can be found on PyPI_.  This
18
version of Pystache passes all tests in `version 1.1.2`_ of the spec.
Chris Wanstrath committed
19

20
Logo: `David Phillips`_
21

22

23 24 25
Requirements
============

26
Pystache is tested with the following versions of Python:
27

28 29
* Python 2.4 (requires simplejson version 2.0.9 or earlier)
* Python 2.5 (requires simplejson)
30 31
* Python 2.6
* Python 2.7
Chris Wanstrath committed
32

33
JSON support is needed only for the command-line interface and to run the
34 35 36 37
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.
38

39

Chris Wanstrath committed
40 41 42 43 44
Install It
==========

::

Chris Wanstrath committed
45
    pip install pystache
Chris Wanstrath committed
46

Chris Wanstrath committed
47

48
Use It
49 50 51
======

::
52 53 54

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

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

59
Here's your view class (in examples/readme.py)::
60

61
    class SayHello(object):
62

63
        def to(self):
64 65 66
            return "Pizza"

Like so::
67

68 69
    >>> from examples.readme import SayHello
    >>> hello = SayHello()
70

71
Then your template, say_hello.mustache::
72 73

    Hello, {{to}}!
74

75 76
Pull it together::

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

81

82 83 84 85 86
Unicode Handling
================

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

88
Internally, Pystache uses `only unicode strings`_.  For input, Pystache accepts
89 90
both ``unicode`` and ``str`` strings.  For output, Pystache's template
rendering methods return only unicode.
91

92 93 94 95 96
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
97
to unicode any files read from the file system.  Similarly, ``string_encoding``
98 99
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
100 101 102
of type ``str``).

The ``decode_errors`` attribute is what the renderer passes as the ``errors``
103 104 105
argument to Python's `built-in unicode function`_ ``unicode()`` when
converting.  The valid values for this argument are ``strict``, ``ignore``,
and ``replace``.
106 107

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


115
Test It
116
=======
Chris Wanstrath committed
117

118
nose_ works great! ::
Chris Wanstrath committed
119

Chris Wanstrath committed
120
    pip install nose
Chris Wanstrath committed
121
    cd pystache
122
    nosetests
Chris Wanstrath committed
123

124 125 126 127 128
Depending on your Python version and nose installation, you may need
to type, for example ::

    nosetests-2.4

129
To include tests from the Mustache spec in your test runs: ::
130 131 132 133

    git submodule init
    git submodule update

134
To run all available tests (including doctests)::
135

136
    nosetests --with-doctest --doctest-extension=rst
137

138
or alternatively (using setup.cfg)::
139 140 141

    python setup.py nosetests

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

    nosetests --tests tests/test_context.py:GetValueTests.test_dictionary__key_present
Chris Wanstrath committed
145 146


Tim Kersten committed
147
Mailing List
148
============
149 150

As of November 2011, there's a mailing list, pystache@librelist.com.
Tim Kersten committed
151 152 153 154 155 156

Archive: http://librelist.com/browser/pystache/

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

157

Chris Wanstrath committed
158
Author
159 160 161
======

::
Chris Wanstrath committed
162

163 164 165
    >>> context = { 'author': 'Chris Wanstrath', 'email': 'chris@ozmm.org' }
    >>> pystache.render("{{author}} :: {{email}}", context)
    u'Chris Wanstrath :: chris@ozmm.org'
Chris Wanstrath committed
166 167


168
.. _ctemplate: http://code.google.com/p/google-ctemplate/
169
.. _David Phillips: http://davidphillips.us/
170
.. _et: http://www.ivan.fomichev.name/2008/05/erlang-template-engine-prototype.html
171
.. _json: http://docs.python.org/library/json.html
172
.. _Mustache: http://mustache.github.com/
173
.. _Mustache spec: https://github.com/mustache/spec
174
.. _mustache(5): http://mustache.github.com/mustache.5.html
175
.. _nose: http://somethingaboutorange.com/mrl/projects/nose/0.11.1/testing.html
176
.. _only unicode strings: http://docs.python.org/howto/unicode.html#tips-for-writing-unicode-aware-programs
177
.. _PyPI: http://pypi.python.org/pypi/pystache
178 179
.. _Pystache: https://github.com/defunkt/pystache
.. _semantically versioned: http://semver.org
180
.. _simplejson: http://pypi.python.org/pypi/simplejson/
181
.. _built-in unicode function: http://docs.python.org/library/functions.html#unicode
182
.. _version 1.0.3: https://github.com/mustache/spec/tree/48c933b0bb780875acbfd15816297e263c53d6f7