Table Of Contents
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 no C-compiler is available and you are using Python 2.4 the ctypes module should be installed.
If you don’t have a working C compiler and you are trying to install the source release you will get a compiler error. This however can be circumvented by passing the --without-speedups command line argument to the setup script.
For more details about that have a look at the Disable the speedups Module section below.
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:
sudo easy_install Jinja2
sudo 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¶
- Download the most recent tarball from the download page
- Unpack the tarball
- sudo python setup.py install
Note that the last command will automatically download and install setuptools if you don’t already have it installed. This requires a working internet connection.
This will install Jinja2 into your Python installation’s site-packages directory.
Installing the development version¶
- Install mercurial
- hg clone http://dev.pocoo.org/hg/jinja2-main jinja2
- cd jinja2
- ln -s 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 setuptools in development mode. This also has the advantage that the C extensions are compiled.
Alternative you can use easy_install to install the current development snapshot:
sudo easy_install Jinja2==dev
Or the new pip command:
sudo pip install Jinja2==dev
Disable the speedups Module¶
By default Jinja2 will try to compile the speedups module. This of course 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.
You can disable the speedups extension when installing using the --without-speedups flag:
sudo python setup.py install --without-speedups
You can also pass this parameter to easy_install or pip.
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 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 jinja2 import Template
>>> template = Template('Hello {{ name }}!')
>>> template.render(name='John Doe')
u'Hello John Doe!'
By creating an instance of Template you get back a new template object that provides a method called 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.