README.rst 8.15 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--
27

Chris Jerdonek committed
28
* Python 2.4 (requires simplejson `version 2.0.9`_ or earlier)
29
* Python 2.5 (requires simplejson_)
30 31
* Python 2.6
* Python 2.7
32
* Python 3.1
33
* Python 3.2
Chris Wanstrath committed
34

35
JSON support is needed only for the command-line interface and to run the
36 37
spec tests.  We require simplejson for earlier versions of Python since
Python's json_ module was added in Python 2.6.
38

39 40 41
For Python 2.4 we require an earlier version of simplejson since simplejson
stopped officially supporting Python 2.4 in simplejson version 2.1.0.
Earlier versions of simplejson can be installed manually, as follows: ::
42 43 44

    pip install 'simplejson<2.1.0'

45

Chris Wanstrath committed
46 47 48 49 50
Install It
==========

::

Chris Wanstrath committed
51
    pip install pystache
52 53
    pystache-test

54
To install and test from source (e.g. from GitHub), see the Develop section.
Chris Wanstrath committed
55

Chris Wanstrath committed
56

57
Use It
58 59 60
======

::
61 62

    >>> import pystache
63 64
    >>> print pystache.render('Hi {{person}}!', {'person': 'Mom'})
    Hi Mom!
65

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

68
Here's your view class (in examples/readme.py)::
69

70
    class SayHello(object):
71

72
        def to(self):
73 74 75
            return "Pizza"

Like so::
76

77
    >>> from pystache.tests.examples.readme import SayHello
78
    >>> hello = SayHello()
79

80 81
Then your template, say_hello.mustache (in the same directory by default
as your class definition)::
82 83

    Hello, {{to}}!
84

85 86
Pull it together::

87
    >>> renderer = pystache.Renderer()
88 89
    >>> print renderer.render(hello)
    Hello, Pizza!
90

91 92 93 94 95 96 97
For greater control over rendering (e.g. to specify a custom template directory),
use the ``Renderer`` class directly.  One can pass attributes to the class's
constructor or set them on an instance.
To customize template loading on a per-view basis, subclass ``TemplateSpec``.
See the docstrings of the Renderer_ class and TemplateSpec_ class for
more information.

98

99 100 101
Python 3
========

102 103
Pystache has supported Python 3 since version 0.5.1.  Pystache behaves
slightly differently between Python 2 and 3, as follows:
104 105 106 107 108 109 110 111

* In Python 2, the default html-escape function ``cgi.escape()`` does not
  escape single quotes; whereas in Python 3, the default escape function
  ``html.escape()`` does escape single quotes.
* In both Python 2 and 3, the string and file encodings default to
  ``sys.getdefaultencoding()``.  However, this function can return different
  values under Python 2 and 3, even when run from the same system.  Check
  your own system for the behavior on your system, or do not rely on the
112
  defaults by passing in the encodings explicitly (e.g. to the ``Renderer`` class).
113 114


115 116
Unicode
=======
117

118
This section describes how Pystache handles unicode, strings, and encodings.
119

120 121
Internally, Pystache uses `only unicode strings`_ (``str`` in Python 3 and
``unicode`` in Python 2).  For input, Pystache accepts both unicode strings
122 123
and byte strings (``bytes`` in Python 3 and ``str`` in Python 2).  For output,
Pystache's template rendering methods return only unicode.
124

125 126
Pystache's ``Renderer`` class supports a number of attributes to control how
Pystache converts byte strings to unicode on input.  These include the
127 128 129
``file_encoding``, ``string_encoding``, and ``decode_errors`` attributes.

The ``file_encoding`` attribute is the encoding the renderer uses to convert
130
to unicode any files read from the file system.  Similarly, ``string_encoding``
131 132 133
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).
134 135

The ``decode_errors`` attribute is what the renderer passes as the ``errors``
136 137 138
argument to Python's built-in unicode-decoding function (``str()`` in Python 3
and ``unicode()`` in Python 2).  The valid values for this argument are
``strict``, ``ignore``, and ``replace``.
139 140

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


148
Develop
149
=======
Chris Wanstrath committed
150

151
To test from a source distribution (without installing)-- ::
152 153 154

    python test_pystache.py

