| Introduction |
| ============ |
| |
| This is the documentation for the Jinja2 general purpose templating language. |
| Jinja2 is a library for Python 2.4 and onwards that is designed to be flexible, |
| fast and secure. |
| |
| If you have any exposure to other text-based template languages, such as Smarty or |
| Django, you should feel right at home with Jinja2. It's both designer and |
| developer friendly by sticking to Python's principles and adding functionality |
| useful for templating environments. |
| |
| The key-features are... |
| |
| - ... **configurable syntax**. If you are generating LaTeX or other formats |
| with Jinja2 you can change the delimiters to something that integrates better |
| into the LaTeX markup. |
| |
| - ... **fast**. While performance is not the primarily target of Jinja2 it's |
| surprisingly fast. The overhead compared to regular Python code was reduced |
| to the very minimum. |
| |
| - ... **easy to debug**. Jinja2 integrates directly into the python traceback |
| system which allows you to debug Jinja2 templates with regular python |
| debugging helpers. |
| |
| - ... **secure**. It's possible to evaluate untrusted template code if the |
| optional sandbox is enabled. This allows Jinja2 to be used as templating |
| language for applications where users may modify the template design. |
| |
| |
| Prerequisites |
| ------------- |
| |
| Jinja2 needs at least **Python 2.4** to run. Additionally a working C-compiler |
| that can create python extensions should be installed for the debugger if you |
| are using Python 2.4. |
| |
| If you don't have a working C-compiler and you are trying to install the source |
| release with the debugsupport you will get a compiler error. |
| |
| .. _ctypes: http://python.net/crew/theller/ctypes/ |
| |
| |
| Installation |
| ------------ |
| |
| You have multiple ways to install Jinja2. If you are unsure what to do, go |
| with the Python egg or tarball. |
| |
| As a Python egg (via easy_install) |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| You can install the most recent Jinja2 version using `easy_install`_ or `pip`_:: |
| |
| easy_install Jinja2 |
| pip install Jinja2 |
| |
| This will install a Jinja2 egg in your Python installation's site-packages |
| directory. |
| |
| (If you are installing from the windows command line omit the `sudo` and make |
| sure to run the command as user with administrator rights) |
| |
| From the tarball release |
| ~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| 1. Download the most recent tarball from the `download page`_ |
| 2. Unpack the tarball |
| 3. ``sudo python setup.py install`` |
| |
| Note that you either have to have setuptools or `distribute`_ installed, |
| the latter is preferred. |
| |
| This will install Jinja2 into your Python installation's site-packages directory. |
| |
| .. _distribute: http://pypi.python.org/pypi/distribute |
| |
| Installing the development version |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| 1. Install `git`_ |
| 2. ``git clone git://github.com/mitsuhiko/ambari_jinja2.git`` |
| 3. ``cd ambari_jinja2`` |
| 4. ``ln -s ambari_jinja2 /usr/lib/python2.X/site-packages`` |
| |
| As an alternative to steps 4 you can also do ``python setup.py develop`` |
| which will install the package via distribute in development mode. This also |
| has the advantage that the C extensions are compiled. |
| |
| .. _download page: http://pypi.python.org/pypi/Jinja2 |
| .. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools |
| .. _easy_install: http://peak.telecommunity.com/DevCenter/EasyInstall |
| .. _pip: http://pypi.python.org/pypi/pip |
| .. _git: http://git-scm.org/ |
| |
| |
| More Speed with MarkupSafe |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| As of version 2.5.1 Jinja2 will check for an installed `MarkupSafe`_ |
| module. If it can find it, it will use the Markup class of that module |
| instead of the one that comes with Jinja2. `MarkupSafe` replaces the |
| older speedups module that came with Jinja2 and has the advantage that is |
| has a better setup script and will automatically attempt to install the C |
| version and nicely fall back to a pure Python implementation if that is |
| not possible. |
| |
| The C implementation of MarkupSafe is much faster and recommended when |
| using Jinja2 with autoescaping. |
| |
| .. _MarkupSafe: http://pypi.python.org/pypi/MarkupSafe |
| |
| |
| Enable the debug support Module |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| By default Jinja2 will not compile the debug support module. Enabling this |
| will fail if you don't have the Python headers or a working compiler. This |
| is often the case if you are installing Jinja2 from a windows machine. |
| |
| Because the debug support is only necessary for Python 2.4 you will not |
| have to do this unless you run 2.4:: |
| |
| sudo python setup.py --with-debugsupport install |
| |
| |
| Basic API Usage |
| --------------- |
| |
| This section gives you a brief introduction to the Python API for Jinja2 |
| templates. |
| |
| The most basic way to create a template and render it is through |
| :class:`~ambari_jinja2.Template`. This however is not the recommended way to |
| work with it if your templates are not loaded from strings but the file |
| system or another data source: |
| |
| >>> from ambari_jinja2 import Template |
| >>> template = Template('Hello {{ name }}!') |
| >>> template.render(name='John Doe') |
| u'Hello John Doe!' |
| |
| By creating an instance of :class:`~ambari_jinja2.Template` you get back a new template |
| object that provides a method called :meth:`~ambari_jinja2.Template.render` which when |
| called with a dict or keyword arguments expands the template. The dict |
| or keywords arguments passed to the template are the so-called "context" |
| of the template. |
| |
| What you can see here is that Jinja2 is using unicode internally and the |
| return value is an unicode string. So make sure that your application is |
| indeed using unicode internally. |
| |
| |
| Experimental Python 3 Support |
| ----------------------------- |
| |
| Jinja 2.3 brings experimental support for Python 3. It means that all |
| unittests pass on the new version, but there might still be small bugs in |
| there and behavior might be inconsistent. If you notice any bugs, please |
| provide feedback in the `Jinja bug tracker`_. |
| |
| Also please keep in mind that the documentation is written with Python 2 |
| in mind, you will have to adapt the shown code examples to Python 3 syntax |
| for yourself. |
| |
| |
| .. _Jinja bug tracker: http://github.com/mitsuhiko/ambari_jinja2/issues |