api.rst

API

jinja2

This document describes the API to Jinja2 and not the template language. It will be most useful as reference to those implementing the template interface to the application and not those who are creating Jinja2 templates.

Basics

Jinja2 uses a central object called the template Environment. Instances of this class are used to store the configuration, global objects and are used to load templates from the file system or other locations. Even if you are creating templates from string by using the constructor of Template class, an environment is created automatically for you.

Most applications will create one Environment object on application initialization and use that to load templates. In some cases it's however useful to have multiple environments side by side, if different configurations are in use.

The simplest way to configure Jinja2 to load templates for your application looks roughly like this:

from jinja2 import Environment, PackageLoader
env = Environment(loader=PackageLoader('yourapplication', 'templates'))

This will create a template environment with the default settings and a loader that looks up the templates in the templates folder inside the yourapplication python package. Different loaders are available and you can also write your own if you want to load templates from a database or other resources.

To load a template from this environment you just have to call the get_template method which then returns the loaded Template:

template = env.get_template('mytemplate.html')

To render it with some variables, just call the render method:

print template.render(the='variables', go='here')

High Level API

jinja2.environment.Environment

shared

If a template was created by using the Template constructor an environment is created automatically. These environments are created as shared environments which means that multiple templates may have the same anonymous environment. For all shared environments this attribute is True, else False.

sandboxed

If the environment is sandboxed this attribute is True. For the sandbox mode have a look at the documentation for the ~jinja2.sandbox.SandboxedEnvironment.

filters

A dict of filters for this environment. As long as no template was loaded it's safe to add new filters or remove old. For custom filters see writing-filters.

tests

A dict of test functions for this environment. As long as no template was loaded it's safe to modify this dict. For custom tests see writing-tests.

globals

A dict of global variables. These variables are always available in a template and (if the optimizer is enabled) may not be overridden by templates. As long as no template was loaded it's safe to modify this dict. For more details see global-namespace.

jinja2.Template

globals

foo

name

foo

jinja2.environment.TemplateStream

Undefined Types

These classes can be used as undefined types. The Environment constructor takes an undefined parameter that can be one of those classes or a custom subclass of Undefined. Whenever the template engine is unable to look up a name or access an attribute one of those objects is created and returned. Some operations on undefined values are then allowed, others fail.

The closest to regular Python behavior is the StrictUndefined which disallows all operations beside testing if it's an undefined object.

jinja2.runtime.Undefined

jinja2.runtime.DebugUndefined

jinja2.runtime.StrictUndefined

The Context

jinja2.runtime.Context

parent

A dict of read only, global variables the template looks up. These can either come from another Context, from the Environment.globals or Template.globals. It must not be altered.

vars

The template local variables. This list contains environment and context functions from the parent scope as well as local modifications and exported variables from the template. The template will modify this dict during template evaluation but filters and context functions are not allowed to modify it.

environment

The environment that loaded the template.

exported_vars

This set contains all the names the template exports. The values for the names are in the vars dict. In order to get a copy of the exported variables as dict, get_exported can be used.

name

The load name of the template owning this context.

blocks

A dict with the current mapping of blocks in the template. The keys in this dict are the names of the blocks, and the values a list of blocks registered. The last item in each list is the current active block (latest in the inheritance chain).

Loaders

Loaders are responsible for loading templates from a resource such as the file system. The environment will keep the compiled modules in memory like Python's sys.modules. Unlike sys.modules however this cache is limited in size by default and templates are automatically reloaded. All loaders are subclasses of BaseLoader. If you want to create your

own loader, subclass BaseLoader and override get_source.

jinja2.loaders.BaseLoader

Here a list of the builtin loaders Jinja2 provides:

jinja2.loaders.FileSystemLoader

jinja2.loaders.PackageLoader

jinja2.loaders.DictLoader

jinja2.loaders.FunctionLoader

jinja2.loaders.PrefixLoader

jinja2.loaders.ChoiceLoader

Utilities

These helper functions and classes are useful if you add custom filters or functions to a Jinja2 environment.

jinja2.filters.environmentfilter

jinja2.filters.contextfilter

jinja2.utils.environmentfunction

jinja2.utils.contextfunction

escape(s)

Convert the characters &, <, >, and " in string s to HTML-safe sequences. Use this if you need to display text that might contain such characters in HTML. This function will not escaped objects that do have an HTML representation such as already escaped data.

jinja2.utils.clear_caches

jinja2.utils.Markup

Exceptions

jinja2.exceptions.TemplateError

jinja2.exceptions.UndefinedError

jinja2.exceptions.TemplateNotFound

jinja2.exceptions.TemplateSyntaxError

jinja2.exceptions.TemplateAssertionError

Custom Filters

Custom filters are just regular Python functions that take the left side of the filter as first argument and the the arguments passed to the filter as extra arguments or keyword arguments.

For example in the filter {{ 42|myfilter(23) }} the function would be called with myfilter(42, 23). Here for example a simple filter that can be applied to datetime objects to format them:

def datetimeformat(value, format='%H:%M / %d-%m-%Y'):
    return value.strftime(format)

You can register it on the template environment by updating the ~Environment.filters dict on the environment:

environment.filters['datetimeformat'] = datetimeformat

Inside the template it can then be used as follows:

jinja

written on: {{ article.pub_datedatetimeformat('%d-%m-%Y') }}

Filters can also be passed the current template context or environment. This is useful if a filters wants to return an undefined value or check the current ~Environment.autoescape setting. For this purpose two decorators exist: environmentfilter and contextfilter.

Here a small example filter that breaks a text into HTML line breaks and paragraphs and marks the return value as safe HTML string if autoescaping is enabled:

import re
from jinja2 import environmentfilter, Markup, escape

_paragraph_re = re.compile(r'(?:\r\n|\r|\n){2,}')

@environmentfilter
def nl2br(environment, value):
    result = u'\n\n'.join(u'<p>%s</p>' % p.replace('\n', '<br>\n')
                          for p in _paragraph_re.split(escape(value)))
    if environment.autoescape:
        result = Markup(result)
    return result

Context filters work the same just that the first argument is the current active Context rather then the environment.

Custom Tests

Tests work like filters just that there is no way for a filter to get access to the environment or context and that they can't be chained. The return value of a filter should be True or False. The purpose of a filter is to give the template designers the possibility to perform type and conformability checks.

Here a simple filter that checks if a variable is a prime number:

import math

def is_prime(n):
    if n == 2:
        return True
    for i in xrange(2, int(math.ceil(math.sqrt(n))) + 1):
        if n % i == 0:
            return False
    return True

You can register it on the template environment by updating the ~Environment.tests dict on the environment:

environment.tests['prime'] = is_prime

A template designer can then use the test like this:

jinja

{% if 42 is prime %}

42 is a prime number

{% else %}

42 is not a prime number

{% endif %}

The Global Namespace

Variables stored in the Environment.globals or Template.globals dicts are special as they are available for imported templates too and will be used by the optimizer in future releases to evaluates parts of the template at compile time. This is the place where you can put variables and functions that should be available all the time.