155 156
To test Pystache with multiple versions of Python (with a single command!),
you can use tox_: ::
157 158 159

    pip install tox
    tox
160

Chris Jerdonek committed
161
If you do not have all Python versions listed in ``tox.ini``-- ::
Chris Jerdonek committed
162

163
    tox -e py26,py32  # for example
Chris Jerdonek committed
164

165 166
The source distribution tests also include doctests and tests from the
Mustache spec.  To include tests from the Mustache spec in your test runs: ::
167 168 169 170

    git submodule init
    git submodule update

Chris Jerdonek committed
171
The test harness parses the spec's (more human-readable) yaml files if PyYAML_
172 173 174
is present.  Otherwise, it parses the json files.  To install PyYAML-- ::

    pip install pyyaml
175

176 177 178 179 180
To run a subset of the tests, you can use nose_: ::

    pip install nose
    nosetests --tests pystache/tests/test_context.py:GetValueTests.test_dictionary__key_present

181 182 183 184 185 186 187 188 189 190
**Running Pystache from source with Python 3.**  Pystache is written in
Python 2 and must be converted with 2to3_ prior to running under Python 3.
The installation process (and tox) do this conversion automatically.

To ``import pystache`` from a source distribution while using Python 3,
be sure that you are importing from a directory containing a converted
version (e.g. from your site-packages directory after manually installing)
and not from the original source directory.  Otherwise, you will get a
syntax error.  You can help ensure this by not running the Python IDE
from the project directory when importing Pystache.
191

Chris Wanstrath committed
192

Tim Kersten committed
193
Mailing List
194
============
195

196 197
There is a `mailing list`_.  Note that there is a bit of a delay between
posting a message and seeing it appear in the mailing list archive.
Tim Kersten committed
198

199

200 201
Authors
=======
202 203

::
Chris Wanstrath committed
204

205
    >>> context = { 'author': 'Chris Wanstrath', 'maintainer': 'Chris Jerdonek' }
Chris Jerdonek committed
206 207 208
    >>> print pystache.render("Author: {{author}}\nMaintainer: {{maintainer}}", context)
    Author: Chris Wanstrath
    Maintainer: Chris Jerdonek
Chris Wanstrath committed
209 210


211
.. _2to3: http://docs.python.org/library/2to3.html
Chris Jerdonek committed
212
.. _built-in unicode function: http://docs.python.org/library/functions.html#unicode
213
.. _ctemplate: http://code.google.com/p/google-ctemplate/
214
.. _David Phillips: http://davidphillips.us/
215
.. _Distribute: http://pypi.python.org/pypi/distribute
216
.. _et: http://www.ivan.fomichev.name/2008/05/erlang-template-engine-prototype.html
217
.. _json: http://docs.python.org/library/json.html
218
.. _mailing list: http://librelist.com/browser/pystache/
219
.. _Mustache: http://mustache.github.com/
220
.. _Mustache spec: https://github.com/mustache/spec
221
.. _mustache(5): http://mustache.github.com/mustache.5.html
222
.. _nose: http://somethingaboutorange.com/mrl/projects/nose/0.11.1/testing.html
223
.. _only unicode strings: http://docs.python.org/howto/unicode.html#tips-for-writing-unicode-aware-programs
224
.. _PyPI: http://pypi.python.org/pypi/pystache
225
.. _Pystache: https://github.com/defunkt/pystache
226
.. _PyYAML: http://pypi.python.org/pypi/PyYAML
227
.. _Renderer: https://github.com/defunkt/pystache/blob/master/pystache/renderer.py
228
.. _semantically versioned: http://semver.org
229
.. _simplejson: http://pypi.python.org/pypi/simplejson/
230
.. _TemplateSpec: https://github.com/defunkt/pystache/blob/master/pystache/template_spec.py
Chris Jerdonek committed
231
.. _test: http://packages.python.org/distribute/setuptools.html#test
232
.. _tox: http://pypi.python.org/pypi/tox
233
.. _version 1.1.2: https://github.com/mustache/spec/tree/v1.1.2
Chris Jerdonek committed
234
.. _version 2.0.9: http://pypi.python.org/pypi/simplejson/2.0.9