Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 210 lines (143 sloc) 6.785 kb
04560ac @dinoboff Convert HISTORY and README to reStructuredText
dinoboff authored
1 ========
0ed75fa @defunkt simple readme
authored
2 Pystache
3 ========
4
e427b7b @arkany Edited README.rst via GitHub
arkany authored
5 .. image:: https://s3.amazonaws.com/webdev_bucket/pystache.png
6
17b144e @cjerdonek Tweaked introduction to README.
cjerdonek authored
7 Pystache_ is a Python implementation of Mustache_.
8 Mustache is a framework-agnostic, logic-free templating system inspired
9 by ctemplate_ and et_. Like ctemplate, Mustache "emphasizes
8189c76 @cjerdonek README tweaks: moved documentation into intro; cleaned up links.
cjerdonek authored
10 separating logic from presentation: it is impossible to embed application
11 logic in this template language."
0ed75fa @defunkt simple readme
authored
12
8189c76 @cjerdonek README tweaks: moved documentation into intro; cleaned up links.
cjerdonek authored
13 The `mustache(5)`_ man page provides a good introduction to Mustache's
14 syntax. For a more complete (and more current) description of Mustache's
17b144e @cjerdonek Tweaked introduction to README.
cjerdonek authored
15 behavior, see the official `Mustache spec`_.
0ed75fa @defunkt simple readme
authored
16
5d8eecf @cjerdonek Added to the README a link to the PyPI page.
cjerdonek authored
17 Pystache is `semantically versioned`_ and can be found on PyPI_. This
18 version of Pystache passes all tests in `version 1.0.3`_ of the spec.
0ed75fa @defunkt simple readme
authored
19
8189c76 @cjerdonek README tweaks: moved documentation into intro; cleaned up links.
cjerdonek authored
20 Logo: `David Phillips`_
929c369 @arkany added Pystache logo. Hope you like it!
arkany authored
21
5ba98b3 @cjerdonek Merge branch 'master' into 'development': v0.4.1 changes
cjerdonek authored
22
594bc73 @cjerdonek Addressed issue #43: added spec version that pystache complies with.
cjerdonek authored
23 Requirements
24 ============
25
5999592 @cjerdonek More README refinements.
cjerdonek authored
26 Pystache is tested with the following versions of Python:
8e89497 @cjerdonek Added support for Python 2.4: issue #89 (wangtz) and issue #94 (jvantuyl...
cjerdonek authored
27
da43d44 @cjerdonek Further README cleanups.
cjerdonek authored
28 * Python 2.4 (requires simplejson version 2.0.9 or earlier)
29 * Python 2.5 (requires simplejson)
8e89497 @cjerdonek Added support for Python 2.4: issue #89 (wangtz) and issue #94 (jvantuyl...
cjerdonek authored
30 * Python 2.6
31 * Python 2.7
d36bc2a @cjerdonek Added "support for Python 3" to README and HISTORY.
cjerdonek authored
32 * Python 3.2
0ed75fa @defunkt simple readme
authored
33
da43d44 @cjerdonek Further README cleanups.
cjerdonek authored
34 JSON support is needed only for the command-line interface and to run the
1485797 @cjerdonek Wording change in README regarding simplejson.
cjerdonek authored
35 spec tests. We require simplejson_ for earlier versions of Python since
36 Python's json_ module was added in Python 2.6. Moreover, we require an
37 earlier version of simplejson for Python 2.4 since simplejson stopped
38 officially supporting Python 2.4 with version 2.1.0.
cf2f05d @cjerdonek Added two TODO's to the README.
cjerdonek authored
39
e6cddf9 @cjerdonek Added a note to the README re: installing an older version of simplejson...
cjerdonek authored
40 An earlier version of simplejson can be installed manually, as follows: ::
41
42 pip install 'simplejson<2.1.0'
43
594bc73 @cjerdonek Addressed issue #43: added spec version that pystache complies with.
cjerdonek authored
44
c514948 @defunkt install it
authored
45 Install It
46 ==========
47
48 ::
49
6c679ef @defunkt What was I thinking?
authored
50 pip install pystache
c514948 @defunkt install it
authored
51
0ed75fa @defunkt simple readme
authored
52
a65d398 @defunkt update readme with new api
authored
53 Use It
04560ac @dinoboff Convert HISTORY and README to reStructuredText
dinoboff authored
54 ======
55
56 ::
a65d398 @defunkt update readme with new api
authored
57
58 >>> import pystache
7341e36 @cjerdonek Changed the README doctests to work after 2to3 conversion.
cjerdonek authored
59 >>> print pystache.render('Hi {{person}}!', {'person': 'Mom'})
60 Hi Mom!
a65d398 @defunkt update readme with new api
authored
61
a1d4610 @defunkt mention view classes in the readme
authored
62 You can also create dedicated view classes to hold your view logic.
63
aa1a256 @cjerdonek Spacing; added a link to the spec; and made the author line a doctest.
cjerdonek authored
64 Here's your view class (in examples/readme.py)::
04560ac @dinoboff Convert HISTORY and README to reStructuredText
dinoboff authored
65
d595856 @cjerdonek READM view example is now more real.
cjerdonek authored
66 class SayHello(object):
aa1a256 @cjerdonek Spacing; added a link to the spec; and made the author line a doctest.
cjerdonek authored
67
d595856 @cjerdonek READM view example is now more real.
cjerdonek authored
68 def to(self):
8b92c96 @cjerdonek README formatting tweaks.
cjerdonek authored
69 return "Pizza"
70
71 Like so::
a1d4610 @defunkt mention view classes in the readme
authored
72
9b5195f @cjerdonek README doctest update for moving examples folder.
cjerdonek authored
73 >>> from pystache.tests.examples.readme import SayHello
d595856 @cjerdonek READM view example is now more real.
cjerdonek authored
74 >>> hello = SayHello()
04560ac @dinoboff Convert HISTORY and README to reStructuredText
dinoboff authored
75
aa1a256 @cjerdonek Spacing; added a link to the spec; and made the author line a doctest.
cjerdonek authored
76 Then your template, say_hello.mustache::
d595856 @cjerdonek READM view example is now more real.
cjerdonek authored
77
78 Hello, {{to}}!
a1d4610 @defunkt mention view classes in the readme
authored
79
04560ac @dinoboff Convert HISTORY and README to reStructuredText
dinoboff authored
80 Pull it together::
81
d595856 @cjerdonek READM view example is now more real.
cjerdonek authored
82 >>> renderer = pystache.Renderer()
7341e36 @cjerdonek Changed the README doctests to work after 2to3 conversion.
cjerdonek authored
83 >>> print renderer.render(hello)
84 Hello, Pizza!
a1d4610 @defunkt mention view classes in the readme
authored
85
a65d398 @defunkt update readme with new api
authored
86
96f039d @cjerdonek Added notes to the README regarding Python 3.
cjerdonek authored
87 Python 3
88 ========
89
d36bc2a @cjerdonek Added "support for Python 3" to README and HISTORY.
cjerdonek authored
90 As of version 0.5.1, Pystache fully supports Python 3. There are slight
91 differences in behavior between Pystache running under Python 2 and 3,
92 as follows:
96f039d @cjerdonek Added notes to the README regarding Python 3.
cjerdonek authored
93
94 * In Python 2, the default html-escape function ``cgi.escape()`` does not
95 escape single quotes; whereas in Python 3, the default escape function
96 ``html.escape()`` does escape single quotes.
97 * In both Python 2 and 3, the string and file encodings default to
98 ``sys.getdefaultencoding()``. However, this function can return different
99 values under Python 2 and 3, even when run from the same system. Check
100 your own system for the behavior on your system, or do not rely on the
b488143 @cjerdonek Made README section on unicode correct for both Python 2 and 3.
cjerdonek authored
101 defaults by passing in the encodings explicitly (e.g. to the ``Renderer`` class).
96f039d @cjerdonek Added notes to the README regarding Python 3.
cjerdonek authored
102
103
ccee7d9 @cjerdonek Tweaks to the unicode section of the README.
cjerdonek authored
104 Unicode Handling
105 ================
106
107 This section describes Pystache's handling of unicode (e.g. strings and
108 encodings).
d202377 @cjerdonek Added to README a section on unicode string handling.
cjerdonek authored
109
b488143 @cjerdonek Made README section on unicode correct for both Python 2 and 3.
cjerdonek authored
110 Internally, Pystache uses `only unicode strings`_ (type ``str`` in Python 3 and
111 type ``unicode`` in Python 2). For input, Pystache accepts both unicode strings
112 and byte strings (``bytes`` in Python 3 and ``str`` in Python 2). For output,
113 Pystache's template rendering methods return only unicode.
d202377 @cjerdonek Added to README a section on unicode string handling.
cjerdonek authored
114
b488143 @cjerdonek Made README section on unicode correct for both Python 2 and 3.
cjerdonek authored
115 Pystache's ``Renderer`` class supports a number of attributes to control how
116 Pystache converts byte strings to unicode on input. These include the
135540b @cjerdonek More tweaks to the unicode section of the README.
cjerdonek authored
117 ``file_encoding``, ``string_encoding``, and ``decode_errors`` attributes.
118
119 The ``file_encoding`` attribute is the encoding the renderer uses to convert
da43d44 @cjerdonek Further README cleanups.
cjerdonek authored
120 to unicode any files read from the file system. Similarly, ``string_encoding``
b488143 @cjerdonek Made README section on unicode correct for both Python 2 and 3.
cjerdonek authored
121 is the encoding the renderer uses to convert any other byte strings encountered
122 during the rendering process into unicode (e.g. context values that are
123 encoded byte strings).
8a4cdc7 @cjerdonek Added JSON requirements to README.
cjerdonek authored
124
125 The ``decode_errors`` attribute is what the renderer passes as the ``errors``
b488143 @cjerdonek Made README section on unicode correct for both Python 2 and 3.
cjerdonek authored
126 argument to Python's built-in unicode-decoding function (``str()`` in Python 3
127 and ``unicode()`` in Python 2). The valid values for this argument are
128 ``strict``, ``ignore``, and ``replace``.
135540b @cjerdonek More tweaks to the unicode section of the README.
cjerdonek authored
129
130 Each of these attributes can be set via the ``Renderer`` class's constructor
da43d44 @cjerdonek Further README cleanups.
cjerdonek authored
131 using a keyword argument of the same name. See the Renderer class's
5999592 @cjerdonek More README refinements.
cjerdonek authored
132 docstrings for further details. In addition, the ``file_encoding``
135540b @cjerdonek More tweaks to the unicode section of the README.
cjerdonek authored
133 attribute can be controlled on a per-view basis by subclassing the
da43d44 @cjerdonek Further README cleanups.
cjerdonek authored
134 ``TemplateSpec`` class. When not specified explicitly, these attributes
135 default to values set in Pystache's ``defaults`` module.
d202377 @cjerdonek Added to README a section on unicode string handling.
cjerdonek authored
136
137
a65d398 @defunkt update readme with new api
authored
138 Test It
04560ac @dinoboff Convert HISTORY and README to reStructuredText
dinoboff authored
139 =======
0ed75fa @defunkt simple readme
authored
140
4c9d50d @cjerdonek Updated README to reflect new testing procedures.
cjerdonek authored
141 From an install-- ::
142
143 pystache-test
144
145 From a source distribution-- ::
146
147 python test_pystache.py
148
09a5c9c @cjerdonek Updated README re: testing.
cjerdonek authored
149 To test Pystache source under multiple versions of Python all at once, you
150 can use tox_: ::
58640f0 @cjerdonek Added documentation re: tox.
cjerdonek authored
151
152 pip install tox
153 tox
96f039d @cjerdonek Added notes to the README regarding Python 3.
cjerdonek authored
154
6c42ef7 @cjerdonek README formatting fix.
cjerdonek authored
155 If you do not have all Python versions listed in ``tox.ini``-- ::
9d1e3aa @cjerdonek Tweaks to tox comments.
cjerdonek authored
156
157 tox -e py26,py27 # for example
158
4c9d50d @cjerdonek Updated README to reflect new testing procedures.
cjerdonek authored
159 The source distribution tests also include doctests and tests from the
160 Mustache spec. To include tests from the Mustache spec in your test runs: ::
96f039d @cjerdonek Added notes to the README regarding Python 3.
cjerdonek authored
161
162 git submodule init
163 git submodule update
164
11eaef8 @cjerdonek README tweak.
cjerdonek authored
165 To test Pystache from a source distribution with Python 3.x, you must use tox.
166 This is because the raw source is not Python 3 compatible and must first be
167 run through 2to3_.
864957a @cjerdonek Added a setup.cfg file (to store nosetests options).
cjerdonek authored
168
0ed75fa @defunkt simple readme
authored
169
dcd01d5 @io41 Add mailing list details.
io41 authored
170 Mailing List
5ba98b3 @cjerdonek Merge branch 'master' into 'development': v0.4.1 changes
cjerdonek authored
171 ============
aa1a256 @cjerdonek Spacing; added a link to the spec; and made the author line a doctest.
cjerdonek authored
172
173 As of November 2011, there's a mailing list, pystache@librelist.com.
dcd01d5 @io41 Add mailing list details.
io41 authored
174
175 Archive: http://librelist.com/browser/pystache/
176
177 Note: There's a bit of a delay in seeing the latest emails appear
178 in the archive.
179
5ba98b3 @cjerdonek Merge branch 'master' into 'development': v0.4.1 changes
cjerdonek authored
180
0ed75fa @defunkt simple readme
authored
181 Author
04560ac @dinoboff Convert HISTORY and README to reStructuredText
dinoboff authored
182 ======
183
184 ::
0ed75fa @defunkt simple readme
authored
185
aa1a256 @cjerdonek Spacing; added a link to the spec; and made the author line a doctest.
cjerdonek authored
186 >>> context = { 'author': 'Chris Wanstrath', 'email': 'chris@ozmm.org' }
7341e36 @cjerdonek Changed the README doctests to work after 2to3 conversion.
cjerdonek authored
187 >>> print pystache.render("{{author}} :: {{email}}", context)
188 Chris Wanstrath :: chris@ozmm.org
0ed75fa @defunkt simple readme
authored
189
190
58640f0 @cjerdonek Added documentation re: tox.
cjerdonek authored
191 .. _2to3: http://docs.python.org/library/2to3.html
9d1e3aa @cjerdonek Tweaks to tox comments.
cjerdonek authored
192 .. _built-in unicode function: http://docs.python.org/library/functions.html#unicode
04560ac @dinoboff Convert HISTORY and README to reStructuredText
dinoboff authored
193 .. _ctemplate: http://code.google.com/p/google-ctemplate/
8189c76 @cjerdonek README tweaks: moved documentation into intro; cleaned up links.
cjerdonek authored
194 .. _David Phillips: http://davidphillips.us/
b488143 @cjerdonek Made README section on unicode correct for both Python 2 and 3.
cjerdonek authored
195 .. _Distribute: http://pypi.python.org/pypi/distribute
04560ac @dinoboff Convert HISTORY and README to reStructuredText
dinoboff authored
196 .. _et: http://www.ivan.fomichev.name/2008/05/erlang-template-engine-prototype.html
8a4cdc7 @cjerdonek Added JSON requirements to README.
cjerdonek authored
197 .. _json: http://docs.python.org/library/json.html
8189c76 @cjerdonek README tweaks: moved documentation into intro; cleaned up links.
cjerdonek authored
198 .. _Mustache: http://mustache.github.com/
17b144e @cjerdonek Tweaked introduction to README.
cjerdonek authored
199 .. _Mustache spec: https://github.com/mustache/spec
442f84d @adamv Fix link to mustache(5)
adamv authored
200 .. _mustache(5): http://mustache.github.com/mustache.5.html
84e24e5 @cjerdonek Tests now pass with Python 3.1.
cjerdonek authored
201 .. _nose: http://readthedocs.org/docs/nose/en/latest/
9aca794 @cjerdonek Added to README a link to the Python documentation's "Tips for Writing U...
cjerdonek authored
202 .. _only unicode strings: http://docs.python.org/howto/unicode.html#tips-for-writing-unicode-aware-programs
5d8eecf @cjerdonek Added to the README a link to the PyPI page.
cjerdonek authored
203 .. _PyPI: http://pypi.python.org/pypi/pystache
8189c76 @cjerdonek README tweaks: moved documentation into intro; cleaned up links.
cjerdonek authored
204 .. _Pystache: https://github.com/defunkt/pystache
205 .. _semantically versioned: http://semver.org
8a4cdc7 @cjerdonek Added JSON requirements to README.
cjerdonek authored
206 .. _simplejson: http://pypi.python.org/pypi/simplejson/
9d1e3aa @cjerdonek Tweaks to tox comments.
cjerdonek authored
207 .. _test: http://packages.python.org/distribute/setuptools.html#test
58640f0 @cjerdonek Added documentation re: tox.
cjerdonek authored
208 .. _tox: http://pypi.python.org/pypi/tox
8189c76 @cjerdonek README tweaks: moved documentation into intro; cleaned up links.
cjerdonek authored
209 .. _version 1.0.3: https://github.com/mustache/spec/tree/48c933b0bb780875acbfd15816297e263c53d6f7
Something went wrong with that request. Please try again.