mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-11-25 22:01:30 +00:00
51503a1a67
--HG-- extra : rebase_source : 7a91182ca85dde748a14b03fa93ae85769691042 extra : source : b91e85b02d796db5de9a0e726a7c3360ea67b400
514 lines
17 KiB
ReStructuredText
514 lines
17 KiB
ReStructuredText
.. Do not edit this file. This file is auto-generated for PyPI by setup.py
|
|
.. using pandoc, so edits should go in the source files rather than here.
|
|
|
|
Pystache
|
|
========
|
|
|
|
.. figure:: http://defunkt.github.com/pystache/images/logo_phillips.png
|
|
:alt: mustachioed, monocled snake by David Phillips
|
|
|
|
.. figure:: https://secure.travis-ci.org/defunkt/pystache.png
|
|
:alt: Travis CI current build status
|
|
|
|
`Pystache <http://defunkt.github.com/pystache>`__ is a Python
|
|
implementation of `Mustache <http://mustache.github.com/>`__. Mustache
|
|
is a framework-agnostic, logic-free templating system inspired by
|
|
`ctemplate <http://code.google.com/p/google-ctemplate/>`__ and
|
|
`et <http://www.ivan.fomichev.name/2008/05/erlang-template-engine-prototype.html>`__.
|
|
Like ctemplate, Mustache "emphasizes separating logic from presentation:
|
|
it is impossible to embed application logic in this template language."
|
|
|
|
The `mustache(5) <http://mustache.github.com/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 <http://semver.org>`__ and can be
|
|
found on `PyPI <http://pypi.python.org/pypi/pystache>`__. This version
|
|
of Pystache passes all tests in `version
|
|
1.1.2 <https://github.com/mustache/spec/tree/v1.1.2>`__ of the spec.
|
|
|
|
Requirements
|
|
------------
|
|
|
|
Pystache is tested with--
|
|
|
|
- Python 2.4 (requires simplejson `version
|
|
2.0.9 <http://pypi.python.org/pypi/simplejson/2.0.9>`__ or earlier)
|
|
- Python 2.5 (requires
|
|
`simplejson <http://pypi.python.org/pypi/simplejson/>`__)
|
|
- Python 2.6
|
|
- Python 2.7
|
|
- Python 3.1
|
|
- Python 3.2
|
|
- Python 3.3
|
|
- `PyPy <http://pypy.org/>`__
|
|
|
|
`Distribute <http://packages.python.org/distribute/>`__ (the setuptools
|
|
fork) is recommended over
|
|
`setuptools <http://pypi.python.org/pypi/setuptools>`__, and is required
|
|
in some cases (e.g. for Python 3 support). If you use
|
|
`pip <http://www.pip-installer.org/>`__, you probably already satisfy
|
|
this requirement.
|
|
|
|
JSON support is needed only for the command-line interface and to run
|
|
the spec tests. We require simplejson for earlier versions of Python
|
|
since Python's `json <http://docs.python.org/library/json.html>`__
|
|
module was added in Python 2.6.
|
|
|
|
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:
|
|
|
|
::
|
|
|
|
pip install 'simplejson<2.1.0'
|
|
|
|
Official support for Python 2.4 will end with Pystache version 0.6.0.
|
|
|
|
Install It
|
|
----------
|
|
|
|
::
|
|
|
|
pip install pystache
|
|
|
|
And test it--
|
|
|
|
::
|
|
|
|
pystache-test
|
|
|
|
To install and test from source (e.g. from GitHub), see the Develop
|
|
section.
|
|
|
|
Use It
|
|
------
|
|
|
|
::
|
|
|
|
>>> 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 .../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/defunkt/pystache/blob/master/pystache/renderer.py>`__
|
|
class and
|
|
`TemplateSpec <https://github.com/defunkt/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
|
|
[u'Hey ', _SectionNode(key=u'who', index_begin=12, index_end=18, parsed=[_EscapeNode(key=u'.'), u'!'])]
|
|
|
|
And then:
|
|
|
|
::
|
|
|
|
>>> print renderer.render(parsed, {'who': 'Pops'})
|
|
Hey Pops!
|
|
>>> print renderer.render(parsed, {'who': 'you'})
|
|
Hey you!
|
|
|
|
Python 3
|
|
--------
|
|
|
|
Pystache has supported Python 3 since version 0.5.1. Pystache behaves
|
|
slightly differently between Python 2 and 3, as follows:
|
|
|
|
- In Python 2, the default html-escape function ``cgi.escape()`` does
|
|
not escape single quotes. 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 defaults by passing in the encodings explicitly (e.g.
|
|
to the ``Renderer`` class).
|
|
|
|
Unicode
|
|
-------
|
|
|
|
This section describes how Pystache handles unicode, strings, and
|
|
encodings.
|
|
|
|
Internally, Pystache uses `only unicode
|
|
strings <http://docs.python.org/howto/unicode.html#tips-for-writing-unicode-aware-programs>`__
|
|
(``str`` in Python 3 and ``unicode`` in Python 2). For input, Pystache
|
|
accepts both unicode strings and byte strings (``bytes`` in Python 3 and
|
|
``str`` in Python 2). For output, Pystache's template rendering methods
|
|
return only unicode.
|
|
|
|
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`` 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``.
|
|
|
|
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.
|
|
|
|
Develop
|
|
-------
|
|
|
|
To test from a source distribution (without installing)--
|
|
|
|
::
|
|
|
|
python test_pystache.py
|
|
|
|
To test Pystache with multiple versions of Python (with a single
|
|
command!), you can use `tox <http://pypi.python.org/pypi/tox>`__:
|
|
|
|
::
|
|
|
|
pip install 'virtualenv<1.8' # Version 1.8 dropped support for Python 2.4.
|
|
pip install 'tox<1.4' # Version 1.4 dropped support for Python 2.4.
|
|
tox
|
|
|
|
If you do not have all Python versions listed in ``tox.ini``--
|
|
|
|
::
|
|
|
|
tox -e py26,py32 # for example
|
|
|
|
The source distribution tests also include doctests and tests from the
|
|
Mustache spec. To include tests from the Mustache spec in your test
|
|
runs:
|
|
|
|
::
|
|
|
|
git submodule init
|
|
git submodule update
|
|
|
|
The test harness parses the spec's (more human-readable) yaml files if
|
|
`PyYAML <http://pypi.python.org/pypi/PyYAML>`__ is present. Otherwise,
|
|
it parses the json files. To install PyYAML--
|
|
|
|
::
|
|
|
|
pip install pyyaml
|
|
|
|
To run a subset of the tests, you can use
|
|
`nose <http://somethingaboutorange.com/mrl/projects/nose/0.11.1/testing.html>`__:
|
|
|
|
::
|
|
|
|
pip install nose
|
|
nosetests --tests pystache/tests/test_context.py:GetValueTests.test_dictionary__key_present
|
|
|
|
Using Python 3 with Pystache from source
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Pystache is written in Python 2 and must be converted to Python 3 prior
|
|
to using it with Python 3. The installation process (and tox) do this
|
|
automatically.
|
|
|
|
To convert the code to Python 3 manually (while using Python 3)--
|
|
|
|
::
|
|
|
|
python setup.py build
|
|
|
|
This writes the converted code to a subdirectory called ``build``. By
|
|
design, Python 3 builds
|
|
`cannot <https://bitbucket.org/tarek/distribute/issue/292/allow-use_2to3-with-python-2>`__
|
|
be created from Python 2.
|
|
|
|
To convert the code without using setup.py, you can use
|
|
`2to3 <http://docs.python.org/library/2to3.html>`__ as follows (two
|
|
steps)--
|
|
|
|
::
|
|
|
|
2to3 --write --nobackups --no-diffs --doctests_only pystache
|
|
2to3 --write --nobackups --no-diffs pystache
|
|
|
|
This converts the code (and doctests) in place.
|
|
|
|
To ``import pystache`` from a source distribution while using Python 3,
|
|
be sure that you are importing from a directory containing a converted
|
|
version of the code (e.g. from the ``build`` directory after
|
|
converting), and not from the original (unconverted) source directory.
|
|
Otherwise, you will get a syntax error. You can help prevent this by not
|
|
running the Python IDE from the project directory when importing
|
|
Pystache while using Python 3.
|
|
|
|
Mailing List
|
|
------------
|
|
|
|
There is a `mailing list <http://librelist.com/browser/pystache/>`__.
|
|
Note that there is a bit of a delay between posting a message and seeing
|
|
it appear in the mailing list archive.
|
|
|
|
Credits
|
|
-------
|
|
|
|
::
|
|
|
|
>>> context = { 'author': 'Chris Wanstrath', 'maintainer': 'Chris Jerdonek' }
|
|
>>> print pystache.render("Author: {{author}}\nMaintainer: {{maintainer}}", context)
|
|
Author: Chris Wanstrath
|
|
Maintainer: Chris Jerdonek
|
|
|
|
Pystache logo by `David Phillips <http://davidphillips.us/>`__ is
|
|
licensed under a `Creative Commons Attribution-ShareAlike 3.0 Unported
|
|
License <http://creativecommons.org/licenses/by-sa/3.0/deed.en_US>`__.
|
|
|image0|
|
|
|
|
History
|
|
=======
|
|
|
|
**Note:** Official support for Python 2.4 will end with Pystache version
|
|
0.6.0.
|
|
|
|
0.5.4 (2014-07-11)
|
|
------------------
|
|
|
|
- Bugfix: made test with filenames OS agnostic (issue #162).
|
|
|
|
0.5.3 (2012-11-03)
|
|
------------------
|
|
|
|
- Added ability to customize string coercion (e.g. to have None render
|
|
as ``''``) (issue #130).
|
|
- Added Renderer.render\_name() to render a template by name (issue
|
|
#122).
|
|
- Added TemplateSpec.template\_path to specify an absolute path to a
|
|
template (issue #41).
|
|
- Added option of raising errors on missing tags/partials:
|
|
``Renderer(missing_tags='strict')`` (issue #110).
|
|
- Added support for finding and loading templates by file name in
|
|
addition to by template name (issue #127). [xgecko]
|
|
- Added a ``parse()`` function that yields a printable, pre-compiled
|
|
parse tree.
|
|
- Added support for rendering pre-compiled templates.
|
|
- Added Python 3.3 to the list of supported versions.
|
|
- Added support for `PyPy <http://pypy.org/>`__ (issue #125).
|
|
- Added support for `Travis CI <http://travis-ci.org>`__ (issue #124).
|
|
[msabramo]
|
|
- Bugfix: ``defaults.DELIMITERS`` can now be changed at runtime (issue
|
|
#135). [bennoleslie]
|
|
- Bugfix: exceptions raised from a property are no longer swallowed
|
|
when getting a key from a context stack (issue #110).
|
|
- Bugfix: lambda section values can now return non-ascii, non-unicode
|
|
strings (issue #118).
|
|
- Bugfix: allow ``test_pystache.py`` and ``tox`` to pass when run from
|
|
a downloaded sdist (i.e. without the spec test directory).
|
|
- Convert HISTORY and README files from reST to Markdown.
|
|
- More robust handling of byte strings in Python 3.
|
|
- Added Creative Commons license for David Phillips's logo.
|
|
|
|
0.5.2 (2012-05-03)
|
|
------------------
|
|
|
|
- Added support for dot notation and version 1.1.2 of the spec (issue
|
|
#99). [rbp]
|
|
- Missing partials now render as empty string per latest version of
|
|
spec (issue #115).
|
|
- Bugfix: falsey values now coerced to strings using str().
|
|
- Bugfix: lambda return values for sections no longer pushed onto
|
|
context stack (issue #113).
|
|
- Bugfix: lists of lambdas for sections were not rendered (issue #114).
|
|
|
|
0.5.1 (2012-04-24)
|
|
------------------
|
|
|
|
- Added support for Python 3.1 and 3.2.
|
|
- Added tox support to test multiple Python versions.
|
|
- Added test script entry point: pystache-test.
|
|
- Added \_\_version\_\_ package attribute.
|
|
- Test harness now supports both YAML and JSON forms of Mustache spec.
|
|
- Test harness no longer requires nose.
|
|
|
|
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).
|
|
|
|
Highlights:
|
|
|
|
- Pystache now passes all tests in version 1.0.3 of the `Mustache
|
|
spec <https://github.com/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 <https://github.com/defunkt/pystache/issues/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
|
|
|
|
License
|
|
=======
|
|
|
|
Copyright (C) 2012 Chris Jerdonek. All rights reserved.
|
|
|
|
Copyright (c) 2009 Chris Wanstrath
|
|
|
|
Permission is hereby granted, free of charge, to any person obtaining a
|
|
copy of this software and associated documentation files (the
|
|
"Software"), to deal in the Software without restriction, including
|
|
without limitation the rights to use, copy, modify, merge, publish,
|
|
distribute, sublicense, and/or sell copies of the Software, and to
|
|
permit persons to whom the Software is furnished to do so, subject to
|
|
the following conditions:
|
|
|
|
The above copyright notice and this permission notice shall be included
|
|
in all copies or substantial portions of the Software.
|
|
|
|
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
|
|
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
|
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
|
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
|
|
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
|
|
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
|
|
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
|
|
|
.. |image0| image:: http://i.creativecommons.org/l/by-sa/3.0/88x31.png
|