{"body":"Pystache\r\n========\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n![](https://raw.github.com/defunkt/pystache/master/gh/images/logo_phillips.png \"mustachioed, monocled snake by David Phillips\")\r\n\r\n![](https://secure.travis-ci.org/defunkt/pystache.png)\r\n\r\n[Pystache](https://github.com/defunkt/pystache) is a Python\r\nimplementation of [Mustache](http://mustache.github.com/). Mustache is a\r\nframework-agnostic, logic-free templating system inspired by\r\n[ctemplate](http://code.google.com/p/google-ctemplate/) and\r\n[et](http://www.ivan.fomichev.name/2008/05/erlang-template-engine-prototype.html).\r\nLike ctemplate, Mustache \"emphasizes separating logic from presentation:\r\nit is impossible to embed application logic in this template language.\"\r\n\r\nThe [mustache(5)](http://mustache.github.com/mustache.5.html) man page\r\nprovides a good introduction to Mustache's syntax. For a more complete\r\n(and more current) description of Mustache's behavior, see the official\r\n[Mustache spec](https://github.com/mustache/spec).\r\n\r\nPystache is [semantically versioned](http://semver.org) and can be found\r\non [PyPI](http://pypi.python.org/pypi/pystache). This version of\r\nPystache passes all tests in [version\r\n1.1.2](https://github.com/mustache/spec/tree/v1.1.2) of the spec.\r\n\r\n\r\nRequirements\r\n------------\r\n\r\nPystache is tested with--\r\n\r\n- Python 2.4 (requires simplejson [version\r\n 2.0.9](http://pypi.python.org/pypi/simplejson/2.0.9) or earlier)\r\n- Python 2.5 (requires\r\n [simplejson](http://pypi.python.org/pypi/simplejson/))\r\n- Python 2.6\r\n- Python 2.7\r\n- Python 3.1\r\n- Python 3.2\r\n- Python 3.3\r\n- [PyPy](http://pypy.org/)\r\n\r\n[Distribute](http://packages.python.org/distribute/) (the setuptools fork)\r\nis recommended over [setuptools](http://pypi.python.org/pypi/setuptools),\r\nand is required in some cases (e.g. for Python 3 support).\r\nIf you use [pip](http://www.pip-installer.org/), you probably already satisfy\r\nthis requirement.\r\n\r\nJSON support is needed only for the command-line interface and to run\r\nthe spec tests. We require simplejson for earlier versions of Python\r\nsince Python's [json](http://docs.python.org/library/json.html) module\r\nwas added in Python 2.6.\r\n\r\nFor Python 2.4 we require an earlier version of simplejson since\r\nsimplejson stopped officially supporting Python 2.4 in simplejson\r\nversion 2.1.0. Earlier versions of simplejson can be installed manually,\r\nas follows:\r\n\r\n pip install 'simplejson<2.1.0'\r\n\r\nInstall It\r\n----------\r\n\r\n pip install pystache\r\n\r\nAnd test it--\r\n\r\n pystache-test\r\n\r\nTo install and test from source (e.g. from GitHub), see the Develop\r\nsection.\r\n\r\nUse It\r\n------\r\n\r\n >>> import pystache\r\n >>> print pystache.render('Hi {{person}}!', {'person': 'Mom'})\r\n Hi Mom!\r\n\r\nYou can also create dedicated view classes to hold your view logic.\r\n\r\nHere's your view class (in .../examples/readme.py):\r\n\r\n class SayHello(object):\r\n def to(self):\r\n return \"Pizza\"\r\n\r\nInstantiating like so:\r\n\r\n >>> from pystache.tests.examples.readme import SayHello\r\n >>> hello = SayHello()\r\n\r\nThen your template, say\\_hello.mustache (by default in the same\r\ndirectory as your class definition):\r\n\r\n Hello, {{to}}!\r\n\r\nPull it together:\r\n\r\n >>> renderer = pystache.Renderer()\r\n >>> print renderer.render(hello)\r\n Hello, Pizza!\r\n\r\nFor greater control over rendering (e.g. to specify a custom template\r\ndirectory), use the `Renderer` class like above. One can pass attributes\r\nto the Renderer class constructor or set them on a Renderer instance. To\r\ncustomize template loading on a per-view basis, subclass `TemplateSpec`.\r\nSee the docstrings of the\r\n[Renderer](https://github.com/defunkt/pystache/blob/master/pystache/renderer.py)\r\nclass and\r\n[TemplateSpec](https://github.com/defunkt/pystache/blob/master/pystache/template_spec.py)\r\nclass for more information.\r\n\r\nYou can also pre-parse a template:\r\n\r\n >>> parsed = pystache.parse(u\"Hey {{#who}}{{.}}!{{/who}}\")\r\n >>> print parsed\r\n [u'Hey ', _SectionNode(key=u'who', index_begin=12, index_end=18, parsed=[_EscapeNode(key=u'.'), u'!'])]\r\n\r\nAnd then:\r\n\r\n >>> print renderer.render(parsed, {'who': 'Pops'})\r\n Hey Pops!\r\n >>> print renderer.render(parsed, {'who': 'you'})\r\n Hey you!\r\n\r\nPython 3\r\n--------\r\n\r\nPystache has supported Python 3 since version 0.5.1. Pystache behaves\r\nslightly differently between Python 2 and 3, as follows:\r\n\r\n- In Python 2, the default html-escape function `cgi.escape()` does\r\n not escape single quotes. In Python 3, the default escape function\r\n `html.escape()` does escape single quotes.\r\n- In both Python 2 and 3, the string and file encodings default to\r\n `sys.getdefaultencoding()`. However, this function can return\r\n different values under Python 2 and 3, even when run from the same\r\n system. Check your own system for the behavior on your system, or do\r\n not rely on the defaults by passing in the encodings explicitly\r\n (e.g. to the `Renderer` class).\r\n\r\nUnicode\r\n-------\r\n\r\nThis section describes how Pystache handles unicode, strings, and\r\nencodings.\r\n\r\nInternally, Pystache uses [only unicode\r\nstrings](http://docs.python.org/howto/unicode.html#tips-for-writing-unicode-aware-programs)\r\n(`str` in Python 3 and `unicode` in Python 2). For input, Pystache\r\naccepts both unicode strings and byte strings (`bytes` in Python 3 and\r\n`str` in Python 2). For output, Pystache's template rendering methods\r\nreturn only unicode.\r\n\r\nPystache's `Renderer` class supports a number of attributes to control\r\nhow Pystache converts byte strings to unicode on input. These include\r\nthe `file_encoding`, `string_encoding`, and `decode_errors` attributes.\r\n\r\nThe `file_encoding` attribute is the encoding the renderer uses to\r\nconvert to unicode any files read from the file system. Similarly,\r\n`string_encoding` is the encoding the renderer uses to convert any other\r\nbyte strings encountered during the rendering process into unicode (e.g.\r\ncontext values that are encoded byte strings).\r\n\r\nThe `decode_errors` attribute is what the renderer passes as the\r\n`errors` argument to Python's built-in unicode-decoding function\r\n(`str()` in Python 3 and `unicode()` in Python 2). The valid values for\r\nthis argument are `strict`, `ignore`, and `replace`.\r\n\r\nEach of these attributes can be set via the `Renderer` class's\r\nconstructor using a keyword argument of the same name. See the Renderer\r\nclass's docstrings for further details. In addition, the `file_encoding`\r\nattribute can be controlled on a per-view basis by subclassing the\r\n`TemplateSpec` class. When not specified explicitly, these attributes\r\ndefault to values set in Pystache's `defaults` module.\r\n\r\nDevelop\r\n-------\r\n\r\nTo test from a source distribution (without installing)--\r\n\r\n python test_pystache.py\r\n\r\nTo test Pystache with multiple versions of Python (with a single\r\ncommand!), you can use [tox](http://pypi.python.org/pypi/tox):\r\n\r\n pip install 'virtualenv<1.8' # Version 1.8 dropped support for Python 2.4.\r\n pip install 'tox<1.4' # Version 1.4 dropped support for Python 2.4.\r\n tox\r\n\r\nIf you do not have all Python versions listed in `tox.ini`--\r\n\r\n tox -e py26,py32 # for example\r\n\r\nThe source distribution tests also include doctests and tests from the\r\nMustache spec. To include tests from the Mustache spec in your test\r\nruns:\r\n\r\n git submodule init\r\n git submodule update\r\n\r\nThe test harness parses the spec's (more human-readable) yaml files if\r\n[PyYAML](http://pypi.python.org/pypi/PyYAML) is present. Otherwise, it\r\nparses the json files. To install PyYAML--\r\n\r\n pip install pyyaml\r\n\r\nTo run a subset of the tests, you can use\r\n[nose](http://somethingaboutorange.com/mrl/projects/nose/0.11.1/testing.html):\r\n\r\n pip install nose\r\n nosetests --tests pystache/tests/test_context.py:GetValueTests.test_dictionary__key_present\r\n\r\n### Using Python 3 with Pystache from source\r\n\r\nPystache is written in Python 2 and must be converted to Python 3 prior to\r\nusing it with Python 3. The installation process (and tox) do this\r\nautomatically.\r\n\r\nTo convert the code to Python 3 manually (while using Python 3)--\r\n\r\n python setup.py build\r\n\r\nThis writes the converted code to a subdirectory called `build`.\r\nBy design, Python 3 builds\r\n[cannot](https://bitbucket.org/tarek/distribute/issue/292/allow-use_2to3-with-python-2)\r\nbe created from Python 2.\r\n\r\nTo convert the code without using setup.py, you can use\r\n[2to3](http://docs.python.org/library/2to3.html) as follows (two steps)--\r\n\r\n 2to3 --write --nobackups --no-diffs --doctests_only pystache\r\n 2to3 --write --nobackups --no-diffs pystache\r\n\r\nThis converts the code (and doctests) in place.\r\n\r\nTo `import pystache` from a source distribution while using Python 3, be\r\nsure that you are importing from a directory containing a converted\r\nversion of the code (e.g. from the `build` directory after converting),\r\nand not from the original (unconverted) source directory. Otherwise, you will\r\nget a syntax error. You can help prevent this by not running the Python\r\nIDE from the project directory when importing Pystache while using Python 3.\r\n\r\n\r\nMailing List\r\n------------\r\n\r\nThere is a [mailing list](http://librelist.com/browser/pystache/). Note\r\nthat there is a bit of a delay between posting a message and seeing it\r\nappear in the mailing list archive.\r\n\r\nCredits\r\n-------\r\n\r\n >>> context = { 'author': 'Chris Wanstrath', 'maintainer': 'Chris Jerdonek' }\r\n >>> print pystache.render(\"Author: {{author}}\\nMaintainer: {{maintainer}}\", context)\r\n Author: Chris Wanstrath\r\n Maintainer: Chris Jerdonek\r\n\r\nPystache logo by [David Phillips](http://davidphillips.us/) is licensed\r\nunder a [Creative Commons Attribution-ShareAlike 3.0 Unported\r\nLicense](http://creativecommons.org/licenses/by-sa/3.0/deed.en_US).\r\n![](http://i.creativecommons.org/l/by-sa/3.0/88x31.png \"Creative\r\nCommons Attribution-ShareAlike 3.0 Unported License\")\r\n","tagline":"Mustache in Python","google":"","note":"Don't delete this file! It's used internally to help with page regeneration.","name":"Pystache"}