% Generated by Sphinx.
\def\sphinxdocclass{report}
\documentclass[a4paper,10pt,english]{sphinxmanual}
\usepackage[utf8]{inputenc}
\DeclareUnicodeCharacter{00A0}{\nobreakspace}
\usepackage[T1]{fontenc}
\usepackage{babel}
\usepackage{times}
\usepackage[Bjarne]{fncychap}
\usepackage{longtable}
\usepackage{sphinx}

\usepackage{palatino}
\definecolor{TitleColor}{rgb}{0.7,0,0}
\definecolor{InnerLinkColor}{rgb}{0.7,0,0}
\definecolor{OuterLinkColor}{rgb}{0.8,0,0}
\definecolor{VerbatimColor}{rgb}{0.985,0.985,0.985}
\definecolor{VerbatimBorderColor}{rgb}{0.8,0.8,0.8}


\title{Jinja2 Documentation}
\date{October 17, 2010}
\release{2.0}
\author{Armin Ronacher}
\newcommand{\sphinxlogo}{}
\renewcommand{\releasename}{Release}
\makeindex

\makeatletter
\def\PYG@reset{\let\PYG@it=\relax \let\PYG@bf=\relax%
    \let\PYG@ul=\relax \let\PYG@tc=\relax%
    \let\PYG@bc=\relax \let\PYG@ff=\relax}
\def\PYG@tok#1{\csname PYG@tok@#1\endcsname}
\def\PYG@toks#1+{\ifx\relax#1\empty\else%
    \PYG@tok{#1}\expandafter\PYG@toks\fi}
\def\PYG@do#1{\PYG@bc{\PYG@tc{\PYG@ul{%
    \PYG@it{\PYG@bf{\PYG@ff{#1}}}}}}}
\def\PYG#1#2{\PYG@reset\PYG@toks#1+\relax+\PYG@do{#2}}

\def\PYG@tok@gu{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.50,0.00,0.50}{##1}}}
\def\PYG@tok@gt{\def\PYG@tc##1{\textcolor[rgb]{0.67,0.00,0.00}{##1}}}
\def\PYG@tok@gs{\let\PYG@bf=\textbf}
\def\PYG@tok@gr{\def\PYG@tc##1{\textcolor[rgb]{0.67,0.00,0.00}{##1}}}
\def\PYG@tok@cm{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.67,0.67,0.67}{##1}}}
\def\PYG@tok@gp{\def\PYG@tc##1{\textcolor[rgb]{0.33,0.33,0.33}{##1}}}
\def\PYG@tok@m{\def\PYG@tc##1{\textcolor[rgb]{0.27,0.27,0.27}{##1}}}
\def\PYG@tok@mh{\def\PYG@tc##1{\textcolor[rgb]{0.27,0.27,0.27}{##1}}}
\def\PYG@tok@cs{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.31,0.31,0.31}{##1}}}
\def\PYG@tok@ge{\let\PYG@it=\textit}
\def\PYG@tok@gd{\def\PYG@tc##1{\textcolor[rgb]{0.67,0.00,0.00}{##1}}}
\def\PYG@tok@il{\def\PYG@tc##1{\textcolor[rgb]{0.27,0.27,0.27}{##1}}}
\def\PYG@tok@go{\def\PYG@tc##1{\textcolor[rgb]{0.53,0.53,0.53}{##1}}}
\def\PYG@tok@cp{\def\PYG@tc##1{\textcolor[rgb]{0.69,0.08,0.08}{##1}}}
\def\PYG@tok@gi{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.67,0.00}{##1}}}
\def\PYG@tok@gh{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.00,0.50}{##1}}}
\def\PYG@tok@ni{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.21,0.21,0.21}{##1}}}
\def\PYG@tok@nn{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.20,0.20,0.20}{##1}}}
\def\PYG@tok@na{\def\PYG@tc##1{\textcolor[rgb]{0.41,0.41,0.41}{##1}}}
\def\PYG@tok@nb{\def\PYG@tc##1{\textcolor[rgb]{0.20,0.20,0.20}{##1}}}
\def\PYG@tok@nc{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.20,0.20,0.20}{##1}}}
\def\PYG@tok@nd{\def\PYG@tc##1{\textcolor[rgb]{0.41,0.41,0.41}{##1}}}
\def\PYG@tok@si{\def\PYG@tc##1{\textcolor[rgb]{0.67,0.54,0.11}{##1}}}
\def\PYG@tok@nf{\def\PYG@tc##1{\textcolor[rgb]{0.20,0.20,0.20}{##1}}}
\def\PYG@tok@s2{\def\PYG@tc##1{\textcolor[rgb]{0.67,0.54,0.11}{##1}}}
\def\PYG@tok@nt{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.41,0.41,0.41}{##1}}}
\def\PYG@tok@s1{\def\PYG@tc##1{\textcolor[rgb]{0.67,0.54,0.11}{##1}}}
\def\PYG@tok@sh{\def\PYG@tc##1{\textcolor[rgb]{0.67,0.54,0.11}{##1}}}
\def\PYG@tok@ow{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.72,0.00,0.00}{##1}}}
\def\PYG@tok@sx{\def\PYG@tc##1{\textcolor[rgb]{0.67,0.54,0.11}{##1}}}
\def\PYG@tok@bp{\def\PYG@tc##1{\textcolor[rgb]{0.20,0.20,0.20}{##1}}}
\def\PYG@tok@c1{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.67,0.67,0.67}{##1}}}
\def\PYG@tok@kc{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.72,0.00,0.00}{##1}}}
\def\PYG@tok@c{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.67,0.67,0.67}{##1}}}
\def\PYG@tok@mf{\def\PYG@tc##1{\textcolor[rgb]{0.27,0.27,0.27}{##1}}}
\def\PYG@tok@err{\def\PYG@tc##1{\textcolor[rgb]{0.94,0.00,0.00}{##1}}\def\PYG@bc##1{\colorbox[rgb]{0.94,0.63,0.63}{##1}}}
\def\PYG@tok@kd{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.72,0.00,0.00}{##1}}}
\def\PYG@tok@ss{\def\PYG@tc##1{\textcolor[rgb]{0.67,0.54,0.11}{##1}}}
\def\PYG@tok@sr{\def\PYG@tc##1{\textcolor[rgb]{0.67,0.54,0.11}{##1}}}
\def\PYG@tok@mo{\def\PYG@tc##1{\textcolor[rgb]{0.27,0.27,0.27}{##1}}}
\def\PYG@tok@mi{\def\PYG@tc##1{\textcolor[rgb]{0.27,0.27,0.27}{##1}}}
\def\PYG@tok@kn{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.72,0.00,0.00}{##1}}}
\def\PYG@tok@kr{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.72,0.00,0.00}{##1}}}
\def\PYG@tok@s{\def\PYG@tc##1{\textcolor[rgb]{0.67,0.54,0.11}{##1}}}
\def\PYG@tok@kp{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.72,0.00,0.00}{##1}}}
\def\PYG@tok@kt{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.50,0.50,0.50}{##1}}}
\def\PYG@tok@sc{\def\PYG@tc##1{\textcolor[rgb]{0.67,0.54,0.11}{##1}}}
\def\PYG@tok@sb{\def\PYG@tc##1{\textcolor[rgb]{0.67,0.54,0.11}{##1}}}
\def\PYG@tok@k{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.72,0.00,0.00}{##1}}}
\def\PYG@tok@se{\def\PYG@tc##1{\textcolor[rgb]{0.67,0.54,0.11}{##1}}}
\def\PYG@tok@sd{\def\PYG@tc##1{\textcolor[rgb]{0.67,0.54,0.11}{##1}}}

\def\PYGZbs{\char`\\}
\def\PYGZus{\char`\_}
\def\PYGZob{\char`\{}
\def\PYGZcb{\char`\}}
\def\PYGZca{\char`\^}
% for compatibility with earlier versions
\def\PYGZat{@}
\def\PYGZlb{[}
\def\PYGZrb{]}
\makeatother

\begin{document}

\maketitle
\tableofcontents
\phantomsection\label{index::doc}



\chapter{Introduction}
\label{intro:introduction}\label{intro::doc}
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.


\section{Prerequisites}
\label{intro:prerequisites}
Jinja2 needs at least \textbf{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.


\section{Installation}
\label{intro:installation}\label{intro:ctypes}
You have multiple ways to install Jinja2.  If you are unsure what to do, go
with the Python egg or tarball.


\subsection{As a Python egg (via easy\_install)}
\label{intro:as-a-python-egg-via-easy-install}
You can install the most recent Jinja2 version using \href{http://peak.telecommunity.com/DevCenter/EasyInstall}{easy\_install} or \href{http://pypi.python.org/pypi/pip}{pip}:

\begin{Verbatim}[commandchars=@\[\]]
easy@_install Jinja2
pip install Jinja2
\end{Verbatim}

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 \emph{sudo} and make
sure to run the command as user with administrator rights)


\subsection{From the tarball release}
\label{intro:from-the-tarball-release}\begin{enumerate}
\item {} 
Download the most recent tarball from the \href{http://pypi.python.org/pypi/Jinja2}{download page}

\item {} 
Unpack the tarball

\item {} 
\code{sudo python setup.py install}

\end{enumerate}

Note that you either have to have setuptools or \href{http://pypi.python.org/pypi/distribute}{distribute} installed,
the latter is preferred.

This will install Jinja2 into your Python installation's site-packages directory.


\subsection{Installing the development version}
\label{intro:installing-the-development-version}\label{intro:distribute}\begin{enumerate}
\item {} 
Install \href{http://git-scm.org/}{git}

\item {} 
\code{git clone git://github.com/mitsuhiko/jinja2.git}

\item {} 
\code{cd jinja2}

\item {} 
\code{ln -s jinja2 /usr/lib/python2.X/site-packages}

\end{enumerate}

As an alternative to steps 4 you can also do \code{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.


\subsection{More Speed with MarkupSafe}
\label{intro:more-speed-with-markupsafe}\label{intro:git}
As of version 2.5.1 Jinja2 will check for an installed \href{http://pypi.python.org/pypi/MarkupSafe}{MarkupSafe}
module.  If it can find it, it will use the Markup class of that module
instead of the one that comes with Jinja2.  \emph{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.


\subsection{Enable the debug support Module}
\label{intro:markupsafe}\label{intro: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:

\begin{Verbatim}[commandchars=@\[\]]
sudo python setup.py --with-debugsupport install
\end{Verbatim}


\section{Basic API Usage}
\label{intro: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
{\hyperref[api:jinja2.Template]{\code{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:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{k+kn}{from} \PYG{n+nn}{jinja2} \PYG{k+kn}{import} \PYG{n}{Template}
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{template} \PYG{o}{=} \PYG{n}{Template}\PYG{p}{(}\PYG{l+s}{'}\PYG{l+s}{Hello \PYGZob{}\PYGZob{} name \PYGZcb{}\PYGZcb{}!}\PYG{l+s}{'}\PYG{p}{)}
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{template}\PYG{o}{.}\PYG{n}{render}\PYG{p}{(}\PYG{n}{name}\PYG{o}{=}\PYG{l+s}{'}\PYG{l+s}{John Doe}\PYG{l+s}{'}\PYG{p}{)}
\PYG{g+go}{u'Hello John Doe!'}
\end{Verbatim}

By creating an instance of {\hyperref[api:jinja2.Template]{\code{Template}}} you get back a new template
object that provides a method called {\hyperref[api:jinja2.Template.render]{\code{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.


\section{Experimental Python 3 Support}
\label{intro: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 \href{http://github.com/mitsuhiko/jinja2/issues}{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.


\chapter{API}
\label{api:api}\label{api::doc}\label{api:module-jinja2}\label{api:jinja-bug-tracker}\index{jinja2 (module)}
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.


\section{Basics}
\label{api:basics}
Jinja2 uses a central object called the template {\hyperref[api:jinja2.Environment]{\code{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 strings by using the constructor of
{\hyperref[api:jinja2.Template]{\code{Template}}} class, an environment is created automatically for you,
albeit a shared one.

Most applications will create one {\hyperref[api:jinja2.Environment]{\code{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:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{k+kn}{from} \PYG{n+nn}{jinja2} \PYG{k+kn}{import} \PYG{n}{Environment}\PYG{p}{,} \PYG{n}{PackageLoader}
\PYG{n}{env} \PYG{o}{=} \PYG{n}{Environment}\PYG{p}{(}\PYG{n}{loader}\PYG{o}{=}\PYG{n}{PackageLoader}\PYG{p}{(}\PYG{l+s}{'}\PYG{l+s}{yourapplication}\PYG{l+s}{'}\PYG{p}{,} \PYG{l+s}{'}\PYG{l+s}{templates}\PYG{l+s}{'}\PYG{p}{)}\PYG{p}{)}
\end{Verbatim}

This will create a template environment with the default settings and a
loader that looks up the templates in the \emph{templates} folder inside the
\emph{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
\code{get\_template()} method which then returns the loaded {\hyperref[api:jinja2.Template]{\code{Template}}}:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n}{template} \PYG{o}{=} \PYG{n}{env}\PYG{o}{.}\PYG{n}{get\PYGZus{}template}\PYG{p}{(}\PYG{l+s}{'}\PYG{l+s}{mytemplate.html}\PYG{l+s}{'}\PYG{p}{)}
\end{Verbatim}

To render it with some variables, just call the \code{render()} method:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{k}{print} \PYG{n}{template}\PYG{o}{.}\PYG{n}{render}\PYG{p}{(}\PYG{n}{the}\PYG{o}{=}\PYG{l+s}{'}\PYG{l+s}{variables}\PYG{l+s}{'}\PYG{p}{,} \PYG{n}{go}\PYG{o}{=}\PYG{l+s}{'}\PYG{l+s}{here}\PYG{l+s}{'}\PYG{p}{)}
\end{Verbatim}

Using a template loader rather then passing strings to {\hyperref[api:jinja2.Template]{\code{Template}}}
or {\hyperref[api:jinja2.Environment.from_string]{\code{Environment.from\_string()}}} has multiple advantages.  Besides being
a lot easier to use it also enables template inheritance.


\section{Unicode}
\label{api:unicode}
Jinja2 is using Unicode internally which means that you have to pass Unicode
objects to the render function or bytestrings that only consist of ASCII
characters.  Additionally newlines are normalized to one end of line
sequence which is per default UNIX style (\code{\textbackslash{}n}).

Python 2.x supports two ways of representing string objects.  One is the
\emph{str} type and the other is the \emph{unicode} type, both of which extend a type
called \emph{basestring}.  Unfortunately the default is \emph{str} which should not
be used to store text based information unless only ASCII characters are
used.  With Python 2.6 it is possible to make \emph{unicode} the default on a per
module level and with Python 3 it will be the default.

To explicitly use a Unicode string you have to prefix the string literal
with a \emph{u}: \code{u'Hänsel und Gretel sagen Hallo'}.  That way Python will
store the string as Unicode by decoding the string with the character
encoding from the current Python module.  If no encoding is specified this
defaults to `ASCII' which means that you can't use any non ASCII identifier.

To set a better module encoding add the following comment to the first or
second line of the Python module using the Unicode literal:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c}{\# -*- coding: utf-8 -*-}
\end{Verbatim}

We recommend utf-8 as Encoding for Python modules and templates as it's
possible to represent every Unicode character in utf-8 and because it's
backwards compatible to ASCII.  For Jinja2 the default encoding of templates
is assumed to be utf-8.

It is not possible to use Jinja2 to process non-Unicode data.  The reason
for this is that Jinja2 uses Unicode already on the language level.  For
example Jinja2 treats the non-breaking space as valid whitespace inside
expressions which requires knowledge of the encoding or operating on an
Unicode string.

For more details about Unicode in Python have a look at the excellent
\href{http://docs.python.org/dev/howto/unicode.html}{Unicode documentation}.

Another important thing is how Jinja2 is handling string literals in
templates.  A naive implementation would be using Unicode strings for
all string literals but it turned out in the past that this is problematic
as some libraries are typechecking against \emph{str} explicitly.  For example
\emph{datetime.strftime} does not accept Unicode arguments.  To not break it
completely Jinja2 is returning \emph{str} for strings that fit into ASCII and
for everything else \emph{unicode}:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{m} \PYG{o}{=} \PYG{n}{Template}\PYG{p}{(}\PYG{l+s}{u"}\PYG{l+s}{\PYGZob{}}\PYG{l+s+si}{\% s}\PYG{l+s}{et a, b = }\PYG{l+s}{'}\PYG{l+s}{foo}\PYG{l+s}{'}\PYG{l+s}{, }\PYG{l+s}{'}\PYG{l+s}{föö}\PYG{l+s}{'}\PYG{l+s}{ }\PYG{l+s}{\%}\PYG{l+s}{\PYGZcb{}}\PYG{l+s}{"}\PYG{p}{)}\PYG{o}{.}\PYG{n}{module}
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{m}\PYG{o}{.}\PYG{n}{a}
\PYG{g+go}{'foo'}
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{m}\PYG{o}{.}\PYG{n}{b}
\PYG{g+go}{u'f\PYGZbs{}xf6\PYGZbs{}xf6'}
\end{Verbatim}


\section{High Level API}
\label{api:unicode-documentation}\label{api:high-level-api}
The high-level API is the API you will use in the application to load and
render Jinja2 templates.  The {\hyperref[api:low-level-api]{\emph{Low Level API}}} on the other side is only
useful if you want to dig deeper into Jinja2 or {\hyperref[extensions:jinja-extensions]{\emph{develop extensions}}}.
\index{Environment (class in jinja2)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Environment}\pysiglinewithargsret{\strong{class }\code{jinja2.}\bfcode{Environment}}{\optional{\emph{options}}}{}
The core component of Jinja is the \emph{Environment}.  It contains
important shared variables like configuration, filters, tests,
globals and others.  Instances of this class may be modified if
they are not shared and if no template was loaded so far.
Modifications on environments after the first template was loaded
will lead to surprising effects and undefined behavior.

Here the possible initialization parameters:
\begin{quote}
\begin{description}
\item[{\emph{block\_start\_string}}] \leavevmode
The string marking the begin of a block.  Defaults to \code{'\{\%'}.

\item[{\emph{block\_end\_string}}] \leavevmode
The string marking the end of a block.  Defaults to \code{'\%\}'}.

\item[{\emph{variable\_start\_string}}] \leavevmode
The string marking the begin of a print statement.
Defaults to \code{'\{\{'}.

\item[{\emph{variable\_end\_string}}] \leavevmode
The string marking the end of a print statement.  Defaults to
\code{'\}\}'}.

\item[{\emph{comment\_start\_string}}] \leavevmode
The string marking the begin of a comment.  Defaults to \code{'\{\#'}.

\item[{\emph{comment\_end\_string}}] \leavevmode
The string marking the end of a comment.  Defaults to \code{'\#\}'}.

\item[{\emph{line\_statement\_prefix}}] \leavevmode
If given and a string, this will be used as prefix for line based
statements.  See also {\hyperref[templates:line-statements]{\emph{Line Statements}}}.

\item[{\emph{line\_comment\_prefix}}] \leavevmode
If given and a string, this will be used as prefix for line based
based comments.  See also {\hyperref[templates:line-statements]{\emph{Line Statements}}}.
New in version 2.2.
\item[{\emph{trim\_blocks}}] \leavevmode
If this is set to \code{True} the first newline after a block is
removed (block, not variable tag!).  Defaults to \emph{False}.

\item[{\emph{newline\_sequence}}] \leavevmode
The sequence that starts a newline.  Must be one of \code{'\textbackslash{}r'},
\code{'\textbackslash{}n'} or \code{'\textbackslash{}r\textbackslash{}n'}.  The default is \code{'\textbackslash{}n'} which is a
useful default for Linux and OS X systems as well as web
applications.

\item[{\emph{extensions}}] \leavevmode
List of Jinja extensions to use.  This can either be import paths
as strings or extension classes.  For more information have a
look at {\hyperref[extensions:jinja-extensions]{\emph{the extensions documentation}}}.

\item[{\emph{optimized}}] \leavevmode
should the optimizer be enabled?  Default is \emph{True}.

\item[{\emph{undefined}}] \leavevmode
{\hyperref[api:jinja2.Undefined]{\code{Undefined}}} or a subclass of it that is used to represent
undefined values in the template.

\item[{\emph{finalize}}] \leavevmode
A callable that can be used to process the result of a variable
expression before it is output.  For example one can convert
\emph{None} implicitly into an empty string here.

\item[{\emph{autoescape}}] \leavevmode
If set to true the XML/HTML autoescaping feature is enabled by
default.  For more details about auto escaping see
\code{Markup}.  As of Jinja 2.4 this can also
be a callable that is passed the template name and has to
return \emph{True} or \emph{False} depending on autoescape should be
enabled by default.
Changed in version 2.4: \emph{autoescape} can now be a function
\item[{\emph{loader}}] \leavevmode
The template loader for this environment.

\item[{\emph{cache\_size}}] \leavevmode
The size of the cache.  Per default this is \code{50} which means
that if more than 50 templates are loaded the loader will clean
out the least recently used template.  If the cache size is set to
\code{0} templates are recompiled all the time, if the cache size is
\code{-1} the cache will not be cleaned.

\item[{\emph{auto\_reload}}] \leavevmode
Some loaders load templates from locations where the template
sources may change (ie: file system or database).  If
\emph{auto\_reload} is set to \emph{True} (default) every time a template is
requested the loader checks if the source changed and if yes, it
will reload the template.  For higher performance it's possible to
disable that.

\item[{\emph{bytecode\_cache}}] \leavevmode
If set to a bytecode cache object, this object will provide a
cache for the internal Jinja bytecode so that templates don't
have to be parsed if they were not changed.

See {\hyperref[api:bytecode-cache]{\emph{Bytecode Cache}}} for more information.

\end{description}
\end{quote}
\index{shared (jinja2.Environment attribute)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Environment.shared}\pysigline{\bfcode{shared}}{}
If a template was created by using the {\hyperref[api:jinja2.Template]{\code{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 \emph{True}, else \emph{False}.

\end{fulllineitems}

\index{sandboxed (jinja2.Environment attribute)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Environment.sandboxed}\pysigline{\bfcode{sandboxed}}{}
If the environment is sandboxed this attribute is \emph{True}.  For the
sandbox mode have a look at the documentation for the
{\hyperref[sandbox:jinja2.sandbox.SandboxedEnvironment]{\code{SandboxedEnvironment}}}.

\end{fulllineitems}

\index{filters (jinja2.Environment attribute)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Environment.filters}\pysigline{\bfcode{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 {\hyperref[api:writing-filters]{\emph{Custom Filters}}}.  For valid filter names have a look at
{\hyperref[api:identifier-naming]{\emph{Notes on Identifiers}}}.

\end{fulllineitems}

\index{tests (jinja2.Environment attribute)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Environment.tests}\pysigline{\bfcode{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 {\hyperref[api:writing-tests]{\emph{Custom Tests}}}.  For valid test names have a look at
{\hyperref[api:identifier-naming]{\emph{Notes on Identifiers}}}.

\end{fulllineitems}

\index{globals (jinja2.Environment attribute)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Environment.globals}\pysigline{\bfcode{globals}}{}
A dict of global variables.  These variables are always available
in a template.  As long as no template was loaded it's safe
to modify this dict.  For more details see {\hyperref[api:global-namespace]{\emph{The Global Namespace}}}.
For valid object names have a look at {\hyperref[api:identifier-naming]{\emph{Notes on Identifiers}}}.

\end{fulllineitems}

\index{overlay() (jinja2.Environment method)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Environment.overlay}\pysiglinewithargsret{\bfcode{overlay}}{\optional{\emph{options}}}{}
Create a new overlay environment that shares all the data with the
current environment except of cache and the overridden attributes.
Extensions cannot be removed for an overlayed environment.  An overlayed
environment automatically gets all the extensions of the environment it
is linked to plus optional extra extensions.

Creating overlays should happen after the initial environment was set
up completely.  Not all attributes are truly linked, some are just
copied over so modifications on the original environment may not shine
through.

\end{fulllineitems}

\index{undefined() (jinja2.Environment method)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Environment.undefined}\pysiglinewithargsret{\bfcode{undefined}}{\optional{\emph{hint}, \emph{obj}, \emph{name}, \emph{exc}}}{}
Creates a new {\hyperref[api:jinja2.Undefined]{\code{Undefined}}} object for \emph{name}.  This is useful
for filters or functions that may return undefined objects for
some operations.  All parameters except of \emph{hint} should be provided
as keyword parameters for better readability.  The \emph{hint} is used as
error message for the exception if provided, otherwise the error
message will be generated from \emph{obj} and \emph{name} automatically.  The exception
provided as \emph{exc} is raised if something with the generated undefined
object is done that the undefined object does not allow.  The default
exception is {\hyperref[api:jinja2.UndefinedError]{\code{UndefinedError}}}.  If a \emph{hint} is provided the
\emph{name} may be ommited.

The most common way to create an undefined object is by providing
a name only:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{k}{return} \PYG{n}{environment}\PYG{o}{.}\PYG{n}{undefined}\PYG{p}{(}\PYG{n}{name}\PYG{o}{=}\PYG{l+s}{'}\PYG{l+s}{some\PYGZus{}name}\PYG{l+s}{'}\PYG{p}{)}
\end{Verbatim}

This means that the name \emph{some\_name} is not defined.  If the name
was from an attribute of an object it makes sense to tell the
undefined object the holder object to improve the error message:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{k}{if} \PYG{o+ow}{not} \PYG{n+nb}{hasattr}\PYG{p}{(}\PYG{n}{obj}\PYG{p}{,} \PYG{l+s}{'}\PYG{l+s}{attr}\PYG{l+s}{'}\PYG{p}{)}\PYG{p}{:}
    \PYG{k}{return} \PYG{n}{environment}\PYG{o}{.}\PYG{n}{undefined}\PYG{p}{(}\PYG{n}{obj}\PYG{o}{=}\PYG{n}{obj}\PYG{p}{,} \PYG{n}{name}\PYG{o}{=}\PYG{l+s}{'}\PYG{l+s}{attr}\PYG{l+s}{'}\PYG{p}{)}
\end{Verbatim}

For a more complex example you can provide a hint.  For example
the {\hyperref[templates:first]{\code{first()}}} filter creates an undefined object that way:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{k}{return} \PYG{n}{environment}\PYG{o}{.}\PYG{n}{undefined}\PYG{p}{(}\PYG{l+s}{'}\PYG{l+s}{no first item, sequence was empty}\PYG{l+s}{'}\PYG{p}{)}
\end{Verbatim}

If it the \emph{name} or \emph{obj} is known (for example because an attribute
was accessed) it shold be passed to the undefined object, even if
a custom \emph{hint} is provided.  This gives undefined objects the
possibility to enhance the error message.

\end{fulllineitems}

\index{from\_string() (jinja2.Environment method)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Environment.from_string}\pysiglinewithargsret{\bfcode{from\_string}}{\emph{source}, \emph{globals=None}, \emph{template\_class=None}}{}
Load a template from a string.  This parses the source given and
returns a {\hyperref[api:jinja2.Template]{\code{Template}}} object.

\end{fulllineitems}

\index{get\_template() (jinja2.Environment method)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Environment.get_template}\pysiglinewithargsret{\bfcode{get\_template}}{\emph{name}, \emph{parent=None}, \emph{globals=None}}{}
Load a template from the loader.  If a loader is configured this
method ask the loader for the template and returns a {\hyperref[api:jinja2.Template]{\code{Template}}}.
If the \emph{parent} parameter is not \emph{None}, {\hyperref[api:jinja2.Environment.join_path]{\code{join\_path()}}} is called
to get the real template name before loading.

The \emph{globals} parameter can be used to provide template wide globals.
These variables are available in the context at render time.

If the template does not exist a {\hyperref[api:jinja2.TemplateNotFound]{\code{TemplateNotFound}}} exception is
raised.
Changed in version 2.4: If \emph{name} is a {\hyperref[api:jinja2.Template]{\code{Template}}} object it is returned from the
function unchanged.
\end{fulllineitems}

\index{select\_template() (jinja2.Environment method)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Environment.select_template}\pysiglinewithargsret{\bfcode{select\_template}}{\emph{names}, \emph{parent=None}, \emph{globals=None}}{}
Works like {\hyperref[api:jinja2.Environment.get_template]{\code{get\_template()}}} but tries a number of templates
before it fails.  If it cannot find any of the templates, it will
raise a {\hyperref[api:jinja2.TemplatesNotFound]{\code{TemplatesNotFound}}} exception.
New in version 2.3.Changed in version 2.4: If \emph{names} contains a {\hyperref[api:jinja2.Template]{\code{Template}}} object it is returned
from the function unchanged.
\end{fulllineitems}

\index{get\_or\_select\_template() (jinja2.Environment method)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Environment.get_or_select_template}\pysiglinewithargsret{\bfcode{get\_or\_select\_template}}{\emph{template\_name\_or\_list}, \emph{parent=None}, \emph{globals=None}}{}
Does a typecheck and dispatches to {\hyperref[api:jinja2.Environment.select_template]{\code{select\_template()}}}
if an iterable of template names is given, otherwise to
{\hyperref[api:jinja2.Environment.get_template]{\code{get\_template()}}}.
New in version 2.3.
\end{fulllineitems}

\index{join\_path() (jinja2.Environment method)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Environment.join_path}\pysiglinewithargsret{\bfcode{join\_path}}{\emph{template}, \emph{parent}}{}
Join a template with the parent.  By default all the lookups are
relative to the loader root so this method returns the \emph{template}
parameter unchanged, but if the paths should be relative to the
parent template, this function can be used to calculate the real
template name.

Subclasses may override this method and implement template path
joining here.

\end{fulllineitems}

\index{extend() (jinja2.Environment method)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Environment.extend}\pysiglinewithargsret{\bfcode{extend}}{\emph{**attributes}}{}
Add the items to the instance of the environment if they do not exist
yet.  This is used by {\hyperref[extensions:writing-extensions]{\emph{extensions}}} to register
callbacks and configuration values without breaking inheritance.

\end{fulllineitems}

\index{compile\_expression() (jinja2.Environment method)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Environment.compile_expression}\pysiglinewithargsret{\bfcode{compile\_expression}}{\emph{source}, \emph{undefined\_to\_none=True}}{}
A handy helper method that returns a callable that accepts keyword
arguments that appear as variables in the expression.  If called it
returns the result of the expression.

This is useful if applications want to use the same rules as Jinja
in template ``configuration files'' or similar situations.

Example usage:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{env} \PYG{o}{=} \PYG{n}{Environment}\PYG{p}{(}\PYG{p}{)}
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{expr} \PYG{o}{=} \PYG{n}{env}\PYG{o}{.}\PYG{n}{compile\PYGZus{}expression}\PYG{p}{(}\PYG{l+s}{'}\PYG{l+s}{foo == 42}\PYG{l+s}{'}\PYG{p}{)}
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{expr}\PYG{p}{(}\PYG{n}{foo}\PYG{o}{=}\PYG{l+m+mi}{23}\PYG{p}{)}
\PYG{g+go}{False}
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{expr}\PYG{p}{(}\PYG{n}{foo}\PYG{o}{=}\PYG{l+m+mi}{42}\PYG{p}{)}
\PYG{g+go}{True}
\end{Verbatim}

Per default the return value is converted to \emph{None} if the
expression returns an undefined value.  This can be changed
by setting \emph{undefined\_to\_none} to \emph{False}.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{env}\PYG{o}{.}\PYG{n}{compile\PYGZus{}expression}\PYG{p}{(}\PYG{l+s}{'}\PYG{l+s}{var}\PYG{l+s}{'}\PYG{p}{)}\PYG{p}{(}\PYG{p}{)} \PYG{o+ow}{is} \PYG{n+nb+bp}{None}
\PYG{g+go}{True}
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{env}\PYG{o}{.}\PYG{n}{compile\PYGZus{}expression}\PYG{p}{(}\PYG{l+s}{'}\PYG{l+s}{var}\PYG{l+s}{'}\PYG{p}{,} \PYG{n}{undefined\PYGZus{}to\PYGZus{}none}\PYG{o}{=}\PYG{n+nb+bp}{False}\PYG{p}{)}\PYG{p}{(}\PYG{p}{)}
\PYG{g+go}{Undefined}
\end{Verbatim}
New in version 2.1.
\end{fulllineitems}


\end{fulllineitems}

\index{Template (class in jinja2)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Template}\pysigline{\strong{class }\code{jinja2.}\bfcode{Template}}{}
The central template object.  This class represents a compiled template
and is used to evaluate it.

Normally the template object is generated from an {\hyperref[api:jinja2.Environment]{\code{Environment}}} but
it also has a constructor that makes it possible to create a template
instance directly using the constructor.  It takes the same arguments as
the environment constructor but it's not possible to specify a loader.

Every template object has a few methods and members that are guaranteed
to exist.  However it's important that a template object should be
considered immutable.  Modifications on the object are not supported.

Template objects created from the constructor rather than an environment
do have an \emph{environment} attribute that points to a temporary environment
that is probably shared with other templates created with the constructor
and compatible settings.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{template} \PYG{o}{=} \PYG{n}{Template}\PYG{p}{(}\PYG{l+s}{'}\PYG{l+s}{Hello \PYGZob{}\PYGZob{} name \PYGZcb{}\PYGZcb{}!}\PYG{l+s}{'}\PYG{p}{)}
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{template}\PYG{o}{.}\PYG{n}{render}\PYG{p}{(}\PYG{n}{name}\PYG{o}{=}\PYG{l+s}{'}\PYG{l+s}{John Doe}\PYG{l+s}{'}\PYG{p}{)}
\PYG{g+go}{u'Hello John Doe!'}
\end{Verbatim}

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{stream} \PYG{o}{=} \PYG{n}{template}\PYG{o}{.}\PYG{n}{stream}\PYG{p}{(}\PYG{n}{name}\PYG{o}{=}\PYG{l+s}{'}\PYG{l+s}{John Doe}\PYG{l+s}{'}\PYG{p}{)}
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{stream}\PYG{o}{.}\PYG{n}{next}\PYG{p}{(}\PYG{p}{)}
\PYG{g+go}{u'Hello John Doe!'}
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{stream}\PYG{o}{.}\PYG{n}{next}\PYG{p}{(}\PYG{p}{)}
\PYG{g+gt}{Traceback (most recent call last):}
    \PYG{o}{.}\PYG{o}{.}\PYG{o}{.}
\PYG{n+nc}{StopIteration}
\end{Verbatim}
\index{globals (jinja2.Template attribute)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Template.globals}\pysigline{\bfcode{globals}}{}
The dict with the globals of that template.  It's unsafe to modify
this dict as it may be shared with other templates or the environment
that loaded the template.

\end{fulllineitems}

\index{name (jinja2.Template attribute)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Template.name}\pysigline{\bfcode{name}}{}
The loading name of the template.  If the template was loaded from a
string this is \emph{None}.

\end{fulllineitems}

\index{filename (jinja2.Template attribute)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Template.filename}\pysigline{\bfcode{filename}}{}
The filename of the template on the file system if it was loaded from
there.  Otherwise this is \emph{None}.

\end{fulllineitems}

\index{render() (jinja2.Template method)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Template.render}\pysiglinewithargsret{\bfcode{render}}{\optional{\emph{context}}}{}
This method accepts the same arguments as the \emph{dict} constructor:
A dict, a dict subclass or some keyword arguments.  If no arguments
are given the context will be empty.  These two calls do the same:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n}{template}\PYG{o}{.}\PYG{n}{render}\PYG{p}{(}\PYG{n}{knights}\PYG{o}{=}\PYG{l+s}{'}\PYG{l+s}{that say nih}\PYG{l+s}{'}\PYG{p}{)}
\PYG{n}{template}\PYG{o}{.}\PYG{n}{render}\PYG{p}{(}\PYG{p}{\PYGZob{}}\PYG{l+s}{'}\PYG{l+s}{knights}\PYG{l+s}{'}\PYG{p}{:} \PYG{l+s}{'}\PYG{l+s}{that say nih}\PYG{l+s}{'}\PYG{p}{\PYGZcb{}}\PYG{p}{)}
\end{Verbatim}

This will return the rendered template as unicode string.

\end{fulllineitems}

\index{generate() (jinja2.Template method)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Template.generate}\pysiglinewithargsret{\bfcode{generate}}{\optional{\emph{context}}}{}
For very large templates it can be useful to not render the whole
template at once but evaluate each statement after another and yield
piece for piece.  This method basically does exactly that and returns
a generator that yields one item after another as unicode strings.

It accepts the same arguments as {\hyperref[api:jinja2.Template.render]{\code{render()}}}.

\end{fulllineitems}

\index{stream() (jinja2.Template method)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Template.stream}\pysiglinewithargsret{\bfcode{stream}}{\optional{\emph{context}}}{}
Works exactly like {\hyperref[api:jinja2.Template.generate]{\code{generate()}}} but returns a
\code{TemplateStream}.

\end{fulllineitems}

\index{module (jinja2.Template attribute)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Template.module}\pysigline{\bfcode{module}}{}
The template as module.  This is used for imports in the
template runtime but is also useful if one wants to access
exported template variables from the Python layer:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{t} \PYG{o}{=} \PYG{n}{Template}\PYG{p}{(}\PYG{l+s}{'}\PYG{l+s}{\PYGZob{}}\PYG{l+s}{\%}\PYG{l+s}{ macro foo() }\PYG{l+s}{\%}\PYG{l+s}{\PYGZcb{}42\PYGZob{}}\PYG{l+s+si}{\% e}\PYG{l+s}{ndmacro }\PYG{l+s}{\%}\PYG{l+s}{\PYGZcb{}23}\PYG{l+s}{'}\PYG{p}{)}
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n+nb}{unicode}\PYG{p}{(}\PYG{n}{t}\PYG{o}{.}\PYG{n}{module}\PYG{p}{)}
\PYG{g+go}{u'23'}
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{t}\PYG{o}{.}\PYG{n}{module}\PYG{o}{.}\PYG{n}{foo}\PYG{p}{(}\PYG{p}{)}
\PYG{g+go}{u'42'}
\end{Verbatim}

\end{fulllineitems}

\index{make\_module() (jinja2.Template method)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Template.make_module}\pysiglinewithargsret{\bfcode{make\_module}}{\emph{vars=None}, \emph{shared=False}, \emph{locals=None}}{}
This method works like the {\hyperref[api:jinja2.Template.module]{\code{module}}} attribute when called
without arguments but it will evaluate the template on every call
rather than caching it.  It's also possible to provide
a dict which is then used as context.  The arguments are the same
as for the {\hyperref[api:jinja2.Template.new_context]{\code{new\_context()}}} method.

\end{fulllineitems}


\end{fulllineitems}

\index{TemplateStream (class in jinja2.environment)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.environment.TemplateStream}\pysigline{\strong{class }\code{jinja2.environment.}\bfcode{TemplateStream}}{}
A template stream works pretty much like an ordinary python generator
but it can buffer multiple items to reduce the number of total iterations.
Per default the output is unbuffered which means that for every unbuffered
instruction in the template one unicode string is yielded.

If buffering is enabled with a buffer size of 5, five items are combined
into a new unicode string.  This is mainly useful if you are streaming
big templates to a client via WSGI which flushes after each iteration.
\index{disable\_buffering() (jinja2.environment.TemplateStream method)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.environment.TemplateStream.disable_buffering}\pysiglinewithargsret{\bfcode{disable\_buffering}}{}{}
Disable the output buffering.

\end{fulllineitems}

\index{enable\_buffering() (jinja2.environment.TemplateStream method)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.environment.TemplateStream.enable_buffering}\pysiglinewithargsret{\bfcode{enable\_buffering}}{\emph{size=5}}{}
Enable buffering.  Buffer \emph{size} items before yielding them.

\end{fulllineitems}

\index{dump() (jinja2.environment.TemplateStream method)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.environment.TemplateStream.dump}\pysiglinewithargsret{\bfcode{dump}}{\emph{fp}, \emph{encoding=None}, \emph{errors='strict'}}{}
Dump the complete stream into a file or file-like object.
Per default unicode strings are written, if you want to encode
before writing specifiy an \emph{encoding}.

Example usage:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n}{Template}\PYG{p}{(}\PYG{l+s}{'}\PYG{l+s}{Hello \PYGZob{}\PYGZob{} name \PYGZcb{}\PYGZcb{}!}\PYG{l+s}{'}\PYG{p}{)}\PYG{o}{.}\PYG{n}{stream}\PYG{p}{(}\PYG{n}{name}\PYG{o}{=}\PYG{l+s}{'}\PYG{l+s}{foo}\PYG{l+s}{'}\PYG{p}{)}\PYG{o}{.}\PYG{n}{dump}\PYG{p}{(}\PYG{l+s}{'}\PYG{l+s}{hello.html}\PYG{l+s}{'}\PYG{p}{)}
\end{Verbatim}

\end{fulllineitems}


\end{fulllineitems}



\section{Autoescaping}
\label{api:autoescaping}New in version 2.4.
As of Jinja 2.4 the preferred way to do autoescaping is to enable the
{\hyperref[extensions:autoescape-extension]{\emph{Autoescape Extension}}} and to configure a sensible default for
autoescaping.  This makes it possible to enable and disable autoescaping
on a per-template basis (HTML versus text for instance).

Here a recommended setup that enables autoescaping for templates ending
in \code{'.html'}, \code{'.htm'} and \code{'.xml'} and disabling it by default
for all other extensions:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{k}{def} \PYG{n+nf}{guess\PYGZus{}autoescape}\PYG{p}{(}\PYG{n}{template\PYGZus{}name}\PYG{p}{)}\PYG{p}{:}
    \PYG{k}{if} \PYG{n}{template\PYGZus{}name} \PYG{o+ow}{is} \PYG{n+nb+bp}{None} \PYG{o+ow}{or} \PYG{l+s}{'}\PYG{l+s}{.}\PYG{l+s}{'} \PYG{o+ow}{not} \PYG{o+ow}{in} \PYG{n}{template\PYGZus{}name}\PYG{p}{:}
        \PYG{k}{return} \PYG{n+nb+bp}{False}
    \PYG{n}{ext} \PYG{o}{=} \PYG{n}{template\PYGZus{}name}\PYG{o}{.}\PYG{n}{rsplit}\PYG{p}{(}\PYG{l+s}{'}\PYG{l+s}{.}\PYG{l+s}{'}\PYG{p}{,} \PYG{l+m+mi}{1}\PYG{p}{)}\PYG{p}{[}\PYG{l+m+mi}{1}\PYG{p}{]}
    \PYG{k}{return} \PYG{n}{ext} \PYG{o+ow}{in} \PYG{p}{(}\PYG{l+s}{'}\PYG{l+s}{html}\PYG{l+s}{'}\PYG{p}{,} \PYG{l+s}{'}\PYG{l+s}{htm}\PYG{l+s}{'}\PYG{p}{,} \PYG{l+s}{'}\PYG{l+s}{xml}\PYG{l+s}{'}\PYG{p}{)}

\PYG{n}{env} \PYG{o}{=} \PYG{n}{Environment}\PYG{p}{(}\PYG{n}{autoescape}\PYG{o}{=}\PYG{n}{guess\PYGZus{}autoescape}\PYG{p}{,}
                  \PYG{n}{loader}\PYG{o}{=}\PYG{n}{PackageLoader}\PYG{p}{(}\PYG{l+s}{'}\PYG{l+s}{mypackage}\PYG{l+s}{'}\PYG{p}{)}\PYG{p}{,}
                  \PYG{n}{extensions}\PYG{o}{=}\PYG{p}{[}\PYG{l+s}{'}\PYG{l+s}{jinja2.ext.autoescape}\PYG{l+s}{'}\PYG{p}{]}\PYG{p}{)}
\end{Verbatim}

When implementing a guessing autoescape function, make sure you also
accept \emph{None} as valid template name.  This will be passed when generating
templates from strings.

Inside the templates the behaviour can be temporarily changed by using
the \emph{autoescape} block (see {\hyperref[templates:autoescape-overrides]{\emph{Autoescape Extension}}}).


\section{Notes on Identifiers}
\label{api:notes-on-identifiers}\label{api:identifier-naming}
Jinja2 uses the regular Python 2.x naming rules.  Valid identifiers have to
match \code{{[}a-zA-Z\_{]}{[}a-zA-Z0-9\_{]}*}.  As a matter of fact non ASCII characters
are currently not allowed.  This limitation will probably go away as soon as
unicode identifiers are fully specified for Python 3.

Filters and tests are looked up in separate namespaces and have slightly
modified identifier syntax.  Filters and tests may contain dots to group
filters and tests by topic.  For example it's perfectly valid to add a
function into the filter dict and call it \emph{to.unicode}.  The regular
expression for filter and test identifiers is
\code{{[}a-zA-Z\_{]}{[}a-zA-Z0-9\_{]}*(\textbackslash{}.{[}a-zA-Z\_{]}{[}a-zA-Z0-9\_{]}*)*{}`}.


\section{Undefined Types}
\label{api:undefined-types}
These classes can be used as undefined types.  The {\hyperref[api:jinja2.Environment]{\code{Environment}}}
constructor takes an \emph{undefined} parameter that can be one of those classes
or a custom subclass of {\hyperref[api:jinja2.Undefined]{\code{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 \emph{StrictUndefined} which
disallows all operations beside testing if it's an undefined object.
\index{Undefined (class in jinja2)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Undefined}\pysigline{\strong{class }\code{jinja2.}\bfcode{Undefined}}{}
The default undefined type.  This undefined type can be printed and
iterated over, but every other access will raise an {\hyperref[api:jinja2.UndefinedError]{\code{UndefinedError}}}:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{foo} \PYG{o}{=} \PYG{n}{Undefined}\PYG{p}{(}\PYG{n}{name}\PYG{o}{=}\PYG{l+s}{'}\PYG{l+s}{foo}\PYG{l+s}{'}\PYG{p}{)}
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n+nb}{str}\PYG{p}{(}\PYG{n}{foo}\PYG{p}{)}
\PYG{g+go}{''}
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{o+ow}{not} \PYG{n}{foo}
\PYG{g+go}{True}
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{foo} \PYG{o}{+} \PYG{l+m+mi}{42}
\PYG{g+gt}{Traceback (most recent call last):}
  \PYG{c}{...}
\PYG{n+nc}{UndefinedError}: \PYG{n+nIdentifier}{'foo' is undefined}
\end{Verbatim}
\index{\_undefined\_hint (jinja2.Undefined attribute)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Undefined._undefined_hint}\pysigline{\bfcode{\_undefined\_hint}}{}
Either \emph{None} or an unicode string with the error message for
the undefined object.

\end{fulllineitems}

\index{\_undefined\_obj (jinja2.Undefined attribute)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Undefined._undefined_obj}\pysigline{\bfcode{\_undefined\_obj}}{}
Either \emph{None} or the owner object that caused the undefined object
to be created (for example because an attribute does not exist).

\end{fulllineitems}

\index{\_undefined\_name (jinja2.Undefined attribute)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Undefined._undefined_name}\pysigline{\bfcode{\_undefined\_name}}{}
The name for the undefined variable / attribute or just \emph{None}
if no such information exists.

\end{fulllineitems}

\index{\_undefined\_exception (jinja2.Undefined attribute)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Undefined._undefined_exception}\pysigline{\bfcode{\_undefined\_exception}}{}
The exception that the undefined object wants to raise.  This
is usually one of {\hyperref[api:jinja2.UndefinedError]{\code{UndefinedError}}} or \code{SecurityError}.

\end{fulllineitems}

\index{\_fail\_with\_undefined\_error() (jinja2.Undefined method)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Undefined._fail_with_undefined_error}\pysiglinewithargsret{\bfcode{\_fail\_with\_undefined\_error}}{\emph{*args}, \emph{**kwargs}}{}
When called with any arguments this method raises
{\hyperref[api:jinja2.Undefined._undefined_exception]{\code{\_undefined\_exception}}} with an error message generated
from the undefined hints stored on the undefined object.

\end{fulllineitems}


\end{fulllineitems}

\index{DebugUndefined (class in jinja2)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.DebugUndefined}\pysigline{\strong{class }\code{jinja2.}\bfcode{DebugUndefined}}{}
An undefined that returns the debug info when printed.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{foo} \PYG{o}{=} \PYG{n}{DebugUndefined}\PYG{p}{(}\PYG{n}{name}\PYG{o}{=}\PYG{l+s}{'}\PYG{l+s}{foo}\PYG{l+s}{'}\PYG{p}{)}
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n+nb}{str}\PYG{p}{(}\PYG{n}{foo}\PYG{p}{)}
\PYG{g+go}{'\PYGZob{}\PYGZob{} foo \PYGZcb{}\PYGZcb{}'}
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{o+ow}{not} \PYG{n}{foo}
\PYG{g+go}{True}
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{foo} \PYG{o}{+} \PYG{l+m+mi}{42}
\PYG{g+gt}{Traceback (most recent call last):}
  \PYG{c}{...}
\PYG{n+nc}{UndefinedError}: \PYG{n+nIdentifier}{'foo' is undefined}
\end{Verbatim}

\end{fulllineitems}

\index{StrictUndefined (class in jinja2)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.StrictUndefined}\pysigline{\strong{class }\code{jinja2.}\bfcode{StrictUndefined}}{}
An undefined that barks on print and iteration as well as boolean
tests and all kinds of comparisons.  In other words: you can do nothing
with it except checking if it's defined using the \emph{defined} test.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{foo} \PYG{o}{=} \PYG{n}{StrictUndefined}\PYG{p}{(}\PYG{n}{name}\PYG{o}{=}\PYG{l+s}{'}\PYG{l+s}{foo}\PYG{l+s}{'}\PYG{p}{)}
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n+nb}{str}\PYG{p}{(}\PYG{n}{foo}\PYG{p}{)}
\PYG{g+gt}{Traceback (most recent call last):}
  \PYG{c}{...}
\PYG{n+nc}{UndefinedError}: \PYG{n+nIdentifier}{'foo' is undefined}
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{o+ow}{not} \PYG{n}{foo}
\PYG{g+gt}{Traceback (most recent call last):}
  \PYG{c}{...}
\PYG{n+nc}{UndefinedError}: \PYG{n+nIdentifier}{'foo' is undefined}
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{foo} \PYG{o}{+} \PYG{l+m+mi}{42}
\PYG{g+gt}{Traceback (most recent call last):}
  \PYG{c}{...}
\PYG{n+nc}{UndefinedError}: \PYG{n+nIdentifier}{'foo' is undefined}
\end{Verbatim}

\end{fulllineitems}


Undefined objects are created by calling {\hyperref[templates:undefined]{\code{undefined}}}.

\begin{notice}{note}{Implementation}

{\hyperref[api:jinja2.Undefined]{\code{Undefined}}} objects are implemented by overriding the special
\emph{\_\_underscore\_\_} methods.  For example the default {\hyperref[api:jinja2.Undefined]{\code{Undefined}}}
class implements \emph{\_\_unicode\_\_} in a way that it returns an empty
string, however \emph{\_\_int\_\_} and others still fail with an exception.  To
allow conversion to int by returning \code{0} you can implement your own:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{k}{class} \PYG{n+nc}{NullUndefined}\PYG{p}{(}\PYG{n}{Undefined}\PYG{p}{)}\PYG{p}{:}
    \PYG{k}{def} \PYG{n+nf}{\PYGZus{}\PYGZus{}int\PYGZus{}\PYGZus{}}\PYG{p}{(}\PYG{n+nb+bp}{self}\PYG{p}{)}\PYG{p}{:}
        \PYG{k}{return} \PYG{l+m+mi}{0}
    \PYG{k}{def} \PYG{n+nf}{\PYGZus{}\PYGZus{}float\PYGZus{}\PYGZus{}}\PYG{p}{(}\PYG{n+nb+bp}{self}\PYG{p}{)}\PYG{p}{:}
        \PYG{k}{return} \PYG{l+m+mf}{0.0}
\end{Verbatim}

To disallow a method, just override it and raise
{\hyperref[api:jinja2.Undefined._undefined_exception]{\code{\_undefined\_exception}}}.  Because this is a very common
idom in undefined objects there is the helper method
{\hyperref[api:jinja2.Undefined._fail_with_undefined_error]{\code{\_fail\_with\_undefined\_error()}}} that does the error raising
automatically.  Here a class that works like the regular {\hyperref[api:jinja2.Undefined]{\code{Undefined}}}
but chokes on iteration:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{k}{class} \PYG{n+nc}{NonIterableUndefined}\PYG{p}{(}\PYG{n}{Undefined}\PYG{p}{)}\PYG{p}{:}
    \PYG{n}{\PYGZus{}\PYGZus{}iter\PYGZus{}\PYGZus{}} \PYG{o}{=} \PYG{n}{Undefined}\PYG{o}{.}\PYG{n}{\PYGZus{}fail\PYGZus{}with\PYGZus{}undefined\PYGZus{}error}
\end{Verbatim}
\end{notice}


\section{The Context}
\label{api:the-context}\index{Context (class in jinja2.runtime)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.runtime.Context}\pysigline{\strong{class }\code{jinja2.runtime.}\bfcode{Context}}{}
The template context holds the variables of a template.  It stores the
values passed to the template and also the names the template exports.
Creating instances is neither supported nor useful as it's created
automatically at various stages of the template evaluation and should not
be created by hand.

The context is immutable.  Modifications on {\hyperref[api:jinja2.Context.parent]{\code{parent}}} \textbf{must not}
happen and modifications on {\hyperref[api:jinja2.Context.vars]{\code{vars}}} are allowed from generated
template code only.  Template filters and global functions marked as
{\hyperref[api:jinja2.contextfunction]{\code{contextfunction()}}}s get the active context passed as first argument
and are allowed to access the context read-only.

The template context supports read only dict operations (\emph{get},
\emph{keys}, \emph{values}, \emph{items}, \emph{iterkeys}, \emph{itervalues}, \emph{iteritems},
\emph{\_\_getitem\_\_}, \emph{\_\_contains\_\_}).  Additionally there is a \code{resolve()}
method that doesn't fail with a \emph{KeyError} but returns an
{\hyperref[api:jinja2.Undefined]{\code{Undefined}}} object for missing variables.
\index{parent (jinja2.Context attribute)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Context.parent}\pysigline{\bfcode{parent}}{}
A dict of read only, global variables the template looks up.  These
can either come from another \code{Context}, from the
{\hyperref[api:jinja2.Environment.globals]{\code{Environment.globals}}} or {\hyperref[api:jinja2.Template.globals]{\code{Template.globals}}} or points
to a dict created by combining the globals with the variables
passed to the render function.  It must not be altered.

\end{fulllineitems}

\index{vars (jinja2.Context attribute)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Context.vars}\pysigline{\bfcode{vars}}{}
The template local variables.  This list contains environment and
context functions from the {\hyperref[api:jinja2.Context.parent]{\code{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.

\end{fulllineitems}

\index{environment (jinja2.Context attribute)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Context.environment}\pysigline{\bfcode{environment}}{}
The environment that loaded the template.

\end{fulllineitems}

\index{exported\_vars (jinja2.Context attribute)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Context.exported_vars}\pysigline{\bfcode{exported\_vars}}{}
This set contains all the names the template exports.  The values for
the names are in the {\hyperref[api:jinja2.Context.vars]{\code{vars}}} dict.  In order to get a copy of the
exported variables as dict, \code{get\_exported()} can be used.

\end{fulllineitems}

\index{name (jinja2.Context attribute)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Context.name}\pysigline{\bfcode{name}}{}
The load name of the template owning this context.

\end{fulllineitems}

\index{blocks (jinja2.Context attribute)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Context.blocks}\pysigline{\bfcode{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).

\end{fulllineitems}

\index{eval\_ctx (jinja2.Context attribute)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Context.eval_ctx}\pysigline{\bfcode{eval\_ctx}}{}
The current {\hyperref[api:eval-context]{\emph{Evaluation Context}}}.

\end{fulllineitems}

\index{call() (jinja2.runtime.Context method)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.runtime.Context.call}\pysiglinewithargsret{\bfcode{call}}{\emph{callable}, \emph{*args}, \emph{**kwargs}}{}
Call the callable with the arguments and keyword arguments
provided but inject the active context or environment as first
argument if the callable is a {\hyperref[api:jinja2.contextfunction]{\code{contextfunction()}}} or
{\hyperref[api:jinja2.environmentfunction]{\code{environmentfunction()}}}.

\end{fulllineitems}

\index{resolve() (jinja2.runtime.Context method)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.runtime.Context.resolve}\pysiglinewithargsret{\bfcode{resolve}}{\emph{key}}{}
Looks up a variable like \emph{\_\_getitem\_\_} or \emph{get} but returns an
{\hyperref[api:jinja2.Undefined]{\code{Undefined}}} object with the name of the name looked up.

\end{fulllineitems}

\index{get\_exported() (jinja2.runtime.Context method)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.runtime.Context.get_exported}\pysiglinewithargsret{\bfcode{get\_exported}}{}{}
Get a new dict with the exported variables.

\end{fulllineitems}

\index{get\_all() (jinja2.runtime.Context method)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.runtime.Context.get_all}\pysiglinewithargsret{\bfcode{get\_all}}{}{}
Return a copy of the complete context as dict including the
exported variables.

\end{fulllineitems}


\end{fulllineitems}


\begin{notice}{note}{Implementation}

Context is immutable for the same reason Python's frame locals are
immutable inside functions.  Both Jinja2 and Python are not using the
context / frame locals as data storage for variables but only as primary
data source.

When a template accesses a variable the template does not define, Jinja2
looks up the variable in the context, after that the variable is treated
as if it was defined in the template.
\end{notice}


\section{Loaders}
\label{api:id1}\label{api: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 \emph{sys.modules}.  Unlike \emph{sys.modules} however this cache is limited in
size by default and templates are automatically reloaded.
All loaders are subclasses of {\hyperref[api:jinja2.BaseLoader]{\code{BaseLoader}}}.  If you want to create your
own loader, subclass {\hyperref[api:jinja2.BaseLoader]{\code{BaseLoader}}} and override \emph{get\_source}.
\index{BaseLoader (class in jinja2)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.BaseLoader}\pysigline{\strong{class }\code{jinja2.}\bfcode{BaseLoader}}{}
Baseclass for all loaders.  Subclass this and override \emph{get\_source} to
implement a custom loading mechanism.  The environment provides a
\emph{get\_template} method that calls the loader's \emph{load} method to get the
{\hyperref[api:jinja2.Template]{\code{Template}}} object.

A very basic example for a loader that looks up templates on the file
system could look like this:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{k+kn}{from} \PYG{n+nn}{jinja2} \PYG{k+kn}{import} \PYG{n}{BaseLoader}\PYG{p}{,} \PYG{n}{TemplateNotFound}
\PYG{k+kn}{from} \PYG{n+nn}{os.path} \PYG{k+kn}{import} \PYG{n}{join}\PYG{p}{,} \PYG{n}{exists}\PYG{p}{,} \PYG{n}{getmtime}

\PYG{k}{class} \PYG{n+nc}{MyLoader}\PYG{p}{(}\PYG{n}{BaseLoader}\PYG{p}{)}\PYG{p}{:}

    \PYG{k}{def} \PYG{n+nf}{\PYGZus{}\PYGZus{}init\PYGZus{}\PYGZus{}}\PYG{p}{(}\PYG{n+nb+bp}{self}\PYG{p}{,} \PYG{n}{path}\PYG{p}{)}\PYG{p}{:}
        \PYG{n+nb+bp}{self}\PYG{o}{.}\PYG{n}{path} \PYG{o}{=} \PYG{n}{path}

    \PYG{k}{def} \PYG{n+nf}{get\PYGZus{}source}\PYG{p}{(}\PYG{n+nb+bp}{self}\PYG{p}{,} \PYG{n}{environment}\PYG{p}{,} \PYG{n}{template}\PYG{p}{)}\PYG{p}{:}
        \PYG{n}{path} \PYG{o}{=} \PYG{n}{join}\PYG{p}{(}\PYG{n+nb+bp}{self}\PYG{o}{.}\PYG{n}{path}\PYG{p}{,} \PYG{n}{template}\PYG{p}{)}
        \PYG{k}{if} \PYG{o+ow}{not} \PYG{n}{exists}\PYG{p}{(}\PYG{n}{path}\PYG{p}{)}\PYG{p}{:}
            \PYG{k}{raise} \PYG{n}{TemplateNotFound}\PYG{p}{(}\PYG{n}{template}\PYG{p}{)}
        \PYG{n}{mtime} \PYG{o}{=} \PYG{n}{getmtime}\PYG{p}{(}\PYG{n}{path}\PYG{p}{)}
        \PYG{k}{with} \PYG{n+nb}{file}\PYG{p}{(}\PYG{n}{path}\PYG{p}{)} \PYG{k}{as} \PYG{n}{f}\PYG{p}{:}
            \PYG{n}{source} \PYG{o}{=} \PYG{n}{f}\PYG{o}{.}\PYG{n}{read}\PYG{p}{(}\PYG{p}{)}\PYG{o}{.}\PYG{n}{decode}\PYG{p}{(}\PYG{l+s}{'}\PYG{l+s}{utf-8}\PYG{l+s}{'}\PYG{p}{)}
        \PYG{k}{return} \PYG{n}{source}\PYG{p}{,} \PYG{n}{path}\PYG{p}{,} \PYG{k}{lambda}\PYG{p}{:} \PYG{n}{mtime} \PYG{o}{==} \PYG{n}{getmtime}\PYG{p}{(}\PYG{n}{path}\PYG{p}{)}
\end{Verbatim}
\index{get\_source() (jinja2.BaseLoader method)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.BaseLoader.get_source}\pysiglinewithargsret{\bfcode{get\_source}}{\emph{environment}, \emph{template}}{}
Get the template source, filename and reload helper for a template.
It's passed the environment and template name and has to return a
tuple in the form \code{(source, filename, uptodate)} or raise a
\emph{TemplateNotFound} error if it can't locate the template.

The source part of the returned tuple must be the source of the
template as unicode string or a ASCII bytestring.  The filename should
be the name of the file on the filesystem if it was loaded from there,
otherwise \emph{None}.  The filename is used by python for the tracebacks
if no loader extension is used.

The last item in the tuple is the \emph{uptodate} function.  If auto
reloading is enabled it's always called to check if the template
changed.  No arguments are passed so the function must store the
old state somewhere (for example in a closure).  If it returns \emph{False}
the template will be reloaded.

\end{fulllineitems}

\index{load() (jinja2.BaseLoader method)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.BaseLoader.load}\pysiglinewithargsret{\bfcode{load}}{\emph{environment}, \emph{name}, \emph{globals=None}}{}
Loads a template.  This method looks up the template in the cache
or loads one by calling {\hyperref[api:jinja2.BaseLoader.get_source]{\code{get\_source()}}}.  Subclasses should not
override this method as loaders working on collections of other
loaders (such as {\hyperref[api:jinja2.PrefixLoader]{\code{PrefixLoader}}} or {\hyperref[api:jinja2.ChoiceLoader]{\code{ChoiceLoader}}})
will not call this method but \emph{get\_source} directly.

\end{fulllineitems}


\end{fulllineitems}


Here a list of the builtin loaders Jinja2 provides:
\index{FileSystemLoader (class in jinja2)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.FileSystemLoader}\pysiglinewithargsret{\strong{class }\code{jinja2.}\bfcode{FileSystemLoader}}{\emph{searchpath}, \emph{encoding='utf-8'}}{}
Loads templates from the file system.  This loader can find templates
in folders on the file system and is the preferred way to load them.

The loader takes the path to the templates as string, or if multiple
locations are wanted a list of them which is then looked up in the
given order:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{loader} \PYG{o}{=} \PYG{n}{FileSystemLoader}\PYG{p}{(}\PYG{l+s}{'}\PYG{l+s}{/path/to/templates}\PYG{l+s}{'}\PYG{p}{)}
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{loader} \PYG{o}{=} \PYG{n}{FileSystemLoader}\PYG{p}{(}\PYG{p}{[}\PYG{l+s}{'}\PYG{l+s}{/path/to/templates}\PYG{l+s}{'}\PYG{p}{,} \PYG{l+s}{'}\PYG{l+s}{/other/path}\PYG{l+s}{'}\PYG{p}{]}\PYG{p}{)}
\end{Verbatim}

Per default the template encoding is \code{'utf-8'} which can be changed
by setting the \emph{encoding} parameter to something else.

\end{fulllineitems}

\index{PackageLoader (class in jinja2)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.PackageLoader}\pysiglinewithargsret{\strong{class }\code{jinja2.}\bfcode{PackageLoader}}{\emph{package\_name}, \emph{package\_path='templates'}, \emph{encoding='utf-8'}}{}
Load templates from python eggs or packages.  It is constructed with
the name of the python package and the path to the templates in that
package:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n}{loader} \PYG{o}{=} \PYG{n}{PackageLoader}\PYG{p}{(}\PYG{l+s}{'}\PYG{l+s}{mypackage}\PYG{l+s}{'}\PYG{p}{,} \PYG{l+s}{'}\PYG{l+s}{views}\PYG{l+s}{'}\PYG{p}{)}
\end{Verbatim}

If the package path is not given, \code{'templates'} is assumed.

Per default the template encoding is \code{'utf-8'} which can be changed
by setting the \emph{encoding} parameter to something else.  Due to the nature
of eggs it's only possible to reload templates if the package was loaded
from the file system and not a zip file.

\end{fulllineitems}

\index{DictLoader (class in jinja2)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.DictLoader}\pysiglinewithargsret{\strong{class }\code{jinja2.}\bfcode{DictLoader}}{\emph{mapping}}{}
Loads a template from a python dict.  It's passed a dict of unicode
strings bound to template names.  This loader is useful for unittesting:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{loader} \PYG{o}{=} \PYG{n}{DictLoader}\PYG{p}{(}\PYG{p}{\PYGZob{}}\PYG{l+s}{'}\PYG{l+s}{index.html}\PYG{l+s}{'}\PYG{p}{:} \PYG{l+s}{'}\PYG{l+s}{source here}\PYG{l+s}{'}\PYG{p}{\PYGZcb{}}\PYG{p}{)}
\end{Verbatim}

Because auto reloading is rarely useful this is disabled per default.

\end{fulllineitems}

\index{FunctionLoader (class in jinja2)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.FunctionLoader}\pysiglinewithargsret{\strong{class }\code{jinja2.}\bfcode{FunctionLoader}}{\emph{load\_func}}{}
A loader that is passed a function which does the loading.  The
function becomes the name of the template passed and has to return either
an unicode string with the template source, a tuple in the form \code{(source,
filename, uptodatefunc)} or \emph{None} if the template does not exist.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{k}{def} \PYG{n+nf}{load\PYGZus{}template}\PYG{p}{(}\PYG{n}{name}\PYG{p}{)}\PYG{p}{:}
\PYG{g+gp}{... }    \PYG{k}{if} \PYG{n}{name} \PYG{o}{==} \PYG{l+s}{'}\PYG{l+s}{index.html}\PYG{l+s}{'}\PYG{p}{:}
\PYG{g+gp}{... }        \PYG{k}{return} \PYG{l+s}{'}\PYG{l+s}{...}\PYG{l+s}{'}
\PYG{g+gp}{...}
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{loader} \PYG{o}{=} \PYG{n}{FunctionLoader}\PYG{p}{(}\PYG{n}{load\PYGZus{}template}\PYG{p}{)}
\end{Verbatim}

The \emph{uptodatefunc} is a function that is called if autoreload is enabled
and has to return \emph{True} if the template is still up to date.  For more
details have a look at {\hyperref[api:jinja2.BaseLoader.get_source]{\code{BaseLoader.get\_source()}}} which has the same
return value.

\end{fulllineitems}

\index{PrefixLoader (class in jinja2)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.PrefixLoader}\pysiglinewithargsret{\strong{class }\code{jinja2.}\bfcode{PrefixLoader}}{\emph{mapping}, \emph{delimiter='/'}}{}
A loader that is passed a dict of loaders where each loader is bound
to a prefix.  The prefix is delimited from the template by a slash per
default, which can be changed by setting the \emph{delimiter} argument to
something else:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n}{loader} \PYG{o}{=} \PYG{n}{PrefixLoader}\PYG{p}{(}\PYG{p}{\PYGZob{}}
    \PYG{l+s}{'}\PYG{l+s}{app1}\PYG{l+s}{'}\PYG{p}{:}     \PYG{n}{PackageLoader}\PYG{p}{(}\PYG{l+s}{'}\PYG{l+s}{mypackage.app1}\PYG{l+s}{'}\PYG{p}{)}\PYG{p}{,}
    \PYG{l+s}{'}\PYG{l+s}{app2}\PYG{l+s}{'}\PYG{p}{:}     \PYG{n}{PackageLoader}\PYG{p}{(}\PYG{l+s}{'}\PYG{l+s}{mypackage.app2}\PYG{l+s}{'}\PYG{p}{)}
\PYG{p}{\PYGZcb{}}\PYG{p}{)}
\end{Verbatim}

By loading \code{'app1/index.html'} the file from the app1 package is loaded,
by loading \code{'app2/index.html'} the file from the second.

\end{fulllineitems}

\index{ChoiceLoader (class in jinja2)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.ChoiceLoader}\pysiglinewithargsret{\strong{class }\code{jinja2.}\bfcode{ChoiceLoader}}{\emph{loaders}}{}
This loader works like the \emph{PrefixLoader} just that no prefix is
specified.  If a template could not be found by one loader the next one
is tried.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{loader} \PYG{o}{=} \PYG{n}{ChoiceLoader}\PYG{p}{(}\PYG{p}{[}
\PYG{g+gp}{... }    \PYG{n}{FileSystemLoader}\PYG{p}{(}\PYG{l+s}{'}\PYG{l+s}{/path/to/user/templates}\PYG{l+s}{'}\PYG{p}{)}\PYG{p}{,}
\PYG{g+gp}{... }    \PYG{n}{FileSystemLoader}\PYG{p}{(}\PYG{l+s}{'}\PYG{l+s}{/path/to/system/templates}\PYG{l+s}{'}\PYG{p}{)}
\PYG{g+gp}{... }\PYG{p}{]}\PYG{p}{)}
\end{Verbatim}

This is useful if you want to allow users to override builtin templates
from a different location.

\end{fulllineitems}



\section{Bytecode Cache}
\label{api:bytecode-cache}\label{api:id2}
Jinja 2.1 and higher support external bytecode caching.  Bytecode caches make
it possible to store the generated bytecode on the file system or a different
location to avoid parsing the templates on first use.

This is especially useful if you have a web application that is initialized on
the first request and Jinja compiles many templates at once which slows down
the application.

To use a bytecode cache, instanciate it and pass it to the {\hyperref[api:jinja2.Environment]{\code{Environment}}}.
\index{BytecodeCache (class in jinja2)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.BytecodeCache}\pysigline{\strong{class }\code{jinja2.}\bfcode{BytecodeCache}}{}
To implement your own bytecode cache you have to subclass this class
and override {\hyperref[api:jinja2.BytecodeCache.load_bytecode]{\code{load\_bytecode()}}} and {\hyperref[api:jinja2.BytecodeCache.dump_bytecode]{\code{dump\_bytecode()}}}.  Both of
these methods are passed a {\hyperref[api:jinja2.bccache.Bucket]{\code{Bucket}}}.

A very basic bytecode cache that saves the bytecode on the file system:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{k+kn}{from} \PYG{n+nn}{os} \PYG{k+kn}{import} \PYG{n}{path}

\PYG{k}{class} \PYG{n+nc}{MyCache}\PYG{p}{(}\PYG{n}{BytecodeCache}\PYG{p}{)}\PYG{p}{:}

    \PYG{k}{def} \PYG{n+nf}{\PYGZus{}\PYGZus{}init\PYGZus{}\PYGZus{}}\PYG{p}{(}\PYG{n+nb+bp}{self}\PYG{p}{,} \PYG{n}{directory}\PYG{p}{)}\PYG{p}{:}
        \PYG{n+nb+bp}{self}\PYG{o}{.}\PYG{n}{directory} \PYG{o}{=} \PYG{n}{directory}

    \PYG{k}{def} \PYG{n+nf}{load\PYGZus{}bytecode}\PYG{p}{(}\PYG{n+nb+bp}{self}\PYG{p}{,} \PYG{n}{bucket}\PYG{p}{)}\PYG{p}{:}
        \PYG{n}{filename} \PYG{o}{=} \PYG{n}{path}\PYG{o}{.}\PYG{n}{join}\PYG{p}{(}\PYG{n+nb+bp}{self}\PYG{o}{.}\PYG{n}{directory}\PYG{p}{,} \PYG{n}{bucket}\PYG{o}{.}\PYG{n}{key}\PYG{p}{)}
        \PYG{k}{if} \PYG{n}{path}\PYG{o}{.}\PYG{n}{exists}\PYG{p}{(}\PYG{n}{filename}\PYG{p}{)}\PYG{p}{:}
            \PYG{k}{with} \PYG{n+nb}{open}\PYG{p}{(}\PYG{n}{filename}\PYG{p}{,} \PYG{l+s}{'}\PYG{l+s}{rb}\PYG{l+s}{'}\PYG{p}{)} \PYG{k}{as} \PYG{n}{f}\PYG{p}{:}
                \PYG{n}{bucket}\PYG{o}{.}\PYG{n}{load\PYGZus{}bytecode}\PYG{p}{(}\PYG{n}{f}\PYG{p}{)}

    \PYG{k}{def} \PYG{n+nf}{dump\PYGZus{}bytecode}\PYG{p}{(}\PYG{n+nb+bp}{self}\PYG{p}{,} \PYG{n}{bucket}\PYG{p}{)}\PYG{p}{:}
        \PYG{n}{filename} \PYG{o}{=} \PYG{n}{path}\PYG{o}{.}\PYG{n}{join}\PYG{p}{(}\PYG{n+nb+bp}{self}\PYG{o}{.}\PYG{n}{directory}\PYG{p}{,} \PYG{n}{bucket}\PYG{o}{.}\PYG{n}{key}\PYG{p}{)}
        \PYG{k}{with} \PYG{n+nb}{open}\PYG{p}{(}\PYG{n}{filename}\PYG{p}{,} \PYG{l+s}{'}\PYG{l+s}{wb}\PYG{l+s}{'}\PYG{p}{)} \PYG{k}{as} \PYG{n}{f}\PYG{p}{:}
            \PYG{n}{bucket}\PYG{o}{.}\PYG{n}{write\PYGZus{}bytecode}\PYG{p}{(}\PYG{n}{f}\PYG{p}{)}
\end{Verbatim}

A more advanced version of a filesystem based bytecode cache is part of
Jinja2.
\index{load\_bytecode() (jinja2.BytecodeCache method)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.BytecodeCache.load_bytecode}\pysiglinewithargsret{\bfcode{load\_bytecode}}{\emph{bucket}}{}
Subclasses have to override this method to load bytecode into a
bucket.  If they are not able to find code in the cache for the
bucket, it must not do anything.

\end{fulllineitems}

\index{dump\_bytecode() (jinja2.BytecodeCache method)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.BytecodeCache.dump_bytecode}\pysiglinewithargsret{\bfcode{dump\_bytecode}}{\emph{bucket}}{}
Subclasses have to override this method to write the bytecode
from a bucket back to the cache.  If it unable to do so it must not
fail silently but raise an exception.

\end{fulllineitems}

\index{clear() (jinja2.BytecodeCache method)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.BytecodeCache.clear}\pysiglinewithargsret{\bfcode{clear}}{}{}
Clears the cache.  This method is not used by Jinja2 but should be
implemented to allow applications to clear the bytecode cache used
by a particular environment.

\end{fulllineitems}


\end{fulllineitems}

\index{Bucket (class in jinja2.bccache)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.bccache.Bucket}\pysiglinewithargsret{\strong{class }\code{jinja2.bccache.}\bfcode{Bucket}}{\emph{environment}, \emph{key}, \emph{checksum}}{}
Buckets are used to store the bytecode for one template.  It's created
and initialized by the bytecode cache and passed to the loading functions.

The buckets get an internal checksum from the cache assigned and use this
to automatically reject outdated cache material.  Individual bytecode
cache subclasses don't have to care about cache invalidation.
\index{environment (jinja2.Bucket attribute)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Bucket.environment}\pysigline{\bfcode{environment}}{}
The {\hyperref[api:jinja2.Environment]{\code{Environment}}} that created the bucket.

\end{fulllineitems}

\index{key (jinja2.Bucket attribute)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Bucket.key}\pysigline{\bfcode{key}}{}
The unique cache key for this bucket

\end{fulllineitems}

\index{code (jinja2.Bucket attribute)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Bucket.code}\pysigline{\bfcode{code}}{}
The bytecode if it's loaded, otherwise \emph{None}.

\end{fulllineitems}

\index{write\_bytecode() (jinja2.bccache.Bucket method)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.bccache.Bucket.write_bytecode}\pysiglinewithargsret{\bfcode{write\_bytecode}}{\emph{f}}{}
Dump the bytecode into the file or file like object passed.

\end{fulllineitems}

\index{load\_bytecode() (jinja2.bccache.Bucket method)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.bccache.Bucket.load_bytecode}\pysiglinewithargsret{\bfcode{load\_bytecode}}{\emph{f}}{}
Loads bytecode from a file or file like object.

\end{fulllineitems}

\index{bytecode\_from\_string() (jinja2.bccache.Bucket method)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.bccache.Bucket.bytecode_from_string}\pysiglinewithargsret{\bfcode{bytecode\_from\_string}}{\emph{string}}{}
Load bytecode from a string.

\end{fulllineitems}

\index{bytecode\_to\_string() (jinja2.bccache.Bucket method)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.bccache.Bucket.bytecode_to_string}\pysiglinewithargsret{\bfcode{bytecode\_to\_string}}{}{}
Return the bytecode as string.

\end{fulllineitems}

\index{reset() (jinja2.bccache.Bucket method)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.bccache.Bucket.reset}\pysiglinewithargsret{\bfcode{reset}}{}{}
Resets the bucket (unloads the bytecode).

\end{fulllineitems}


\end{fulllineitems}


Builtin bytecode caches:
\index{FileSystemBytecodeCache (class in jinja2)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.FileSystemBytecodeCache}\pysiglinewithargsret{\strong{class }\code{jinja2.}\bfcode{FileSystemBytecodeCache}}{\emph{directory=None}, \emph{pattern='\_\_jinja2\_\%s.cache'}}{}
A bytecode cache that stores bytecode on the filesystem.  It accepts
two arguments: The directory where the cache items are stored and a
pattern string that is used to build the filename.

If no directory is specified the system temporary items folder is used.

The pattern can be used to have multiple separate caches operate on the
same directory.  The default pattern is \code{'\_\_jinja2\_\%s.cache'}.  \code{\%s}
is replaced with the cache key.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{bcc} \PYG{o}{=} \PYG{n}{FileSystemBytecodeCache}\PYG{p}{(}\PYG{l+s}{'}\PYG{l+s}{/tmp/jinja\PYGZus{}cache}\PYG{l+s}{'}\PYG{p}{,} \PYG{l+s}{'}\PYG{l+s+si}{\%s}\PYG{l+s}{.cache}\PYG{l+s}{'}\PYG{p}{)}
\end{Verbatim}

This bytecode cache supports clearing of the cache using the clear method.

\end{fulllineitems}

\index{MemcachedBytecodeCache (class in jinja2)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.MemcachedBytecodeCache}\pysiglinewithargsret{\strong{class }\code{jinja2.}\bfcode{MemcachedBytecodeCache}}{\emph{client}, \emph{prefix='jinja2/bytecode/'}, \emph{timeout=None}}{}
This class implements a bytecode cache that uses a memcache cache for
storing the information.  It does not enforce a specific memcache library
(tummy's memcache or cmemcache) but will accept any class that provides
the minimal interface required.

Libraries compatible with this class:
\begin{itemize}
\item {} 
\href{http://werkzeug.pocoo.org/}{werkzeug}.contrib.cache

\item {} 
\href{http://www.tummy.com/Community/software/python-memcached/}{python-memcached}

\item {} 
\href{http://gijsbert.org/cmemcache/}{cmemcache}

\end{itemize}

(Unfortunately the django cache interface is not compatible because it
does not support storing binary data, only unicode.  You can however pass
the underlying cache client to the bytecode cache which is available
as \emph{django.core.cache.cache.\_client}.)

The minimal interface for the client passed to the constructor is this:
\index{MemcachedBytecodeCache.MinimalClientInterface (class in jinja2)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.MemcachedBytecodeCache.MinimalClientInterface}\pysigline{\strong{class }\bfcode{MinimalClientInterface}}{}~\index{set() (jinja2.MemcachedBytecodeCache.MinimalClientInterface method)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.MemcachedBytecodeCache.MinimalClientInterface.set}\pysiglinewithargsret{\bfcode{set}}{\emph{key}, \emph{value}\optional{, \emph{timeout}}}{}
Stores the bytecode in the cache.  \emph{value} is a string and
\emph{timeout} the timeout of the key.  If timeout is not provided
a default timeout or no timeout should be assumed, if it's
provided it's an integer with the number of seconds the cache
item should exist.

\end{fulllineitems}

\index{get() (jinja2.MemcachedBytecodeCache.MinimalClientInterface method)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.MemcachedBytecodeCache.MinimalClientInterface.get}\pysiglinewithargsret{\bfcode{get}}{\emph{key}}{}
Returns the value for the cache key.  If the item does not
exist in the cache the return value must be \emph{None}.

\end{fulllineitems}


\end{fulllineitems}


The other arguments to the constructor are the prefix for all keys that
is added before the actual cache key and the timeout for the bytecode in
the cache system.  We recommend a high (or no) timeout.

This bytecode cache does not support clearing of used items in the cache.
The clear method is a no-operation function.

\end{fulllineitems}



\section{Utilities}
\label{api:utilities}
These helper functions and classes are useful if you add custom filters or
functions to a Jinja2 environment.
\index{environmentfilter() (in module jinja2)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.environmentfilter}\pysiglinewithargsret{\code{jinja2.}\bfcode{environmentfilter}}{\emph{f}}{}
Decorator for marking evironment dependent filters.  The current
{\hyperref[api:jinja2.Environment]{\code{Environment}}} is passed to the filter as first argument.

\end{fulllineitems}

\index{contextfilter() (in module jinja2)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.contextfilter}\pysiglinewithargsret{\code{jinja2.}\bfcode{contextfilter}}{\emph{f}}{}
Decorator for marking context dependent filters. The current
\code{Context} will be passed as first argument.

\end{fulllineitems}

\index{evalcontextfilter() (in module jinja2)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.evalcontextfilter}\pysiglinewithargsret{\code{jinja2.}\bfcode{evalcontextfilter}}{\emph{f}}{}
Decorator for marking eval-context dependent filters.  An eval
context object is passed as first argument.  For more information
about the eval context, see {\hyperref[api:eval-context]{\emph{Evaluation Context}}}.
New in version 2.4.
\end{fulllineitems}

\index{environmentfunction() (in module jinja2)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.environmentfunction}\pysiglinewithargsret{\code{jinja2.}\bfcode{environmentfunction}}{\emph{f}}{}
This decorator can be used to mark a function or method as environment
callable.  This decorator works exactly like the {\hyperref[api:jinja2.contextfunction]{\code{contextfunction()}}}
decorator just that the first argument is the active {\hyperref[api:jinja2.Environment]{\code{Environment}}}
and not context.

\end{fulllineitems}

\index{contextfunction() (in module jinja2)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.contextfunction}\pysiglinewithargsret{\code{jinja2.}\bfcode{contextfunction}}{\emph{f}}{}
This decorator can be used to mark a function or method context callable.
A context callable is passed the active \code{Context} as first argument when
called from the template.  This is useful if a function wants to get access
to the context or functions provided on the context object.  For example
a function that returns a sorted list of template variables the current
template exports could look like this:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nd}{@contextfunction}
\PYG{k}{def} \PYG{n+nf}{get\PYGZus{}exported\PYGZus{}names}\PYG{p}{(}\PYG{n}{context}\PYG{p}{)}\PYG{p}{:}
    \PYG{k}{return} \PYG{n+nb}{sorted}\PYG{p}{(}\PYG{n}{context}\PYG{o}{.}\PYG{n}{exported\PYGZus{}vars}\PYG{p}{)}
\end{Verbatim}

\end{fulllineitems}

\index{evalcontextfunction() (in module jinja2)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.evalcontextfunction}\pysiglinewithargsret{\code{jinja2.}\bfcode{evalcontextfunction}}{\emph{f}}{}
This decoraotr can be used to mark a function or method as an eval
context callable.  This is similar to the {\hyperref[api:jinja2.contextfunction]{\code{contextfunction()}}}
but instead of passing the context, an evaluation context object is
passed.  For more information about the eval context, see
{\hyperref[api:eval-context]{\emph{Evaluation Context}}}.
New in version 2.4.
\end{fulllineitems}

\index{escape() (in module jinja2)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.escape}\pysiglinewithargsret{\code{jinja2.}\bfcode{escape}}{\emph{s}}{}
Convert the characters \code{\&}, \code{\textless{}}, \code{\textgreater{}}, \code{'}, and \code{"} in string \emph{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.

The return value is a {\hyperref[api:jinja2.Markup]{\code{Markup}}} string.

\end{fulllineitems}

\index{clear\_caches() (in module jinja2)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.clear_caches}\pysiglinewithargsret{\code{jinja2.}\bfcode{clear\_caches}}{}{}
Jinja2 keeps internal caches for environments and lexers.  These are
used so that Jinja2 doesn't have to recreate environments and lexers all
the time.  Normally you don't have to care about that but if you are
messuring memory consumption you may want to clean the caches.

\end{fulllineitems}

\index{is\_undefined() (in module jinja2)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.is_undefined}\pysiglinewithargsret{\code{jinja2.}\bfcode{is\_undefined}}{\emph{obj}}{}
Check if the object passed is undefined.  This does nothing more than
performing an instance check against {\hyperref[api:jinja2.Undefined]{\code{Undefined}}} but looks nicer.
This can be used for custom filters or tests that want to react to
undefined variables.  For example a custom default filter can look like
this:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{k}{def} \PYG{n+nf}{default}\PYG{p}{(}\PYG{n}{var}\PYG{p}{,} \PYG{n}{default}\PYG{o}{=}\PYG{l+s}{'}\PYG{l+s}{'}\PYG{p}{)}\PYG{p}{:}
    \PYG{k}{if} \PYG{n}{is\PYGZus{}undefined}\PYG{p}{(}\PYG{n}{var}\PYG{p}{)}\PYG{p}{:}
        \PYG{k}{return} \PYG{n}{default}
    \PYG{k}{return} \PYG{n}{var}
\end{Verbatim}

\end{fulllineitems}

\index{Markup (class in jinja2)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Markup}\pysiglinewithargsret{\strong{class }\code{jinja2.}\bfcode{Markup}}{\optional{\emph{string}}}{}
Marks a string as being safe for inclusion in HTML/XML output without
needing to be escaped.  This implements the \emph{\_\_html\_\_} interface a couple
of frameworks and web applications use.  {\hyperref[api:jinja2.Markup]{\code{Markup}}} is a direct
subclass of \emph{unicode} and provides all the methods of \emph{unicode} just that
it escapes arguments passed and always returns \emph{Markup}.

The \emph{escape} function returns markup objects so that double escaping can't
happen.

The constructor of the {\hyperref[api:jinja2.Markup]{\code{Markup}}} class can be used for three
different things:  When passed an unicode object it's assumed to be safe,
when passed an object with an HTML representation (has an \emph{\_\_html\_\_}
method) that representation is used, otherwise the object passed is
converted into a unicode string and then assumed to be safe:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{Markup}\PYG{p}{(}\PYG{l+s}{"}\PYG{l+s}{Hello \textless{}em\textgreater{}World\textless{}/em\textgreater{}!}\PYG{l+s}{"}\PYG{p}{)}
\PYG{g+go}{Markup(u'Hello \textless{}em\textgreater{}World\textless{}/em\textgreater{}!')}
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{k}{class} \PYG{n+nc}{Foo}\PYG{p}{(}\PYG{n+nb}{object}\PYG{p}{)}\PYG{p}{:}
\PYG{g+gp}{... } \PYG{k}{def} \PYG{n+nf}{\PYGZus{}\PYGZus{}html\PYGZus{}\PYGZus{}}\PYG{p}{(}\PYG{n+nb+bp}{self}\PYG{p}{)}\PYG{p}{:}
\PYG{g+gp}{... }  \PYG{k}{return} \PYG{l+s}{'}\PYG{l+s}{\textless{}a href=}\PYG{l+s}{"}\PYG{l+s}{\#}\PYG{l+s}{"}\PYG{l+s}{\textgreater{}foo\textless{}/a\textgreater{}}\PYG{l+s}{'}
\PYG{g+gp}{... }
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{Markup}\PYG{p}{(}\PYG{n}{Foo}\PYG{p}{(}\PYG{p}{)}\PYG{p}{)}
\PYG{g+go}{Markup(u'\textless{}a href="\#"\textgreater{}foo\textless{}/a\textgreater{}')}
\end{Verbatim}

If you want object passed being always treated as unsafe you can use the
{\hyperref[templates:escape]{\code{escape()}}} classmethod to create a {\hyperref[api:jinja2.Markup]{\code{Markup}}} object:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{Markup}\PYG{o}{.}\PYG{n}{escape}\PYG{p}{(}\PYG{l+s}{"}\PYG{l+s}{Hello \textless{}em\textgreater{}World\textless{}/em\textgreater{}!}\PYG{l+s}{"}\PYG{p}{)}
\PYG{g+go}{Markup(u'Hello \&lt;em\&gt;World\&lt;/em\&gt;!')}
\end{Verbatim}

Operations on a markup string are markup aware which means that all
arguments are passed through the {\hyperref[templates:escape]{\code{escape()}}} function:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{em} \PYG{o}{=} \PYG{n}{Markup}\PYG{p}{(}\PYG{l+s}{"}\PYG{l+s}{\textless{}em\textgreater{}}\PYG{l+s+si}{\%s}\PYG{l+s}{\textless{}/em\textgreater{}}\PYG{l+s}{"}\PYG{p}{)}
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{em} \PYG{o}{\%} \PYG{l+s}{"}\PYG{l+s}{foo \& bar}\PYG{l+s}{"}
\PYG{g+go}{Markup(u'\textless{}em\textgreater{}foo \&amp; bar\textless{}/em\textgreater{}')}
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{strong} \PYG{o}{=} \PYG{n}{Markup}\PYG{p}{(}\PYG{l+s}{"}\PYG{l+s}{\textless{}strong\textgreater{}}\PYG{l+s+si}{\%(text)s}\PYG{l+s}{\textless{}/strong\textgreater{}}\PYG{l+s}{"}\PYG{p}{)}
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{strong} \PYG{o}{\%} \PYG{p}{\PYGZob{}}\PYG{l+s}{'}\PYG{l+s}{text}\PYG{l+s}{'}\PYG{p}{:} \PYG{l+s}{'}\PYG{l+s}{\textless{}blink\textgreater{}hacker here\textless{}/blink\textgreater{}}\PYG{l+s}{'}\PYG{p}{\PYGZcb{}}
\PYG{g+go}{Markup(u'\textless{}strong\textgreater{}\&lt;blink\&gt;hacker here\&lt;/blink\&gt;\textless{}/strong\textgreater{}')}
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{Markup}\PYG{p}{(}\PYG{l+s}{"}\PYG{l+s}{\textless{}em\textgreater{}Hello\textless{}/em\textgreater{} }\PYG{l+s}{"}\PYG{p}{)} \PYG{o}{+} \PYG{l+s}{"}\PYG{l+s}{\textless{}foo\textgreater{}}\PYG{l+s}{"}
\PYG{g+go}{Markup(u'\textless{}em\textgreater{}Hello\textless{}/em\textgreater{} \&lt;foo\&gt;')}
\end{Verbatim}
\index{escape() (jinja2.Markup class method)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Markup.escape}\pysiglinewithargsret{\strong{classmethod }\bfcode{escape}}{\emph{s}}{}
Escape the string.  Works like {\hyperref[templates:escape]{\code{escape()}}} with the difference
that for subclasses of {\hyperref[api:jinja2.Markup]{\code{Markup}}} this function would return the
correct subclass.

\end{fulllineitems}

\index{unescape() (jinja2.Markup method)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Markup.unescape}\pysiglinewithargsret{\bfcode{unescape}}{}{}
Unescape markup again into an unicode string.  This also resolves
known HTML4 and XHTML entities:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{Markup}\PYG{p}{(}\PYG{l+s}{"}\PYG{l+s}{Main \&raquo; \textless{}em\textgreater{}About\textless{}/em\textgreater{}}\PYG{l+s}{"}\PYG{p}{)}\PYG{o}{.}\PYG{n}{unescape}\PYG{p}{(}\PYG{p}{)}
\PYG{g+go}{u'Main \PYGZbs{}xbb \textless{}em\textgreater{}About\textless{}/em\textgreater{}'}
\end{Verbatim}

\end{fulllineitems}

\index{striptags() (jinja2.Markup method)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Markup.striptags}\pysiglinewithargsret{\bfcode{striptags}}{}{}
Unescape markup into an unicode string and strip all tags.  This
also resolves known HTML4 and XHTML entities.  Whitespace is
normalized to one:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{Markup}\PYG{p}{(}\PYG{l+s}{"}\PYG{l+s}{Main \&raquo;  \textless{}em\textgreater{}About\textless{}/em\textgreater{}}\PYG{l+s}{"}\PYG{p}{)}\PYG{o}{.}\PYG{n}{striptags}\PYG{p}{(}\PYG{p}{)}
\PYG{g+go}{u'Main \PYGZbs{}xbb About'}
\end{Verbatim}

\end{fulllineitems}


\end{fulllineitems}


\begin{notice}{note}{Note}

The Jinja2 {\hyperref[api:jinja2.Markup]{\code{Markup}}} class is compatible with at least Pylons and
Genshi.  It's expected that more template engines and framework will pick
up the \emph{\_\_html\_\_} concept soon.
\end{notice}


\section{Exceptions}
\label{api:exceptions}\index{TemplateError}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.TemplateError}\pysiglinewithargsret{\strong{exception }\code{jinja2.}\bfcode{TemplateError}}{\emph{message=None}}{}
Baseclass for all template errors.

\end{fulllineitems}

\index{UndefinedError}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.UndefinedError}\pysiglinewithargsret{\strong{exception }\code{jinja2.}\bfcode{UndefinedError}}{\emph{message=None}}{}
Raised if a template tries to operate on {\hyperref[api:jinja2.Undefined]{\code{Undefined}}}.

\end{fulllineitems}

\index{TemplateNotFound}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.TemplateNotFound}\pysiglinewithargsret{\strong{exception }\code{jinja2.}\bfcode{TemplateNotFound}}{\emph{name}, \emph{message=None}}{}
Raised if a template does not exist.

\end{fulllineitems}

\index{TemplatesNotFound}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.TemplatesNotFound}\pysiglinewithargsret{\strong{exception }\code{jinja2.}\bfcode{TemplatesNotFound}}{\emph{names=()}, \emph{message=None}}{}
Like {\hyperref[api:jinja2.TemplateNotFound]{\code{TemplateNotFound}}} but raised if multiple templates
are selected.  This is a subclass of {\hyperref[api:jinja2.TemplateNotFound]{\code{TemplateNotFound}}}
exception, so just catching the base exception will catch both.
New in version 2.2.
\end{fulllineitems}

\index{TemplateSyntaxError}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.TemplateSyntaxError}\pysiglinewithargsret{\strong{exception }\code{jinja2.}\bfcode{TemplateSyntaxError}}{\emph{message}, \emph{lineno}, \emph{name=None}, \emph{filename=None}}{}
Raised to tell the user that there is a problem with the template.
\index{message (jinja2.TemplateSyntaxError attribute)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.TemplateSyntaxError.message}\pysigline{\bfcode{message}}{}
The error message as utf-8 bytestring.

\end{fulllineitems}

\index{lineno (jinja2.TemplateSyntaxError attribute)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.TemplateSyntaxError.lineno}\pysigline{\bfcode{lineno}}{}
The line number where the error occurred

\end{fulllineitems}

\index{name (jinja2.TemplateSyntaxError attribute)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.TemplateSyntaxError.name}\pysigline{\bfcode{name}}{}
The load name for the template as unicode string.

\end{fulllineitems}

\index{filename (jinja2.TemplateSyntaxError attribute)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.TemplateSyntaxError.filename}\pysigline{\bfcode{filename}}{}
The filename that loaded the template as bytestring in the encoding
of the file system (most likely utf-8 or mbcs on Windows systems).

\end{fulllineitems}


The reason why the filename and error message are bytestrings and not
unicode strings is that Python 2.x is not using unicode for exceptions
and tracebacks as well as the compiler.  This will change with Python 3.

\end{fulllineitems}

\index{TemplateAssertionError}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.TemplateAssertionError}\pysiglinewithargsret{\strong{exception }\code{jinja2.}\bfcode{TemplateAssertionError}}{\emph{message}, \emph{lineno}, \emph{name=None}, \emph{filename=None}}{}
Like a template syntax error, but covers cases where something in the
template caused an error at compile time that wasn't necessarily caused
by a syntax error.  However it's a direct subclass of
{\hyperref[api:jinja2.TemplateSyntaxError]{\code{TemplateSyntaxError}}} and has the same attributes.

\end{fulllineitems}



\section{Custom Filters}
\label{api:custom-filters}\label{api:writing-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 \code{\{\{ 42\textbar{}myfilter(23) \}\}} the function would be
called with \code{myfilter(42, 23)}.  Here for example a simple filter that can
be applied to datetime objects to format them:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{k}{def} \PYG{n+nf}{datetimeformat}\PYG{p}{(}\PYG{n}{value}\PYG{p}{,} \PYG{n}{format}\PYG{o}{=}\PYG{l+s}{'}\PYG{l+s}{\%}\PYG{l+s}{H:}\PYG{l+s}{\%}\PYG{l+s}{M / }\PYG{l+s+si}{\%d}\PYG{l+s}{-}\PYG{l+s}{\%}\PYG{l+s}{m-}\PYG{l+s}{\%}\PYG{l+s}{Y}\PYG{l+s}{'}\PYG{p}{)}\PYG{p}{:}
    \PYG{k}{return} \PYG{n}{value}\PYG{o}{.}\PYG{n}{strftime}\PYG{p}{(}\PYG{n}{format}\PYG{p}{)}
\end{Verbatim}

You can register it on the template environment by updating the
{\hyperref[api:jinja2.Environment.filters]{\code{filters}}} dict on the environment:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n}{environment}\PYG{o}{.}\PYG{n}{filters}\PYG{p}{[}\PYG{l+s}{'}\PYG{l+s}{datetimeformat}\PYG{l+s}{'}\PYG{p}{]} \PYG{o}{=} \PYG{n}{datetimeformat}
\end{Verbatim}

Inside the template it can then be used as follows:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{x}{written on: }\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{article}\PYG{n+nv}{.pub\PYGZus{}date}\PYG{o}{\textbar{}}\PYG{n+nf}{datetimeformat} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}
\PYG{x}{publication date: }\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{article}\PYG{n+nv}{.pub\PYGZus{}date}\PYG{o}{\textbar{}}\PYG{n+nf}{datetimeformat}\PYG{o}{(}\PYG{l+s+s1}{'\%d-\%m-\%Y'}\PYG{o}{)} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}
\end{Verbatim}

Filters can also be passed the current template context or environment.  This
is useful if a filter wants to return an undefined value or check the current
\code{autoescape} setting.  For this purpose three decorators
exist: {\hyperref[api:jinja2.environmentfilter]{\code{environmentfilter()}}}, {\hyperref[api:jinja2.contextfilter]{\code{contextfilter()}}} and
{\hyperref[api:jinja2.evalcontextfilter]{\code{evalcontextfilter()}}}.

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:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{k+kn}{import} \PYG{n+nn}{re}
\PYG{k+kn}{from} \PYG{n+nn}{jinja2} \PYG{k+kn}{import} \PYG{n}{environmentfilter}\PYG{p}{,} \PYG{n}{Markup}\PYG{p}{,} \PYG{n}{escape}

\PYG{n}{\PYGZus{}paragraph\PYGZus{}re} \PYG{o}{=} \PYG{n}{re}\PYG{o}{.}\PYG{n}{compile}\PYG{p}{(}\PYG{l+s}{r'}\PYG{l+s}{(?:}\PYG{l+s}{\PYGZbs{}}\PYG{l+s}{r}\PYG{l+s}{\PYGZbs{}}\PYG{l+s}{n\textbar{}}\PYG{l+s}{\PYGZbs{}}\PYG{l+s}{r\textbar{}}\PYG{l+s}{\PYGZbs{}}\PYG{l+s}{n)\PYGZob{}2,\PYGZcb{}}\PYG{l+s}{'}\PYG{p}{)}

\PYG{n+nd}{@evalcontextfilter}
\PYG{k}{def} \PYG{n+nf}{nl2br}\PYG{p}{(}\PYG{n}{eval\PYGZus{}ctx}\PYG{p}{,} \PYG{n}{value}\PYG{p}{)}\PYG{p}{:}
    \PYG{n}{result} \PYG{o}{=} \PYG{l+s}{u'}\PYG{l+s+se}{\PYGZbs{}n}\PYG{l+s+se}{\PYGZbs{}n}\PYG{l+s}{'}\PYG{o}{.}\PYG{n}{join}\PYG{p}{(}\PYG{l+s}{u'}\PYG{l+s}{\textless{}p\textgreater{}}\PYG{l+s+si}{\%s}\PYG{l+s}{\textless{}/p\textgreater{}}\PYG{l+s}{'} \PYG{o}{\%} \PYG{n}{p}\PYG{o}{.}\PYG{n}{replace}\PYG{p}{(}\PYG{l+s}{'}\PYG{l+s+se}{\PYGZbs{}n}\PYG{l+s}{'}\PYG{p}{,} \PYG{l+s}{'}\PYG{l+s}{\textless{}br\textgreater{}}\PYG{l+s+se}{\PYGZbs{}n}\PYG{l+s}{'}\PYG{p}{)}
                          \PYG{k}{for} \PYG{n}{p} \PYG{o+ow}{in} \PYG{n}{\PYGZus{}paragraph\PYGZus{}re}\PYG{o}{.}\PYG{n}{split}\PYG{p}{(}\PYG{n}{escape}\PYG{p}{(}\PYG{n}{value}\PYG{p}{)}\PYG{p}{)}\PYG{p}{)}
    \PYG{k}{if} \PYG{n}{eval\PYGZus{}ctx}\PYG{o}{.}\PYG{n}{autoescape}\PYG{p}{:}
        \PYG{n}{result} \PYG{o}{=} \PYG{n}{Markup}\PYG{p}{(}\PYG{n}{result}\PYG{p}{)}
    \PYG{k}{return} \PYG{n}{result}
\end{Verbatim}

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


\section{Evaluation Context}
\label{api:eval-context}\label{api:evaluation-context}
The evaluation context (short eval context or eval ctx) is a new object
introducted in Jinja 2.4 that makes it possible to activate and deactivate
compiled features at runtime.

Currently it is only used to enable and disable the automatic escaping but
can be used for extensions as well.

In previous Jinja versions filters and functions were marked as
environment callables in order to check for the autoescape status from the
environment.  In new versions it's encouraged to check the setting from the
evaluation context instead.

Previous versions:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nd}{@environmentfilter}
\PYG{k}{def} \PYG{n+nf}{filter}\PYG{p}{(}\PYG{n}{env}\PYG{p}{,} \PYG{n}{value}\PYG{p}{)}\PYG{p}{:}
    \PYG{n}{result} \PYG{o}{=} \PYG{n}{do\PYGZus{}something}\PYG{p}{(}\PYG{n}{value}\PYG{p}{)}
    \PYG{k}{if} \PYG{n}{env}\PYG{o}{.}\PYG{n}{autoescape}\PYG{p}{:}
        \PYG{n}{result} \PYG{o}{=} \PYG{n}{Markup}\PYG{p}{(}\PYG{n}{result}\PYG{p}{)}
    \PYG{k}{return} \PYG{n}{result}
\end{Verbatim}

In new versions you can either use a {\hyperref[api:jinja2.contextfilter]{\code{contextfilter()}}} and access the
evaluation context from the actual context, or use a
{\hyperref[api:jinja2.evalcontextfilter]{\code{evalcontextfilter()}}} which directly passes the evaluation context to
the function:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nd}{@contextfilter}
\PYG{k}{def} \PYG{n+nf}{filter}\PYG{p}{(}\PYG{n}{context}\PYG{p}{,} \PYG{n}{value}\PYG{p}{)}\PYG{p}{:}
    \PYG{n}{result} \PYG{o}{=} \PYG{n}{do\PYGZus{}something}\PYG{p}{(}\PYG{n}{value}\PYG{p}{)}
    \PYG{k}{if} \PYG{n}{context}\PYG{o}{.}\PYG{n}{eval\PYGZus{}ctx}\PYG{o}{.}\PYG{n}{autoescape}\PYG{p}{:}
        \PYG{n}{result} \PYG{o}{=} \PYG{n}{Markup}\PYG{p}{(}\PYG{n}{result}\PYG{p}{)}
    \PYG{k}{return} \PYG{n}{result}

\PYG{n+nd}{@evalcontextfilter}
\PYG{k}{def} \PYG{n+nf}{filter}\PYG{p}{(}\PYG{n}{eval\PYGZus{}ctx}\PYG{p}{,} \PYG{n}{value}\PYG{p}{)}\PYG{p}{:}
    \PYG{n}{result} \PYG{o}{=} \PYG{n}{do\PYGZus{}something}\PYG{p}{(}\PYG{n}{value}\PYG{p}{)}
    \PYG{k}{if} \PYG{n}{eval\PYGZus{}ctx}\PYG{o}{.}\PYG{n}{autoescape}\PYG{p}{:}
        \PYG{n}{result} \PYG{o}{=} \PYG{n}{Markup}\PYG{p}{(}\PYG{n}{result}\PYG{p}{)}
    \PYG{k}{return} \PYG{n}{result}
\end{Verbatim}

The evaluation context must not be modified at runtime.  Modifications
must only happen with a {\hyperref[extensions:jinja2.nodes.EvalContextModifier]{\code{nodes.EvalContextModifier}}} and
{\hyperref[extensions:jinja2.nodes.ScopedEvalContextModifier]{\code{nodes.ScopedEvalContextModifier}}} from an extension, not on the
eval context object itself.
\index{EvalContext (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.nodes.EvalContext}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{EvalContext}}{\emph{environment}, \emph{template\_name=None}}{}
Holds evaluation time information.  Custom attributes can be attached
to it in extensions.
\index{autoescape (jinja2.EvalContext attribute)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.EvalContext.autoescape}\pysigline{\bfcode{autoescape}}{}
\emph{True} or \emph{False} depending on if autoescaping is active or not.

\end{fulllineitems}

\index{volatile (jinja2.EvalContext attribute)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.EvalContext.volatile}\pysigline{\bfcode{volatile}}{}
\emph{True} if the compiler cannot evaluate some expressions at compile
time.  At runtime this should always be \emph{False}.

\end{fulllineitems}


\end{fulllineitems}



\section{Custom Tests}
\label{api:writing-tests}\label{api:custom-tests}
Tests work like filters just that there is no way for a test to get access
to the environment or context and that they can't be chained.  The return
value of a test should be \emph{True} or \emph{False}.  The purpose of a test is to
give the template designers the possibility to perform type and conformability
checks.

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

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{k+kn}{import} \PYG{n+nn}{math}

\PYG{k}{def} \PYG{n+nf}{is\PYGZus{}prime}\PYG{p}{(}\PYG{n}{n}\PYG{p}{)}\PYG{p}{:}
    \PYG{k}{if} \PYG{n}{n} \PYG{o}{==} \PYG{l+m+mi}{2}\PYG{p}{:}
        \PYG{k}{return} \PYG{n+nb+bp}{True}
    \PYG{k}{for} \PYG{n}{i} \PYG{o+ow}{in} \PYG{n+nb}{xrange}\PYG{p}{(}\PYG{l+m+mi}{2}\PYG{p}{,} \PYG{n+nb}{int}\PYG{p}{(}\PYG{n}{math}\PYG{o}{.}\PYG{n}{ceil}\PYG{p}{(}\PYG{n}{math}\PYG{o}{.}\PYG{n}{sqrt}\PYG{p}{(}\PYG{n}{n}\PYG{p}{)}\PYG{p}{)}\PYG{p}{)} \PYG{o}{+} \PYG{l+m+mi}{1}\PYG{p}{)}\PYG{p}{:}
        \PYG{k}{if} \PYG{n}{n} \PYG{o}{\%} \PYG{n}{i} \PYG{o}{==} \PYG{l+m+mi}{0}\PYG{p}{:}
            \PYG{k}{return} \PYG{n+nb+bp}{False}
    \PYG{k}{return} \PYG{n+nb+bp}{True}
\end{Verbatim}

You can register it on the template environment by updating the
{\hyperref[api:jinja2.Environment.tests]{\code{tests}}} dict on the environment:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n}{environment}\PYG{o}{.}\PYG{n}{tests}\PYG{p}{[}\PYG{l+s}{'}\PYG{l+s}{prime}\PYG{l+s}{'}\PYG{p}{]} \PYG{o}{=} \PYG{n}{is\PYGZus{}prime}
\end{Verbatim}

A template designer can then use the test like this:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{if} \PYG{l+m}{4}\PYG{l+m}{2} \PYG{k}{is} \PYG{n+nf}{prime} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{x}{    42 is a prime number}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{else} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{x}{    42 is not a prime number}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endif} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}


\section{The Global Namespace}
\label{api:the-global-namespace}\label{api:global-namespace}
Variables stored in the {\hyperref[api:jinja2.Environment.globals]{\code{Environment.globals}}} dict are special as they
are available for imported templates too, even if they are imported without
context.  This is the place where you can put variables and functions
that should be available all the time.  Additionally {\hyperref[api:jinja2.Template.globals]{\code{Template.globals}}}
exist that are variables available to a specific template that are available
to all {\hyperref[api:jinja2.Template.render]{\code{render()}}} calls.


\section{Low Level API}
\label{api:low-level-api}\label{api:id3}
The low level API exposes functionality that can be useful to understand some
implementation details, debugging purposes or advanced {\hyperref[extensions:jinja-extensions]{\emph{extension}}} techniques.  Unless you know exactly what you are doing we
don't recommend using any of those.
\index{lex() (jinja2.Environment method)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Environment.lex}\pysiglinewithargsret{\code{Environment.}\bfcode{lex}}{\emph{source}, \emph{name=None}, \emph{filename=None}}{}
Lex the given sourcecode and return a generator that yields
tokens as tuples in the form \code{(lineno, token\_type, value)}.
This can be useful for {\hyperref[extensions:writing-extensions]{\emph{extension development}}}
and debugging templates.

This does not perform preprocessing.  If you want the preprocessing
of the extensions to be applied you have to filter source through
the {\hyperref[api:jinja2.Environment.preprocess]{\code{preprocess()}}} method.

\end{fulllineitems}

\index{parse() (jinja2.Environment method)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Environment.parse}\pysiglinewithargsret{\code{Environment.}\bfcode{parse}}{\emph{source}, \emph{name=None}, \emph{filename=None}}{}
Parse the sourcecode and return the abstract syntax tree.  This
tree of nodes is used by the compiler to convert the template into
executable source- or bytecode.  This is useful for debugging or to
extract information from templates.

If you are {\hyperref[extensions:writing-extensions]{\emph{developing Jinja2 extensions}}}
this gives you a good overview of the node tree generated.

\end{fulllineitems}

\index{preprocess() (jinja2.Environment method)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Environment.preprocess}\pysiglinewithargsret{\code{Environment.}\bfcode{preprocess}}{\emph{source}, \emph{name=None}, \emph{filename=None}}{}
Preprocesses the source with all extensions.  This is automatically
called for all parsing and compiling methods but \emph{not} for {\hyperref[api:jinja2.Environment.lex]{\code{lex()}}}
because there you usually only want the actual source tokenized.

\end{fulllineitems}

\index{new\_context() (jinja2.Template method)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Template.new_context}\pysiglinewithargsret{\code{Template.}\bfcode{new\_context}}{\emph{vars=None}, \emph{shared=False}, \emph{locals=None}}{}
Create a new \code{Context} for this template.  The vars
provided will be passed to the template.  Per default the globals
are added to the context.  If shared is set to \emph{True} the data
is passed as it to the context without adding the globals.

\emph{locals} can be a dict of local variables for internal usage.

\end{fulllineitems}

\index{root\_render\_func() (jinja2.Template method)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Template.root_render_func}\pysiglinewithargsret{\code{Template.}\bfcode{root\_render\_func}}{\emph{context}}{}
This is the low level render function.  It's passed a \code{Context}
that has to be created by {\hyperref[api:jinja2.Template.new_context]{\code{new\_context()}}} of the same template or
a compatible template.  This render function is generated by the
compiler from the template code and returns a generator that yields
unicode strings.

If an exception in the template code happens the template engine will
not rewrite the exception but pass through the original one.  As a
matter of fact this function should only be called from within a
{\hyperref[api:jinja2.Template.render]{\code{render()}}} / {\hyperref[api:jinja2.Template.generate]{\code{generate()}}} / {\hyperref[api:jinja2.Template.stream]{\code{stream()}}} call.

\end{fulllineitems}

\index{blocks (jinja2.Template attribute)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Template.blocks}\pysigline{\code{Template.}\bfcode{blocks}}{}
A dict of block render functions.  Each of these functions works exactly
like the {\hyperref[api:jinja2.Template.root_render_func]{\code{root\_render\_func()}}} with the same limitations.

\end{fulllineitems}

\index{is\_up\_to\_date (jinja2.Template attribute)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.Template.is_up_to_date}\pysigline{\code{Template.}\bfcode{is\_up\_to\_date}}{}
This attribute is \emph{False} if there is a newer version of the template
available, otherwise \emph{True}.

\end{fulllineitems}


\begin{notice}{note}{Note}

The low-level API is fragile.  Future Jinja2 versions will try not to
change it in a backwards incompatible way but modifications in the Jinja2
core may shine through.  For example if Jinja2 introduces a new AST node
in later versions that may be returned by {\hyperref[api:jinja2.Environment.parse]{\code{parse()}}}.
\end{notice}


\section{The Meta API}
\label{api:the-meta-api}New in version 2.2.
The meta API returns some information about abstract syntax trees that
could help applications to implement more advanced template concepts.  All
the functions of the meta API operate on an abstract syntax tree as
returned by the {\hyperref[api:jinja2.Environment.parse]{\code{Environment.parse()}}} method.
\index{find\_undeclared\_variables() (in module jinja2.meta)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.meta.find_undeclared_variables}\pysiglinewithargsret{\code{jinja2.meta.}\bfcode{find\_undeclared\_variables}}{\emph{ast}}{}
Returns a set of all variables in the AST that will be looked up from
the context at runtime.  Because at compile time it's not known which
variables will be used depending on the path the execution takes at
runtime, all variables are returned.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{k+kn}{from} \PYG{n+nn}{jinja2} \PYG{k+kn}{import} \PYG{n}{Environment}\PYG{p}{,} \PYG{n}{meta}
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{env} \PYG{o}{=} \PYG{n}{Environment}\PYG{p}{(}\PYG{p}{)}
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{ast} \PYG{o}{=} \PYG{n}{env}\PYG{o}{.}\PYG{n}{parse}\PYG{p}{(}\PYG{l+s}{'}\PYG{l+s}{\PYGZob{}}\PYG{l+s+si}{\% s}\PYG{l+s}{et foo = 42 }\PYG{l+s}{\%}\PYG{l+s}{\PYGZcb{}\PYGZob{}\PYGZob{} bar + foo \PYGZcb{}\PYGZcb{}}\PYG{l+s}{'}\PYG{p}{)}
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{meta}\PYG{o}{.}\PYG{n}{find\PYGZus{}undeclared\PYGZus{}variables}\PYG{p}{(}\PYG{n}{ast}\PYG{p}{)}
\PYG{g+go}{set(['bar'])}
\end{Verbatim}

\begin{notice}{note}{Implementation}

Internally the code generator is used for finding undeclared variables.
This is good to know because the code generator might raise a
{\hyperref[api:jinja2.TemplateAssertionError]{\code{TemplateAssertionError}}} during compilation and as a matter of
fact this function can currently raise that exception as well.
\end{notice}

\end{fulllineitems}

\index{find\_referenced\_templates() (in module jinja2.meta)}

\begin{fulllineitems}
\phantomsection\label{api:jinja2.meta.find_referenced_templates}\pysiglinewithargsret{\code{jinja2.meta.}\bfcode{find\_referenced\_templates}}{\emph{ast}}{}
Finds all the referenced templates from the AST.  This will return an
iterator over all the hardcoded template extensions, inclusions and
imports.  If dynamic inheritance or inclusion is used, \emph{None} will be
yielded.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{k+kn}{from} \PYG{n+nn}{jinja2} \PYG{k+kn}{import} \PYG{n}{Environment}\PYG{p}{,} \PYG{n}{meta}
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{env} \PYG{o}{=} \PYG{n}{Environment}\PYG{p}{(}\PYG{p}{)}
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{ast} \PYG{o}{=} \PYG{n}{env}\PYG{o}{.}\PYG{n}{parse}\PYG{p}{(}\PYG{l+s}{'}\PYG{l+s}{\PYGZob{}}\PYG{l+s+si}{\% e}\PYG{l+s}{xtends }\PYG{l+s}{"}\PYG{l+s}{layout.html}\PYG{l+s}{"}\PYG{l+s}{ }\PYG{l+s}{\%}\PYG{l+s}{\PYGZcb{}\PYGZob{}}\PYG{l+s+si}{\% i}\PYG{l+s}{nclude helper }\PYG{l+s}{\%}\PYG{l+s}{\PYGZcb{}}\PYG{l+s}{'}\PYG{p}{)}
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n+nb}{list}\PYG{p}{(}\PYG{n}{meta}\PYG{o}{.}\PYG{n}{find\PYGZus{}referenced\PYGZus{}templates}\PYG{p}{(}\PYG{n}{ast}\PYG{p}{)}\PYG{p}{)}
\PYG{g+go}{['layout.html', None]}
\end{Verbatim}

This function is useful for dependency tracking.  For example if you want
to rebuild parts of the website after a layout template has changed.

\end{fulllineitems}



\chapter{Sandbox}
\label{sandbox:sandbox}\label{sandbox::doc}
The Jinja2 sandbox can be used to evaluate untrusted code.  Access to unsafe
attributes and methods is prohibited.

Assuming \emph{env} is a \code{SandboxedEnvironment} in the default configuration
the following piece of code shows how it works:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{env}\PYG{o}{.}\PYG{n}{from\PYGZus{}string}\PYG{p}{(}\PYG{l+s}{"}\PYG{l+s}{\PYGZob{}\PYGZob{} func.func\PYGZus{}code \PYGZcb{}\PYGZcb{}}\PYG{l+s}{"}\PYG{p}{)}\PYG{o}{.}\PYG{n}{render}\PYG{p}{(}\PYG{n}{func}\PYG{o}{=}\PYG{k}{lambda}\PYG{p}{:}\PYG{n+nb+bp}{None}\PYG{p}{)}
\PYG{g+go}{u''}
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{env}\PYG{o}{.}\PYG{n}{from\PYGZus{}string}\PYG{p}{(}\PYG{l+s}{"}\PYG{l+s}{\PYGZob{}\PYGZob{} func.func\PYGZus{}code.do\PYGZus{}something \PYGZcb{}\PYGZcb{}}\PYG{l+s}{"}\PYG{p}{)}\PYG{o}{.}\PYG{n}{render}\PYG{p}{(}\PYG{n}{func}\PYG{o}{=}\PYG{k}{lambda}\PYG{p}{:}\PYG{n+nb+bp}{None}\PYG{p}{)}
\PYG{g+gt}{Traceback (most recent call last):}
  \PYG{c}{...}
\PYG{n+nc}{SecurityError}: \PYG{n+nIdentifier}{access to attribute 'func\PYGZus{}code' of 'function' object is unsafe.}
\end{Verbatim}
\phantomsection\label{sandbox:module-jinja2.sandbox}\index{jinja2.sandbox (module)}\index{SandboxedEnvironment (class in jinja2.sandbox)}

\begin{fulllineitems}
\phantomsection\label{sandbox:jinja2.sandbox.SandboxedEnvironment}\pysiglinewithargsret{\strong{class }\code{jinja2.sandbox.}\bfcode{SandboxedEnvironment}}{\optional{\emph{options}}}{}
The sandboxed environment.  It works like the regular environment but
tells the compiler to generate sandboxed code.  Additionally subclasses of
this environment may override the methods that tell the runtime what
attributes or functions are safe to access.

If the template tries to access insecure code a {\hyperref[sandbox:jinja2.sandbox.SecurityError]{\code{SecurityError}}} is
raised.  However also other exceptions may occour during the rendering so
the caller has to ensure that all exceptions are catched.
\index{is\_safe\_attribute() (jinja2.sandbox.SandboxedEnvironment method)}

\begin{fulllineitems}
\phantomsection\label{sandbox:jinja2.sandbox.SandboxedEnvironment.is_safe_attribute}\pysiglinewithargsret{\bfcode{is\_safe\_attribute}}{\emph{obj}, \emph{attr}, \emph{value}}{}
The sandboxed environment will call this method to check if the
attribute of an object is safe to access.  Per default all attributes
starting with an underscore are considered private as well as the
special attributes of internal python objects as returned by the
{\hyperref[sandbox:jinja2.sandbox.is_internal_attribute]{\code{is\_internal\_attribute()}}} function.

\end{fulllineitems}

\index{is\_safe\_callable() (jinja2.sandbox.SandboxedEnvironment method)}

\begin{fulllineitems}
\phantomsection\label{sandbox:jinja2.sandbox.SandboxedEnvironment.is_safe_callable}\pysiglinewithargsret{\bfcode{is\_safe\_callable}}{\emph{obj}}{}
Check if an object is safely callable.  Per default a function is
considered safe unless the \emph{unsafe\_callable} attribute exists and is
True.  Override this method to alter the behavior, but this won't
affect the \emph{unsafe} decorator from this module.

\end{fulllineitems}


\end{fulllineitems}

\index{ImmutableSandboxedEnvironment (class in jinja2.sandbox)}

\begin{fulllineitems}
\phantomsection\label{sandbox:jinja2.sandbox.ImmutableSandboxedEnvironment}\pysiglinewithargsret{\strong{class }\code{jinja2.sandbox.}\bfcode{ImmutableSandboxedEnvironment}}{\optional{\emph{options}}}{}
Works exactly like the regular \emph{SandboxedEnvironment} but does not
permit modifications on the builtin mutable objects \emph{list}, \emph{set}, and
\emph{dict} by using the {\hyperref[sandbox:jinja2.sandbox.modifies_known_mutable]{\code{modifies\_known\_mutable()}}} function.

\end{fulllineitems}

\index{SecurityError}

\begin{fulllineitems}
\phantomsection\label{sandbox:jinja2.sandbox.SecurityError}\pysiglinewithargsret{\strong{exception }\code{jinja2.sandbox.}\bfcode{SecurityError}}{\emph{message=None}}{}
Raised if a template tries to do something insecure if the
sandbox is enabled.

\end{fulllineitems}

\index{unsafe() (in module jinja2.sandbox)}

\begin{fulllineitems}
\phantomsection\label{sandbox:jinja2.sandbox.unsafe}\pysiglinewithargsret{\code{jinja2.sandbox.}\bfcode{unsafe}}{\emph{f}}{}
Mark a function or method as unsafe:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nd}{@unsafe}
\PYG{k}{def} \PYG{n+nf}{delete}\PYG{p}{(}\PYG{n+nb+bp}{self}\PYG{p}{)}\PYG{p}{:}
    \PYG{k}{pass}
\end{Verbatim}

\end{fulllineitems}

\index{is\_internal\_attribute() (in module jinja2.sandbox)}

\begin{fulllineitems}
\phantomsection\label{sandbox:jinja2.sandbox.is_internal_attribute}\pysiglinewithargsret{\code{jinja2.sandbox.}\bfcode{is\_internal\_attribute}}{\emph{obj}, \emph{attr}}{}
Test if the attribute given is an internal python attribute.  For
example this function returns \emph{True} for the \emph{func\_code} attribute of
python objects.  This is useful if the environment method
{\hyperref[sandbox:jinja2.sandbox.SandboxedEnvironment.is_safe_attribute]{\code{is\_safe\_attribute()}}} is overriden.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{k+kn}{from} \PYG{n+nn}{jinja2.sandbox} \PYG{k+kn}{import} \PYG{n}{is\PYGZus{}internal\PYGZus{}attribute}
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{is\PYGZus{}internal\PYGZus{}attribute}\PYG{p}{(}\PYG{k}{lambda}\PYG{p}{:} \PYG{n+nb+bp}{None}\PYG{p}{,} \PYG{l+s}{"}\PYG{l+s}{func\PYGZus{}code}\PYG{l+s}{"}\PYG{p}{)}
\PYG{g+go}{True}
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{is\PYGZus{}internal\PYGZus{}attribute}\PYG{p}{(}\PYG{p}{(}\PYG{k}{lambda} \PYG{n}{x}\PYG{p}{:}\PYG{n}{x}\PYG{p}{)}\PYG{o}{.}\PYG{n}{func\PYGZus{}code}\PYG{p}{,} \PYG{l+s}{'}\PYG{l+s}{co\PYGZus{}code}\PYG{l+s}{'}\PYG{p}{)}
\PYG{g+go}{True}
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{is\PYGZus{}internal\PYGZus{}attribute}\PYG{p}{(}\PYG{n+nb}{str}\PYG{p}{,} \PYG{l+s}{"}\PYG{l+s}{upper}\PYG{l+s}{"}\PYG{p}{)}
\PYG{g+go}{False}
\end{Verbatim}

\end{fulllineitems}

\index{modifies\_known\_mutable() (in module jinja2.sandbox)}

\begin{fulllineitems}
\phantomsection\label{sandbox:jinja2.sandbox.modifies_known_mutable}\pysiglinewithargsret{\code{jinja2.sandbox.}\bfcode{modifies\_known\_mutable}}{\emph{obj}, \emph{attr}}{}
This function checks if an attribute on a builtin mutable object
(list, dict, set or deque) would modify it if called.  It also supports
the ``user''-versions of the objects (\emph{sets.Set}, \emph{UserDict.*} etc.) and
with Python 2.6 onwards the abstract base classes \emph{MutableSet},
\emph{MutableMapping}, and \emph{MutableSequence}.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{modifies\PYGZus{}known\PYGZus{}mutable}\PYG{p}{(}\PYG{p}{\PYGZob{}}\PYG{p}{\PYGZcb{}}\PYG{p}{,} \PYG{l+s}{"}\PYG{l+s}{clear}\PYG{l+s}{"}\PYG{p}{)}
\PYG{g+go}{True}
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{modifies\PYGZus{}known\PYGZus{}mutable}\PYG{p}{(}\PYG{p}{\PYGZob{}}\PYG{p}{\PYGZcb{}}\PYG{p}{,} \PYG{l+s}{"}\PYG{l+s}{keys}\PYG{l+s}{"}\PYG{p}{)}
\PYG{g+go}{False}
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{modifies\PYGZus{}known\PYGZus{}mutable}\PYG{p}{(}\PYG{p}{[}\PYG{p}{]}\PYG{p}{,} \PYG{l+s}{"}\PYG{l+s}{append}\PYG{l+s}{"}\PYG{p}{)}
\PYG{g+go}{True}
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{modifies\PYGZus{}known\PYGZus{}mutable}\PYG{p}{(}\PYG{p}{[}\PYG{p}{]}\PYG{p}{,} \PYG{l+s}{"}\PYG{l+s}{index}\PYG{l+s}{"}\PYG{p}{)}
\PYG{g+go}{False}
\end{Verbatim}

If called with an unsupported object (such as unicode) \emph{False} is
returned.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{g+gp}{\textgreater{}\textgreater{}\textgreater{} }\PYG{n}{modifies\PYGZus{}known\PYGZus{}mutable}\PYG{p}{(}\PYG{l+s}{"}\PYG{l+s}{foo}\PYG{l+s}{"}\PYG{p}{,} \PYG{l+s}{"}\PYG{l+s}{upper}\PYG{l+s}{"}\PYG{p}{)}
\PYG{g+go}{False}
\end{Verbatim}

\end{fulllineitems}


\begin{notice}{note}{Note}

The Jinja2 sandbox alone is no solution for perfect security.  Especially
for web applications you have to keep in mind that users may create
templates with arbitrary HTML in so it's crucial to ensure that (if you
are running multiple users on the same server) they can't harm each other
via JavaScript insertions and much more.

Also the sandbox is only as good as the configuration.  We stronly
recommend only passing non-shared resources to the template and use
some sort of whitelisting for attributes.

Also keep in mind that templates may raise runtime or compile time errors,
so make sure to catch them.
\end{notice}


\chapter{Template Designer Documentation}
\label{templates:template-designer-documentation}\label{templates::doc}
This document describes the syntax and semantics of the template engine and
will be most useful as reference to those creating Jinja templates.  As the
template engine is very flexible the configuration from the application might
be slightly different from here in terms of delimiters and behavior of
undefined values.


\section{Synopsis}
\label{templates:synopsis}
A template is simply a text file.  It can generate any text-based format
(HTML, XML, CSV, LaTeX, etc.).  It doesn't have a specific extension,
\code{.html} or \code{.xml} are just fine.

A template contains \textbf{variables} or \textbf{expressions}, which get replaced with
values when the template is evaluated, and tags, which control the logic of
the template.  The template syntax is heavily inspired by Django and Python.

Below is a minimal template that illustrates a few basics.  We will cover
the details later in that document:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\textless{}!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"\textgreater{}}
\PYG{n+nt}{\textless{}html} \PYG{n+na}{lang=}\PYG{l+s}{"en"}\PYG{n+nt}{\textgreater{}}
\PYG{n+nt}{\textless{}head}\PYG{n+nt}{\textgreater{}}
    \PYG{n+nt}{\textless{}title}\PYG{n+nt}{\textgreater{}}My Webpage\PYG{n+nt}{\textless{}/title\textgreater{}}
\PYG{n+nt}{\textless{}/head\textgreater{}}
\PYG{n+nt}{\textless{}body}\PYG{n+nt}{\textgreater{}}
    \PYG{n+nt}{\textless{}ul} \PYG{n+na}{id=}\PYG{l+s}{"navigation"}\PYG{n+nt}{\textgreater{}}
    \PYG{c+cp}{\PYGZob{}\%} \PYG{k}{for} \PYG{n+nv}{item} \PYG{k}{in} \PYG{n+nv}{navigation} \PYG{c+cp}{\%\PYGZcb{}}
        \PYG{n+nt}{\textless{}li}\PYG{n+nt}{\textgreater{}}\PYG{n+nt}{\textless{}a} \PYG{n+na}{href=}\PYG{l+s}{"}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{item}\PYG{n+nv}{.href} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{l+s}{"}\PYG{n+nt}{\textgreater{}}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{item}\PYG{n+nv}{.caption} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{n+nt}{\textless{}/a\textgreater{}}\PYG{n+nt}{\textless{}/li\textgreater{}}
    \PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endfor} \PYG{c+cp}{\%\PYGZcb{}}
    \PYG{n+nt}{\textless{}/ul\textgreater{}}

    \PYG{n+nt}{\textless{}h1}\PYG{n+nt}{\textgreater{}}My Webpage\PYG{n+nt}{\textless{}/h1\textgreater{}}
    \PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{a\PYGZus{}variable} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}
\PYG{n+nt}{\textless{}/body\textgreater{}}
\PYG{n+nt}{\textless{}/html\textgreater{}}
\end{Verbatim}

This covers the default settings.  The application developer might have
changed the syntax from \code{\{\% foo \%\}} to \code{\textless{}\% foo \%\textgreater{}} or something similar.

There are two kinds of delimiers. \code{\{\% ... \%\}} and \code{\{\{ ... \}\}}.  The first
one is used to execute statements such as for-loops or assign values, the
latter prints the result of the expression to the template.


\section{Variables}
\label{templates:variables}\label{templates:id1}
The application passes variables to the templates you can mess around in the
template.  Variables may have attributes or elements on them you can access
too.  How a variable looks like, heavily depends on the application providing
those.

You can use a dot (\code{.}) to access attributes of a variable, alternative the
so-called ``subscript'' syntax (\code{{[}{]}}) can be used.  The following lines do
the same:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{foo}\PYG{n+nv}{.bar} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}
\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{foo}\PYG{o}{[}\PYG{l+s+s1}{'bar'}\PYG{o}{]} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}
\end{Verbatim}

It's important to know that the curly braces are \emph{not} part of the variable
but the print statement.  If you access variables inside tags don't put the
braces around.

If a variable or attribute does not exist you will get back an undefined
value.  What you can do with that kind of value depends on the application
configuration, the default behavior is that it evaluates to an empty string
if printed and that you can iterate over it, but every other operation fails.
\phantomsection\label{templates:notes-on-subscriptions}
\begin{notice}{note}{Implementation}

For convenience sake \code{foo.bar} in Jinja2 does the following things on
the Python layer:
\begin{itemize}
\item {} 
check if there is an attribute called \emph{bar} on \emph{foo}.

\item {} 
if there is not, check if there is an item \code{'bar'} in \emph{foo}.

\item {} 
if there is not, return an undefined object.

\end{itemize}

\code{foo{[}'bar'{]}} on the other hand works mostly the same with the a small
difference in the order:
\begin{itemize}
\item {} 
check if there is an item \code{'bar'} in \emph{foo}.

\item {} 
if there is not, check if there is an attribute called \emph{bar} on \emph{foo}.

\item {} 
if there is not, return an undefined object.

\end{itemize}

This is important if an object has an item or attribute with the same
name.  Additionally there is the {\hyperref[templates:attr]{\code{attr()}}} filter that just looks up
attributes.
\end{notice}


\section{Filters}
\label{templates:id2}\label{templates:filters}
Variables can by modified by \textbf{filters}.  Filters are separated from the
variable by a pipe symbol (\code{\textbar{}}) and may have optional arguments in
parentheses.  Multiple filters can be chained.  The output of one filter is
applied to the next.

\code{\{\{ name\textbar{}striptags\textbar{}title \}\}} for example will remove all HTML Tags from the
\emph{name} and title-cases it.  Filters that accept arguments have parentheses
around the arguments, like a function call.  This example will join a list
by commas:  \code{\{\{ list\textbar{}join(', ') \}\}}.

The {\hyperref[templates:builtin-filters]{\emph{List of Builtin Filters}}} below describes all the builtin filters.


\section{Tests}
\label{templates:tests}\label{templates:id3}
Beside filters there are also so called ``tests'' available.  Tests can be used
to test a variable against a common expression.  To test a variable or
expression you add \emph{is} plus the name of the test after the variable.  For
example to find out if a variable is defined you can do \code{name is defined}
which will then return true or false depending on if \emph{name} is defined.

Tests can accept arguments too.  If the test only takes one argument you can
leave out the parentheses to group them.  For example the following two
expressions do the same:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{if} \PYG{n+nb}{loop}\PYG{n+nv}{.index} \PYG{k}{is} \PYG{n+nf}{divisibleby} \PYG{l+m}{3} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{if} \PYG{n+nb}{loop}\PYG{n+nv}{.index} \PYG{k}{is} \PYG{n+nf}{divisibleby}\PYG{o}{(}\PYG{l+m}{3}\PYG{o}{)} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}

The {\hyperref[templates:builtin-tests]{\emph{List of Builtin Tests}}} below describes all the builtin tests.


\section{Comments}
\label{templates:comments}
To comment-out part of a line in a template, use the comment syntax which is
by default set to \code{\{\# ... \#\}}.  This is useful to comment out parts of the
template for debugging or to add information for other template designers or
yourself:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c}{\PYGZob{}\# note: disabled template because we no longer use this}
\PYG{c}{    \PYGZob{}\% for user in users \%\PYGZcb{}}
\PYG{c}{        ...}
\PYG{c}{    \PYGZob{}\% endfor \%\PYGZcb{}}
\PYG{c}{\#\PYGZcb{}}
\end{Verbatim}


\section{Whitespace Control}
\label{templates:whitespace-control}
In the default configuration whitespace is not further modified by the
template engine, so each whitespace (spaces, tabs, newlines etc.) is returned
unchanged.  If the application configures Jinja to \emph{trim\_blocks} the first
newline after a a template tag is removed automatically (like in PHP).

But you can also strip whitespace in templates by hand.  If you put an minus
sign (\code{-}) to the start or end of an block (for example a for tag), a
comment or variable expression you can remove the whitespaces after or before
that block:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{for} \PYG{n+nv}{item} \PYG{k}{in} \PYG{n+nv}{seq} -\PYG{c+cp}{\%\PYGZcb{}}
    \PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{item} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}
\PYG{c+cp}{\PYGZob{}\%}- \PYG{k}{endfor} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}

This will yield all elements without whitespace between them.  If \emph{seq} was
a list of numbers from \code{1} to \code{9} the output would be \code{123456789}.

If {\hyperref[templates:line-statements]{\emph{Line Statements}}} are enabled they strip leading whitespace
automatically up to the beginning of the line.

\begin{notice}{note}{Note}

You must not use a whitespace between the tag and the minus sign.

\textbf{valid}:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%}- \PYG{k}{if} \PYG{n+nv}{foo} -\PYG{c+cp}{\%\PYGZcb{}}...\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endif} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}

\textbf{invalid}:

\begin{Verbatim}[commandchars=\\\{\}]
\PYGZob{}\% - if foo - \%\PYGZcb{}...\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endif} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}
\end{notice}


\section{Escaping}
\label{templates:escaping}
It is sometimes desirable or even necessary to have Jinja ignore parts it
would otherwise handle as variables or blocks.  For example if the default
syntax is used and you want to use \code{\{\{} as raw string in the template and
not start a variable you have to use a trick.

The easiest way is to output the variable delimiter (\code{\{\{}) by using a
variable expression:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{l+s+s1}{'\PYGZob{}\PYGZob{}'} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}
\end{Verbatim}

For bigger sections it makes sense to mark a block \emph{raw}.  For example to
put Jinja syntax as example into a template you can use this snippet:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{raw} \PYG{c+cp}{\%\PYGZcb{}}
    \textless{}ul\textgreater{}
    \PYGZob{}\% for item in seq \%\PYGZcb{}
        \textless{}li\textgreater{}\PYGZob{}\PYGZob{} item \PYGZcb{}\PYGZcb{}\textless{}/li\textgreater{}
    \PYGZob{}\% endfor \%\PYGZcb{}
    \textless{}/ul\textgreater{}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endraw} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}


\section{Line Statements}
\label{templates:line-statements}\label{templates:id4}
If line statements are enabled by the application it's possible to mark a
line as a statement.  For example if the line statement prefix is configured
to \code{\#} the following two examples are equivalent:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nt}{\textless{}ul}\PYG{n+nt}{\textgreater{}}
\# for item in seq
    \PYG{n+nt}{\textless{}li}\PYG{n+nt}{\textgreater{}}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{item} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{n+nt}{\textless{}/li\textgreater{}}
\# endfor
\PYG{n+nt}{\textless{}/ul\textgreater{}}

\PYG{n+nt}{\textless{}ul}\PYG{n+nt}{\textgreater{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{for} \PYG{n+nv}{item} \PYG{k}{in} \PYG{n+nv}{seq} \PYG{c+cp}{\%\PYGZcb{}}
    \PYG{n+nt}{\textless{}li}\PYG{n+nt}{\textgreater{}}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{item} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{n+nt}{\textless{}/li\textgreater{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endfor} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{n+nt}{\textless{}/ul\textgreater{}}
\end{Verbatim}

The line statement prefix can appear anywhere on the line as long as no text
precedes it.  For better readability statements that start a block (such as
\emph{for}, \emph{if}, \emph{elif} etc.) may end with a colon:

\begin{Verbatim}[commandchars=\\\{\}]
\# for item in seq:
    ...
\# endfor
\end{Verbatim}

\begin{notice}{note}{Note}

Line statements can span multiple lines if there are open parentheses,
braces or brackets:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nt}{\textless{}ul}\PYG{n+nt}{\textgreater{}}
\# for href, caption in [('index.html', 'Index'),
                        ('about.html', 'About')]:
    \PYG{n+nt}{\textless{}li}\PYG{n+nt}{\textgreater{}}\PYG{n+nt}{\textless{}a} \PYG{n+na}{href=}\PYG{l+s}{"}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{href} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{l+s}{"}\PYG{n+nt}{\textgreater{}}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{caption} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{n+nt}{\textless{}/a\textgreater{}}\PYG{n+nt}{\textless{}/li\textgreater{}}
\# endfor
\PYG{n+nt}{\textless{}/ul\textgreater{}}
\end{Verbatim}
\end{notice}

Since Jinja 2.2 line-based comments are available as well.  For example if
the line-comment prefix is configured to be \code{\#\#} everything from \code{\#\#} to
the end of the line is ignored (excluding the newline sign):

\begin{Verbatim}[commandchars=\\\{\}]
\# for item in seq:
    \PYG{n+nt}{\textless{}li}\PYG{n+nt}{\textgreater{}}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{item} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{n+nt}{\textless{}/li\textgreater{}}     \#\# this comment is ignored
\# endfor
\end{Verbatim}


\section{Template Inheritance}
\label{templates:id5}\label{templates:template-inheritance}
The most powerful part of Jinja is template inheritance. Template inheritance
allows you to build a base ``skeleton'' template that contains all the common
elements of your site and defines \textbf{blocks} that child templates can override.

Sounds complicated but is very basic. It's easiest to understand it by starting
with an example.


\subsection{Base Template}
\label{templates:base-template}
This template, which we'll call \code{base.html}, defines a simple HTML skeleton
document that you might use for a simple two-column page. It's the job of
``child'' templates to fill the empty blocks with content:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\textless{}!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"\textgreater{}}
\PYG{n+nt}{\textless{}html} \PYG{n+na}{lang=}\PYG{l+s}{"en"}\PYG{n+nt}{\textgreater{}}
\PYG{n+nt}{\textless{}html} \PYG{n+na}{xmlns=}\PYG{l+s}{"http://www.w3.org/1999/xhtml"}\PYG{n+nt}{\textgreater{}}
\PYG{n+nt}{\textless{}head}\PYG{n+nt}{\textgreater{}}
    \PYG{c+cp}{\PYGZob{}\%} \PYG{k}{block} \PYG{n+nv}{head} \PYG{c+cp}{\%\PYGZcb{}}
    \PYG{n+nt}{\textless{}link} \PYG{n+na}{rel=}\PYG{l+s}{"stylesheet"} \PYG{n+na}{href=}\PYG{l+s}{"style.css"} \PYG{n+nt}{/\textgreater{}}
    \PYG{n+nt}{\textless{}title}\PYG{n+nt}{\textgreater{}}\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{block} \PYG{n+nv}{title} \PYG{c+cp}{\%\PYGZcb{}}\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endblock} \PYG{c+cp}{\%\PYGZcb{}} - My Webpage\PYG{n+nt}{\textless{}/title\textgreater{}}
    \PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endblock} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{n+nt}{\textless{}/head\textgreater{}}
\PYG{n+nt}{\textless{}body}\PYG{n+nt}{\textgreater{}}
    \PYG{n+nt}{\textless{}div} \PYG{n+na}{id=}\PYG{l+s}{"content"}\PYG{n+nt}{\textgreater{}}\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{block} \PYG{n+nv}{content} \PYG{c+cp}{\%\PYGZcb{}}\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endblock} \PYG{c+cp}{\%\PYGZcb{}}\PYG{n+nt}{\textless{}/div\textgreater{}}
    \PYG{n+nt}{\textless{}div} \PYG{n+na}{id=}\PYG{l+s}{"footer"}\PYG{n+nt}{\textgreater{}}
        \PYG{c+cp}{\PYGZob{}\%} \PYG{k}{block} \PYG{n+nv}{footer} \PYG{c+cp}{\%\PYGZcb{}}
        \PYG{n+ni}{\&copy;} Copyright 2008 by \PYG{n+nt}{\textless{}a} \PYG{n+na}{href=}\PYG{l+s}{"http://domain.invalid/"}\PYG{n+nt}{\textgreater{}}you\PYG{n+nt}{\textless{}/a\textgreater{}}.
        \PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endblock} \PYG{c+cp}{\%\PYGZcb{}}
    \PYG{n+nt}{\textless{}/div\textgreater{}}
\PYG{n+nt}{\textless{}/body\textgreater{}}
\end{Verbatim}

In this example, the \code{\{\% block \%\}} tags define four blocks that child templates
can fill in. All the \emph{block} tag does is to tell the template engine that a
child template may override those portions of the template.


\subsection{Child Template}
\label{templates:child-template}
A child template might look like this:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{extends} \PYG{l+s+s2}{"base.html"} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{block} \PYG{n+nv}{title} \PYG{c+cp}{\%\PYGZcb{}}Index\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endblock} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{block} \PYG{n+nv}{head} \PYG{c+cp}{\%\PYGZcb{}}
    \PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nb}{super}\PYG{o}{(}\PYG{o}{)} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}
    \PYG{n+nt}{\textless{}style }\PYG{n+na}{type=}\PYG{l+s}{"text/css"}\PYG{n+nt}{\textgreater{}}
        \PYG{n+nc}{.important} \PYG{p}{\PYGZob{}} \PYG{k}{color}\PYG{o}{:} \PYG{l+m}{\#336699}\PYG{p}{;} \PYG{p}{\PYGZcb{}}
    \PYG{n+nt}{\textless{}/style\textgreater{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endblock} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{block} \PYG{n+nv}{content} \PYG{c+cp}{\%\PYGZcb{}}
    \PYG{n+nt}{\textless{}h1}\PYG{n+nt}{\textgreater{}}Index\PYG{n+nt}{\textless{}/h1\textgreater{}}
    \PYG{n+nt}{\textless{}p} \PYG{n+na}{class=}\PYG{l+s}{"important"}\PYG{n+nt}{\textgreater{}}
      Welcome on my awesome homepage.
    \PYG{n+nt}{\textless{}/p\textgreater{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endblock} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}

The \code{\{\% extends \%\}} tag is the key here. It tells the template engine that
this template ``extends'' another template.  When the template system evaluates
this template, first it locates the parent.  The extends tag should be the
first tag in the template.  Everything before it is printed out normally and
may cause confusion.  For details about this behavior and how to take
advantage of it, see {\hyperref[tricks:null-master-fallback]{\emph{Null-Master Fallback}}}.

The filename of the template depends on the template loader.  For example the
\code{FileSystemLoader} allows you to access other templates by giving the
filename.  You can access templates in subdirectories with an slash:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{extends} \PYG{l+s+s2}{"layout/default.html"} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}

But this behavior can depend on the application embedding Jinja.  Note that
since the child template doesn't define the \code{footer} block, the value from
the parent template is used instead.

You can't define multiple \code{\{\% block \%\}} tags with the same name in the
same template.  This limitation exists because a block tag works in ``both''
directions.  That is, a block tag doesn't just provide a hole to fill - it
also defines the content that fills the hole in the \emph{parent}.  If there
were two similarly-named \code{\{\% block \%\}} tags in a template, that template's
parent wouldn't know which one of the blocks' content to use.

If you want to print a block multiple times you can however use the special
\emph{self} variable and call the block with that name:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nt}{\textless{}title}\PYG{n+nt}{\textgreater{}}\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{block} \PYG{n+nv}{title} \PYG{c+cp}{\%\PYGZcb{}}\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endblock} \PYG{c+cp}{\%\PYGZcb{}}\PYG{n+nt}{\textless{}/title\textgreater{}}
\PYG{n+nt}{\textless{}h1}\PYG{n+nt}{\textgreater{}}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{self}\PYG{n+nv}{.title}\PYG{o}{(}\PYG{o}{)} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{n+nt}{\textless{}/h1\textgreater{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{block} \PYG{n+nv}{body} \PYG{c+cp}{\%\PYGZcb{}}\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endblock} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}


\subsection{Super Blocks}
\label{templates:super-blocks}
It's possible to render the contents of the parent block by calling \emph{super}.
This gives back the results of the parent block:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{block} \PYG{n+nv}{sidebar} \PYG{c+cp}{\%\PYGZcb{}}
    \PYG{n+nt}{\textless{}h3}\PYG{n+nt}{\textgreater{}}Table Of Contents\PYG{n+nt}{\textless{}/h3\textgreater{}}
    ...
    \PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nb}{super}\PYG{o}{(}\PYG{o}{)} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endblock} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}


\subsection{Named Block End-Tags}
\label{templates:named-block-end-tags}
Jinja2 allows you to put the name of the block after the end tag for better
readability:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{block} \PYG{n+nv}{sidebar} \PYG{c+cp}{\%\PYGZcb{}}
    \PYG{c+cp}{\PYGZob{}\%} \PYG{k}{block} \PYG{n+nv}{inner\PYGZus{}sidebar} \PYG{c+cp}{\%\PYGZcb{}}
        ...
    \PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endblock} \PYG{n+nv}{inner\PYGZus{}sidebar} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endblock} \PYG{n+nv}{sidebar} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}

However the name after the \emph{endblock} word must match the block name.


\subsection{Block Nesting and Scope}
\label{templates:block-nesting-and-scope}
Blocks can be nested for more complex layouts.  However per default blocks
may not access variables from outer scopes:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{for} \PYG{n+nv}{item} \PYG{k}{in} \PYG{n+nv}{seq} \PYG{c+cp}{\%\PYGZcb{}}
    \PYG{n+nt}{\textless{}li}\PYG{n+nt}{\textgreater{}}\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{block} \PYG{n+nv}{loop\PYGZus{}item} \PYG{c+cp}{\%\PYGZcb{}}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{item} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endblock} \PYG{c+cp}{\%\PYGZcb{}}\PYG{n+nt}{\textless{}/li\textgreater{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endfor} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}

This example would output empty \code{\textless{}li\textgreater{}} items because \emph{item} is unavailable
inside the block.  The reason for this is that if the block is replaced by
a child template a variable would appear that was not defined in the block or
passed to the context.

Starting with Jinja 2.2 you can explicitly specify that variables are
available in a block by setting the block to ``scoped'' by adding the \emph{scoped}
modifier to a block declaration:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{for} \PYG{n+nv}{item} \PYG{k}{in} \PYG{n+nv}{seq} \PYG{c+cp}{\%\PYGZcb{}}
    \PYG{n+nt}{\textless{}li}\PYG{n+nt}{\textgreater{}}\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{block} \PYG{n+nv}{loop\PYGZus{}item} \PYG{k}{scoped} \PYG{c+cp}{\%\PYGZcb{}}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{item} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endblock} \PYG{c+cp}{\%\PYGZcb{}}\PYG{n+nt}{\textless{}/li\textgreater{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endfor} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}

When overriding a block the \emph{scoped} modifier does not have to be provided.


\subsection{Template Objects}
\label{templates:template-objects}Changed in version 2.4.
If a template object was passed to the template context you can
extend from that object as well.  Assuming the calling code passes
a layout template as \emph{layout\_template} to the environment, this
code works:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{extends} \PYG{n+nv}{layout\PYGZus{}template} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}

Previously the \emph{layout\_template} variable had to be a string with
the layout template's filename for this to work.


\section{HTML Escaping}
\label{templates:html-escaping}
When generating HTML from templates, there's always a risk that a variable will
include characters that affect the resulting HTML.  There are two approaches:
manually escaping each variable or automatically escaping everything by default.

Jinja supports both, but what is used depends on the application configuration.
The default configuaration is no automatic escaping for various reasons:
\begin{itemize}
\item {} 
escaping everything except of safe values will also mean that Jinja is
escaping variables known to not include HTML such as numbers which is
a huge performance hit.

\item {} 
The information about the safety of a variable is very fragile.  It could
happen that by coercing safe and unsafe values the return value is double
escaped HTML.

\end{itemize}


\subsection{Working with Manual Escaping}
\label{templates:working-with-manual-escaping}
If manual escaping is enabled it's \textbf{your} responsibility to escape
variables if needed.  What to escape?  If you have a variable that \emph{may}
include any of the following chars (\code{\textgreater{}}, \code{\textless{}}, \code{\&}, or \code{"}) you
\textbf{have to} escape it unless the variable contains well-formed and trusted
HTML.  Escaping works by piping the variable through the \code{\textbar{}e} filter:
\code{\{\{ user.username\textbar{}e \}\}}.


\subsection{Working with Automatic Escaping}
\label{templates:working-with-automatic-escaping}
When automatic escaping is enabled everything is escaped by default except
for values explicitly marked as safe.  Those can either be marked by the
application or in the template by using the \emph{\textbar{}safe} filter.  The main
problem with this approach is that Python itself doesn't have the concept
of tainted values so the information if a value is safe or unsafe can get
lost.  If the information is lost escaping will take place which means that
you could end up with double escaped contents.

Double escaping is easy to avoid however, just rely on the tools Jinja2
provides and don't use builtin Python constructs such as the string modulo
operator.

Functions returning template data (macros, \emph{super}, \emph{self.BLOCKNAME}) return
safe markup always.

String literals in templates with automatic escaping are considered unsafe
too.  The reason for this is that the safe string is an extension to Python
and not every library will work properly with it.


\section{List of Control Structures}
\label{templates:list-of-control-structures}
A control structure refers to all those things that control the flow of a
program - conditionals (i.e. if/elif/else), for-loops, as well as things like
macros and blocks.  Control structures appear inside \code{\{\% ... \%\}} blocks
in the default syntax.


\subsection{For}
\label{templates:for}
Loop over each item in a sequence.  For example, to display a list of users
provided in a variable called \emph{users}:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nt}{\textless{}h1}\PYG{n+nt}{\textgreater{}}Members\PYG{n+nt}{\textless{}/h1\textgreater{}}
\PYG{n+nt}{\textless{}ul}\PYG{n+nt}{\textgreater{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{for} \PYG{n+nv}{user} \PYG{k}{in} \PYG{n+nv}{users} \PYG{c+cp}{\%\PYGZcb{}}
  \PYG{n+nt}{\textless{}li}\PYG{n+nt}{\textgreater{}}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{user}\PYG{n+nv}{.username}\PYG{o}{\textbar{}}\PYG{n+nf}{e} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{n+nt}{\textless{}/li\textgreater{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endfor} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{n+nt}{\textless{}/ul\textgreater{}}
\end{Verbatim}

Inside of a for loop block you can access some special variables:

\begin{tabulary}{\linewidth}{|L|L|}
\hline
\textbf{
Variable
} & \textbf{
Description
}\\
\hline

\emph{loop.index}
 & 
The current iteration of the loop. (1 indexed)
\\

\emph{loop.index0}
 & 
The current iteration of the loop. (0 indexed)
\\

\emph{loop.revindex}
 & 
The number of iterations from the end of the loop
(1 indexed)
\\

\emph{loop.revindex0}
 & 
The number of iterations from the end of the loop
(0 indexed)
\\

\emph{loop.first}
 & 
True if first iteration.
\\

\emph{loop.last}
 & 
True if last iteration.
\\

\emph{loop.length}
 & 
The number of items in the sequence.
\\

\emph{loop.cycle}
 & 
A helper function to cycle between a list of
sequences.  See the explanation below.
\\
\hline
\end{tabulary}


Within a for-loop, it's possible to cycle among a list of strings/variables
each time through the loop by using the special \emph{loop.cycle} helper:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{for} \PYG{n+nv}{row} \PYG{k}{in} \PYG{n+nv}{rows} \PYG{c+cp}{\%\PYGZcb{}}
    \PYG{n+nt}{\textless{}li} \PYG{n+na}{class=}\PYG{l+s}{"}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nb}{loop}\PYG{n+nv}{.cycle}\PYG{o}{(}\PYG{l+s+s1}{'odd'}\PYG{o}{,} \PYG{l+s+s1}{'even'}\PYG{o}{)} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{l+s}{"}\PYG{n+nt}{\textgreater{}}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{row} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{n+nt}{\textless{}/li\textgreater{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endfor} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}

With Jinja 2.1 an extra \emph{cycle} helper exists that allows loop-unbound
cycling.  For more information have a look at the {\hyperref[templates:builtin-globals]{\emph{List of Global Functions}}}.
\phantomsection\label{templates:loop-filtering}
Unlike in Python it's not possible to \emph{break} or \emph{continue} in a loop.  You
can however filter the sequence during iteration which allows you to skip
items.  The following example skips all the users which are hidden:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{for} \PYG{n+nv}{user} \PYG{k}{in} \PYG{n+nv}{users} \PYG{k}{if} \PYG{k}{not} \PYG{n+nv}{user}\PYG{n+nv}{.hidden} \PYG{c+cp}{\%\PYGZcb{}}
    \PYG{n+nt}{\textless{}li}\PYG{n+nt}{\textgreater{}}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{user}\PYG{n+nv}{.username}\PYG{o}{\textbar{}}\PYG{n+nf}{e} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{n+nt}{\textless{}/li\textgreater{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endfor} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}

The advantage is that the special \emph{loop} variable will count correctly thus
not counting the users not iterated over.

If no iteration took place because the sequence was empty or the filtering
removed all the items from the sequence you can render a replacement block
by using \emph{else}:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nt}{\textless{}ul}\PYG{n+nt}{\textgreater{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{for} \PYG{n+nv}{user} \PYG{k}{in} \PYG{n+nv}{users} \PYG{c+cp}{\%\PYGZcb{}}
    \PYG{n+nt}{\textless{}li}\PYG{n+nt}{\textgreater{}}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{user}\PYG{n+nv}{.username}\PYG{o}{\textbar{}}\PYG{n+nf}{e} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{n+nt}{\textless{}/li\textgreater{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{else} \PYG{c+cp}{\%\PYGZcb{}}
    \PYG{n+nt}{\textless{}li}\PYG{n+nt}{\textgreater{}}\PYG{n+nt}{\textless{}em}\PYG{n+nt}{\textgreater{}}no users found\PYG{n+nt}{\textless{}/em\textgreater{}}\PYG{n+nt}{\textless{}/li\textgreater{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endfor} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{n+nt}{\textless{}/ul\textgreater{}}
\end{Verbatim}

It is also possible to use loops recursively.  This is useful if you are
dealing with recursive data such as sitemaps.  To use loops recursively you
basically have to add the \emph{recursive} modifier to the loop definition and
call the \emph{loop} variable with the new iterable where you want to recurse.

The following example implements a sitemap with recursive loops:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nt}{\textless{}ul} \PYG{n+na}{class=}\PYG{l+s}{"sitemap"}\PYG{n+nt}{\textgreater{}}
\PYG{c+cp}{\PYGZob{}\%}- \PYG{k}{for} \PYG{n+nv}{item} \PYG{k}{in} \PYG{n+nv}{sitemap} \PYG{k}{recursive} \PYG{c+cp}{\%\PYGZcb{}}
    \PYG{n+nt}{\textless{}li}\PYG{n+nt}{\textgreater{}}\PYG{n+nt}{\textless{}a} \PYG{n+na}{href=}\PYG{l+s}{"}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{item}\PYG{n+nv}{.href}\PYG{o}{\textbar{}}\PYG{n+nf}{e} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{l+s}{"}\PYG{n+nt}{\textgreater{}}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{item}\PYG{n+nv}{.title} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{n+nt}{\textless{}/a\textgreater{}}
    \PYG{c+cp}{\PYGZob{}\%}- \PYG{k}{if} \PYG{n+nv}{item}\PYG{n+nv}{.children} -\PYG{c+cp}{\%\PYGZcb{}}
        \PYG{n+nt}{\textless{}ul} \PYG{n+na}{class=}\PYG{l+s}{"submenu"}\PYG{n+nt}{\textgreater{}}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nb}{loop}\PYG{o}{(}\PYG{n+nv}{item}\PYG{n+nv}{.children}\PYG{o}{)} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{n+nt}{\textless{}/ul\textgreater{}}
    \PYG{c+cp}{\PYGZob{}\%}- \PYG{k}{endif} \PYG{c+cp}{\%\PYGZcb{}}\PYG{n+nt}{\textless{}/li\textgreater{}}
\PYG{c+cp}{\PYGZob{}\%}- \PYG{k}{endfor} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{n+nt}{\textless{}/ul\textgreater{}}
\end{Verbatim}


\subsection{If}
\label{templates:if}
The \emph{if} statement in Jinja is comparable with the if statements of Python.
In the simplest form you can use it to test if a variable is defined, not
empty or not false:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{if} \PYG{n+nv}{users} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{n+nt}{\textless{}ul}\PYG{n+nt}{\textgreater{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{for} \PYG{n+nv}{user} \PYG{k}{in} \PYG{n+nv}{users} \PYG{c+cp}{\%\PYGZcb{}}
    \PYG{n+nt}{\textless{}li}\PYG{n+nt}{\textgreater{}}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{user}\PYG{n+nv}{.username}\PYG{o}{\textbar{}}\PYG{n+nf}{e} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{n+nt}{\textless{}/li\textgreater{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endfor} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{n+nt}{\textless{}/ul\textgreater{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endif} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}

For multiple branches \emph{elif} and \emph{else} can be used like in Python.  You can
use more complex {\hyperref[templates:expressions]{\emph{Expressions}}} there too:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{if} \PYG{n+nv}{kenny}\PYG{n+nv}{.sick} \PYG{c+cp}{\%\PYGZcb{}}
    Kenny is sick.
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{elif} \PYG{n+nv}{kenny}\PYG{n+nv}{.dead} \PYG{c+cp}{\%\PYGZcb{}}
    You killed Kenny!  You bastard!!!
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{else} \PYG{c+cp}{\%\PYGZcb{}}
    Kenny looks okay --- so far
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endif} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}

If can also be used as {\hyperref[templates:if-expression]{\emph{inline expression}}} and for
{\hyperref[templates:loop-filtering]{\emph{loop filtering}}}.


\subsection{Macros}
\label{templates:macros}
Macros are comparable with functions in regular programming languages.  They
are useful to put often used idioms into reusable functions to not repeat
yourself.

Here a small example of a macro that renders a form element:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{macro} \PYG{n+nv}{input}\PYG{o}{(}\PYG{n+nv}{name}\PYG{o}{,} \PYG{n+nv}{value}\PYG{o}{=}\PYG{l+s+s1}{''}\PYG{o}{,} \PYG{n+nv}{type}\PYG{o}{=}\PYG{l+s+s1}{'text'}\PYG{o}{,} \PYG{n+nv}{size}\PYG{o}{=}\PYG{l+m}{2}\PYG{l+m}{0}\PYG{o}{)} -\PYG{c+cp}{\%\PYGZcb{}}
    \PYG{n+nt}{\textless{}input} \PYG{n+na}{type=}\PYG{l+s}{"}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{type} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{l+s}{"} \PYG{n+na}{name=}\PYG{l+s}{"}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{name} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{l+s}{"} \PYG{n+na}{value=}\PYG{l+s}{"}\PYG{c+cp}{\PYGZob{}\PYGZob{}}
        \PYG{n+nv}{value}\PYG{o}{\textbar{}}\PYG{n+nf}{e} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{l+s}{"} \PYG{n+na}{size=}\PYG{l+s}{"}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{size} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{l+s}{"}\PYG{n+nt}{\textgreater{}}
\PYG{c+cp}{\PYGZob{}\%}- \PYG{k}{endmacro} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}

The macro can then be called like a function in the namespace:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nt}{\textless{}p}\PYG{n+nt}{\textgreater{}}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{input}\PYG{o}{(}\PYG{l+s+s1}{'username'}\PYG{o}{)} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{n+nt}{\textless{}/p\textgreater{}}
\PYG{n+nt}{\textless{}p}\PYG{n+nt}{\textgreater{}}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{input}\PYG{o}{(}\PYG{l+s+s1}{'password'}\PYG{o}{,} \PYG{n+nv}{type}\PYG{o}{=}\PYG{l+s+s1}{'password'}\PYG{o}{)} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{n+nt}{\textless{}/p\textgreater{}}
\end{Verbatim}

If the macro was defined in a different template you have to
{\hyperref[templates:import]{\emph{import}}} it first.

Inside macros you have access to three special variables:
\begin{description}
\item[{\emph{varargs}}] \leavevmode
If more positional arguments are passed to the macro than accepted by the
macro they end up in the special \emph{varargs} variable as list of values.

\item[{\emph{kwargs}}] \leavevmode
Like \emph{varargs} but for keyword arguments.  All unconsumed keyword
arguments are stored in this special variable.

\item[{\emph{caller}}] \leavevmode
If the macro was called from a {\hyperref[templates:call]{\emph{call}}} tag the caller is stored
in this variable as macro which can be called.

\end{description}

Macros also expose some of their internal details.  The following attributes
are available on a macro object:
\begin{description}
\item[{\emph{name}}] \leavevmode
The name of the macro.  \code{\{\{ input.name \}\}} will print \code{input}.

\item[{\emph{arguments}}] \leavevmode
A tuple of the names of arguments the macro accepts.

\item[{\emph{defaults}}] \leavevmode
A tuple of default values.

\item[{\emph{catch\_kwargs}}] \leavevmode
This is \emph{true} if the macro accepts extra keyword arguments (ie: accesses
the special \emph{kwargs} variable).

\item[{\emph{catch\_varargs}}] \leavevmode
This is \emph{true} if the macro accepts extra positional arguments (ie:
accesses the special \emph{varargs} variable).

\item[{\emph{caller}}] \leavevmode
This is \emph{true} if the macro accesses the special \emph{caller} variable and may
be called from a {\hyperref[templates:call]{\emph{call}}} tag.

\end{description}

If a macro name starts with an underscore it's not exported and can't
be imported.


\subsection{Call}
\label{templates:id6}\label{templates:call}
In some cases it can be useful to pass a macro to another macro.  For this
purpose you can use the special \emph{call} block.  The following example shows
a macro that takes advantage of the call functionality and how it can be
used:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{macro} \PYG{n+nv}{render\PYGZus{}dialog}\PYG{o}{(}\PYG{n+nv}{title}\PYG{o}{,} \PYG{n+nv}{class}\PYG{o}{=}\PYG{l+s+s1}{'dialog'}\PYG{o}{)} -\PYG{c+cp}{\%\PYGZcb{}}
    \PYG{n+nt}{\textless{}div} \PYG{n+na}{class=}\PYG{l+s}{"}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{class} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{l+s}{"}\PYG{n+nt}{\textgreater{}}
        \PYG{n+nt}{\textless{}h2}\PYG{n+nt}{\textgreater{}}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{title} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{n+nt}{\textless{}/h2\textgreater{}}
        \PYG{n+nt}{\textless{}div} \PYG{n+na}{class=}\PYG{l+s}{"contents"}\PYG{n+nt}{\textgreater{}}
            \PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{caller}\PYG{o}{(}\PYG{o}{)} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}
        \PYG{n+nt}{\textless{}/div\textgreater{}}
    \PYG{n+nt}{\textless{}/div\textgreater{}}
\PYG{c+cp}{\PYGZob{}\%}- \PYG{k}{endmacro} \PYG{c+cp}{\%\PYGZcb{}}

\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{call} \PYG{n+nv}{render\PYGZus{}dialog}\PYG{o}{(}\PYG{l+s+s1}{'Hello World'}\PYG{o}{)} \PYG{c+cp}{\%\PYGZcb{}}
    This is a simple dialog rendered by using a macro and
    a call block.
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endcall} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}

It's also possible to pass arguments back to the call block.  This makes it
useful as replacement for loops.  Generally speaking a call block works
exactly like an macro, just that it doesn't have a name.

Here an example of how a call block can be used with arguments:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{macro} \PYG{n+nv}{dump\PYGZus{}users}\PYG{o}{(}\PYG{n+nv}{users}\PYG{o}{)} -\PYG{c+cp}{\%\PYGZcb{}}
    \PYG{n+nt}{\textless{}ul}\PYG{n+nt}{\textgreater{}}
    \PYG{c+cp}{\PYGZob{}\%}- \PYG{k}{for} \PYG{n+nv}{user} \PYG{k}{in} \PYG{n+nv}{users} \PYG{c+cp}{\%\PYGZcb{}}
        \PYG{n+nt}{\textless{}li}\PYG{n+nt}{\textgreater{}}\PYG{n+nt}{\textless{}p}\PYG{n+nt}{\textgreater{}}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{user}\PYG{n+nv}{.username}\PYG{o}{\textbar{}}\PYG{n+nf}{e} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{n+nt}{\textless{}/p\textgreater{}}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{caller}\PYG{o}{(}\PYG{n+nv}{user}\PYG{o}{)} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{n+nt}{\textless{}/li\textgreater{}}
    \PYG{c+cp}{\PYGZob{}\%}- \PYG{k}{endfor} \PYG{c+cp}{\%\PYGZcb{}}
    \PYG{n+nt}{\textless{}/ul\textgreater{}}
\PYG{c+cp}{\PYGZob{}\%}- \PYG{k}{endmacro} \PYG{c+cp}{\%\PYGZcb{}}

\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{call}\PYG{o}{(}\PYG{n+nv}{user}\PYG{o}{)} \PYG{n+nv}{dump\PYGZus{}users}\PYG{o}{(}\PYG{n+nv}{list\PYGZus{}of\PYGZus{}user}\PYG{o}{)} \PYG{c+cp}{\%\PYGZcb{}}
    \PYG{n+nt}{\textless{}dl}\PYG{n+nt}{\textgreater{}}
        \PYG{n+nt}{\textless{}dl}\PYG{n+nt}{\textgreater{}}Realname\PYG{n+nt}{\textless{}/dl\textgreater{}}
        \PYG{n+nt}{\textless{}dd}\PYG{n+nt}{\textgreater{}}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{user}\PYG{n+nv}{.realname}\PYG{o}{\textbar{}}\PYG{n+nf}{e} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{n+nt}{\textless{}/dd\textgreater{}}
        \PYG{n+nt}{\textless{}dl}\PYG{n+nt}{\textgreater{}}Description\PYG{n+nt}{\textless{}/dl\textgreater{}}
        \PYG{n+nt}{\textless{}dd}\PYG{n+nt}{\textgreater{}}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{user}\PYG{n+nv}{.description} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{n+nt}{\textless{}/dd\textgreater{}}
    \PYG{n+nt}{\textless{}/dl\textgreater{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endcall} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}


\subsection{Filters}
\label{templates:id7}
Filter sections allow you to apply regular Jinja2 filters on a block of
template data.  Just wrap the code in the special \emph{filter} section:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{filter} \PYG{n+nf}{upper} \PYG{c+cp}{\%\PYGZcb{}}
    This text becomes uppercase
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endfilter} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}


\subsection{Assignments}
\label{templates:assignments}
Inside code blocks you can also assign values to variables.  Assignments at
top level (outside of blocks, macros or loops) are exported from the template
like top level macros and can be imported by other templates.

Assignments use the \emph{set} tag and can have multiple targets:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{set} \PYG{n+nv}{navigation} \PYG{o}{=} \PYG{o}{[}\PYG{o}{(}\PYG{l+s+s1}{'index.html'}\PYG{o}{,} \PYG{l+s+s1}{'Index'}\PYG{o}{)}\PYG{o}{,} \PYG{o}{(}\PYG{l+s+s1}{'about.html'}\PYG{o}{,} \PYG{l+s+s1}{'About'}\PYG{o}{)}\PYG{o}{]} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{set} \PYG{n+nv}{key}\PYG{o}{,} \PYG{n+nv}{value} \PYG{o}{=} \PYG{n+nv}{call\PYGZus{}something}\PYG{o}{(}\PYG{o}{)} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}


\subsection{Extends}
\label{templates:extends}
The \emph{extends} tag can be used to extend a template from another one.  You
can have multiple of them in a file but only one of them may be executed
at the time.  See the section about {\hyperref[templates:template-inheritance]{\emph{Template Inheritance}}} above.


\subsection{Block}
\label{templates:block}
Blocks are used for inheritance and act as placeholders and replacements
at the same time.  They are documented in detail as part of the section
about {\hyperref[templates:template-inheritance]{\emph{Template Inheritance}}}.


\subsection{Include}
\label{templates:include}
The \emph{include} statement is useful to include a template and return the
rendered contents of that file into the current namespace:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{include} \PYG{l+s+s1}{'header.html'} \PYG{c+cp}{\%\PYGZcb{}}
    Body
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{include} \PYG{l+s+s1}{'footer.html'} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}

Included templates have access to the variables of the active context by
default.  For more details about context behavior of imports and includes
see {\hyperref[templates:import-visibility]{\emph{Import Context Behavior}}}.

From Jinja 2.2 onwards you can mark an include with \code{ignore missing} in
which case Jinja will ignore the statement if the template to be ignored
does not exist.  When combined with \code{with} or \code{without context} it has
to be placed \emph{before} the context visibility statement.  Here some valid
examples:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{include} \PYG{l+s+s2}{"sidebar.html"} \PYG{k}{ignore missing} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{include} \PYG{l+s+s2}{"sidebar.html"} \PYG{k}{ignore missing} \PYG{k}{with context} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{include} \PYG{l+s+s2}{"sidebar.html"} \PYG{k}{ignore missing} \PYG{k}{without context} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}
New in version 2.2.
You can also provide a list of templates that are checked for existence
before inclusion.  The first template that exists will be included.  If
\emph{ignore missing} is given, it will fall back to rendering nothing if
none of the templates exist, otherwise it will raise an exception.

Example:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{include} \PYG{o}{[}\PYG{l+s+s1}{'page\PYGZus{}detailed.html'}\PYG{o}{,} \PYG{l+s+s1}{'page.html'}\PYG{o}{]} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{include} \PYG{o}{[}\PYG{l+s+s1}{'special\PYGZus{}sidebar.html'}\PYG{o}{,} \PYG{l+s+s1}{'sidebar.html'}\PYG{o}{]} \PYG{k}{ignore missing} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}
Changed in version 2.4: If a template object was passed to the template context you can
include that object using \emph{include}.

\subsection{Import}
\label{templates:import}\label{templates:id8}
Jinja2 supports putting often used code into macros.  These macros can go into
different templates and get imported from there.  This works similar to the
import statements in Python.  It's important to know that imports are cached
and imported templates don't have access to the current template variables,
just the globals by defualt.  For more details about context behavior of
imports and includes see {\hyperref[templates:import-visibility]{\emph{Import Context Behavior}}}.

There are two ways to import templates.  You can import the complete template
into a variable or request specific macros / exported variables from it.

Imagine we have a helper module that renders forms (called \emph{forms.html}):

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{macro} \PYG{n+nv}{input}\PYG{o}{(}\PYG{n+nv}{name}\PYG{o}{,} \PYG{n+nv}{value}\PYG{o}{=}\PYG{l+s+s1}{''}\PYG{o}{,} \PYG{n+nv}{type}\PYG{o}{=}\PYG{l+s+s1}{'text'}\PYG{o}{)} -\PYG{c+cp}{\%\PYGZcb{}}
    \PYG{n+nt}{\textless{}input} \PYG{n+na}{type=}\PYG{l+s}{"}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{type} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{l+s}{"} \PYG{n+na}{value=}\PYG{l+s}{"}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{value}\PYG{o}{\textbar{}}\PYG{n+nf}{e} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{l+s}{"} \PYG{n+na}{name=}\PYG{l+s}{"}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{name} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{l+s}{"}\PYG{n+nt}{\textgreater{}}
\PYG{c+cp}{\PYGZob{}\%}- \PYG{k}{endmacro} \PYG{c+cp}{\%\PYGZcb{}}

\PYG{c+cp}{\PYGZob{}\%}- \PYG{k}{macro} \PYG{n+nv}{textarea}\PYG{o}{(}\PYG{n+nv}{name}\PYG{o}{,} \PYG{n+nv}{value}\PYG{o}{=}\PYG{l+s+s1}{''}\PYG{o}{,} \PYG{n+nv}{rows}\PYG{o}{=}\PYG{l+m}{1}\PYG{l+m}{0}\PYG{o}{,} \PYG{n+nv}{cols}\PYG{o}{=}\PYG{l+m}{4}\PYG{l+m}{0}\PYG{o}{)} -\PYG{c+cp}{\%\PYGZcb{}}
    \PYG{n+nt}{\textless{}textarea} \PYG{n+na}{name=}\PYG{l+s}{"}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{name} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{l+s}{"} \PYG{n+na}{rows=}\PYG{l+s}{"}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{rows} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{l+s}{"} \PYG{n+na}{cols=}\PYG{l+s}{"}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{cols}
        \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{l+s}{"}\PYG{n+nt}{\textgreater{}}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{value}\PYG{o}{\textbar{}}\PYG{n+nf}{e} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{n+nt}{\textless{}/textarea\textgreater{}}
\PYG{c+cp}{\PYGZob{}\%}- \PYG{k}{endmacro} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}

The easiest and most flexible is importing the whole module into a variable.
That way you can access the attributes:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{import} \PYG{l+s+s1}{'forms.html'} \PYG{k}{as} \PYG{n+nv}{forms} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{n+nt}{\textless{}dl}\PYG{n+nt}{\textgreater{}}
    \PYG{n+nt}{\textless{}dt}\PYG{n+nt}{\textgreater{}}Username\PYG{n+nt}{\textless{}/dt\textgreater{}}
    \PYG{n+nt}{\textless{}dd}\PYG{n+nt}{\textgreater{}}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{forms}\PYG{n+nv}{.input}\PYG{o}{(}\PYG{l+s+s1}{'username'}\PYG{o}{)} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{n+nt}{\textless{}/dd\textgreater{}}
    \PYG{n+nt}{\textless{}dt}\PYG{n+nt}{\textgreater{}}Password\PYG{n+nt}{\textless{}/dt\textgreater{}}
    \PYG{n+nt}{\textless{}dd}\PYG{n+nt}{\textgreater{}}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{forms}\PYG{n+nv}{.input}\PYG{o}{(}\PYG{l+s+s1}{'password'}\PYG{o}{,} \PYG{n+nv}{type}\PYG{o}{=}\PYG{l+s+s1}{'password'}\PYG{o}{)} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{n+nt}{\textless{}/dd\textgreater{}}
\PYG{n+nt}{\textless{}/dl\textgreater{}}
\PYG{n+nt}{\textless{}p}\PYG{n+nt}{\textgreater{}}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{forms}\PYG{n+nv}{.textarea}\PYG{o}{(}\PYG{l+s+s1}{'comment'}\PYG{o}{)} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{n+nt}{\textless{}/p\textgreater{}}
\end{Verbatim}

Alternatively you can import names from the template into the current
namespace:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{from} \PYG{l+s+s1}{'forms.html'} \PYG{k}{import} \PYG{n+nv}{input} \PYG{k}{as} \PYG{n+nv}{input\PYGZus{}field}\PYG{o}{,} \PYG{n+nv}{textarea} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{n+nt}{\textless{}dl}\PYG{n+nt}{\textgreater{}}
    \PYG{n+nt}{\textless{}dt}\PYG{n+nt}{\textgreater{}}Username\PYG{n+nt}{\textless{}/dt\textgreater{}}
    \PYG{n+nt}{\textless{}dd}\PYG{n+nt}{\textgreater{}}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{input\PYGZus{}field}\PYG{o}{(}\PYG{l+s+s1}{'username'}\PYG{o}{)} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{n+nt}{\textless{}/dd\textgreater{}}
    \PYG{n+nt}{\textless{}dt}\PYG{n+nt}{\textgreater{}}Password\PYG{n+nt}{\textless{}/dt\textgreater{}}
    \PYG{n+nt}{\textless{}dd}\PYG{n+nt}{\textgreater{}}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{input\PYGZus{}field}\PYG{o}{(}\PYG{l+s+s1}{'password'}\PYG{o}{,} \PYG{n+nv}{type}\PYG{o}{=}\PYG{l+s+s1}{'password'}\PYG{o}{)} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{n+nt}{\textless{}/dd\textgreater{}}
\PYG{n+nt}{\textless{}/dl\textgreater{}}
\PYG{n+nt}{\textless{}p}\PYG{n+nt}{\textgreater{}}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{textarea}\PYG{o}{(}\PYG{l+s+s1}{'comment'}\PYG{o}{)} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{n+nt}{\textless{}/p\textgreater{}}
\end{Verbatim}

Macros and variables starting with one ore more underscores are private and
cannot be imported.
Changed in version 2.4: If a template object was passed to the template context you can
import from that object.

\section{Import Context Behavior}
\label{templates:import-context-behavior}\label{templates:import-visibility}
Per default included templates are passed the current context and imported
templates not.  The reason for this is that imports unlike includes are
cached as imports are often used just as a module that holds macros.

This however can be changed of course explicitly.  By adding \emph{with context}
or \emph{without context} to the import/include directive the current context
can be passed to the template and caching is disabled automatically.

Here two examples:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{from} \PYG{l+s+s1}{'forms.html'} \PYG{k}{import} \PYG{n+nv}{input} \PYG{k}{with context} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{include} \PYG{l+s+s1}{'header.html'} \PYG{k}{without context} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}

\begin{notice}{note}{Note}

In Jinja 2.0 the context that was passed to the included template
did not include variables defined in the template.  As a matter of
fact this did not work:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{for} \PYG{n+nv}{box} \PYG{k}{in} \PYG{n+nv}{boxes} \PYG{c+cp}{\%\PYGZcb{}}
    \PYG{c+cp}{\PYGZob{}\%} \PYG{k}{include} \PYG{l+s+s2}{"render\PYGZus{}box.html"} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endfor} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}

The included template \code{render\_box.html} is not able to access
\emph{box} in Jinja 2.0, but in Jinja 2.1.
\end{notice}


\section{Expressions}
\label{templates:expressions}\label{templates:id9}
Jinja allows basic expressions everywhere.  These work very similar to regular
Python and even if you're not working with Python you should feel comfortable
with it.


\subsection{Literals}
\label{templates:literals}
The simplest form of expressions are literals.  Literals are representations
for Python objects such as strings and numbers.  The following literals exist:
\begin{description}
\item[{``Hello World'':}] \leavevmode
Everything between two double or single quotes is a string.  They are
useful whenever you need a string in the template (for example as
arguments to function calls, filters or just to extend or include a
template).

\item[{42 / 42.23:}] \leavevmode
Integers and floating point numbers are created by just writing the
number down.  If a dot is present the number is a float, otherwise an
integer.  Keep in mind that for Python \code{42} and \code{42.0} is something
different.

\item[{{[}'list', `of', `objects'{]}:}] \leavevmode
Everything between two brackets is a list.  Lists are useful to store
sequential data in or to iterate over them.  For example you can easily
create a list of links using lists and tuples with a for loop:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nt}{\textless{}ul}\PYG{n+nt}{\textgreater{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{for} \PYG{n+nv}{href}\PYG{o}{,} \PYG{n+nv}{caption} \PYG{k}{in} \PYG{o}{[}\PYG{o}{(}\PYG{l+s+s1}{'index.html'}\PYG{o}{,} \PYG{l+s+s1}{'Index'}\PYG{o}{)}\PYG{o}{,} \PYG{o}{(}\PYG{l+s+s1}{'about.html'}\PYG{o}{,} \PYG{l+s+s1}{'About'}\PYG{o}{)}\PYG{o}{,}
                         \PYG{o}{(}\PYG{l+s+s1}{'downloads.html'}\PYG{o}{,} \PYG{l+s+s1}{'Downloads'}\PYG{o}{)}\PYG{o}{]} \PYG{c+cp}{\%\PYGZcb{}}
    \PYG{n+nt}{\textless{}li}\PYG{n+nt}{\textgreater{}}\PYG{n+nt}{\textless{}a} \PYG{n+na}{href=}\PYG{l+s}{"}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{href} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{l+s}{"}\PYG{n+nt}{\textgreater{}}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{caption} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{n+nt}{\textless{}/a\textgreater{}}\PYG{n+nt}{\textless{}/li\textgreater{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endfor} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{n+nt}{\textless{}/ul\textgreater{}}
\end{Verbatim}

\item[{(`tuple', `of', `values'):}] \leavevmode
Tuples are like lists, just that you can't modify them.  If the tuple
only has one item you have to end it with a comma.  Tuples are usually
used to represent items of two or more elements.  See the example above
for more details.

\item[{\{`dict': `of', `key': `and', `value': `pairs'\}:}] \leavevmode
A dict in Python is a structure that combines keys and values.  Keys must
be unique and always have exactly one value.  Dicts are rarely used in
templates, they are useful in some rare cases such as the {\hyperref[templates:xmlattr]{\code{xmlattr()}}}
filter.

\item[{true / false:}] \leavevmode
true is always true and false is always false.

\end{description}

\begin{notice}{note}{Note}

The special constants \emph{true}, \emph{false} and \emph{none} are indeed lowercase.
Because that caused confusion in the past, when writing \emph{True} expands
to an undefined variable that is considered false, all three of them can
be written in title case too (\emph{True}, \emph{False}, and \emph{None}).  However for
consistency (all Jinja identifiers are lowercase) you should use the
lowercase versions.
\end{notice}


\subsection{Math}
\label{templates:math}
Jinja allows you to calculate with values.  This is rarely useful in templates
but exists for completeness' sake.  The following operators are supported:
\begin{description}
\item[{+}] \leavevmode
Adds two objects together.  Usually the objects are numbers but if both are
strings or lists you can concatenate them this way.  This however is not
the preferred way to concatenate strings!  For string concatenation have
a look at the \code{\textasciitilde{}} operator.  \code{\{\{ 1 + 1 \}\}} is \code{2}.

\item[{-}] \leavevmode
Substract the second number from the first one.  \code{\{\{ 3 - 2 \}\}} is \code{1}.

\end{description}
\begin{description}
\item[{/}] \leavevmode
Divide two numbers.  The return value will be a floating point number.
\code{\{\{ 1 / 2 \}\}} is \code{\{\{ 0.5 \}\}}.

\end{description}
\begin{description}
\item[{//}] \leavevmode
Divide two numbers and return the truncated integer result.
\code{\{\{ 20 / 7 \}\}} is \code{2}.

\end{description}
\begin{description}
\item[{\%}] \leavevmode
Calculate the remainder of an integer division.  \code{\{\{ 11 \% 7 \}\}} is \code{4}.

\item[{*}] \leavevmode
Multiply the left operand with the right one.  \code{\{\{ 2 * 2 \}\}} would
return \code{4}.  This can also be used to repeat a string multiple times.
\code{\{\{ '=' * 80 \}\}} would print a bar of 80 equal signs.

\item[{**}] \leavevmode
Raise the left operand to the power of the right operand.  \code{\{\{ 2**3 \}\}}
would return \code{8}.

\end{description}


\subsection{Comparisons}
\label{templates:comparisons}\begin{description}
\item[{==}] \leavevmode
Compares two objects for equality.

\item[{!=}] \leavevmode
Compares two objects for inequality.

\end{description}
\begin{description}
\item[{\textgreater{}}] \leavevmode
\emph{true} if the left hand side is greater than the right hand side.

\item[{\textgreater{}=}] \leavevmode
\emph{true} if the left hand side is greater or equal to the right hand side.

\end{description}
\begin{description}
\item[{\textless{}}] \leavevmode
\emph{true} if the left hand side is lower than the right hand side.

\item[{\textless{}=}] \leavevmode
\emph{true} if the left hand side is lower or equal to the right hand side.

\end{description}


\subsection{Logic}
\label{templates:logic}
For \emph{if} statements, \emph{for} filtering or \emph{if} expressions it can be useful to
combine multiple expressions:
\begin{description}
\item[{and}] \leavevmode
Return true if the left and the right operand is true.

\item[{or}] \leavevmode
Return true if the left or the right operand is true.

\item[{not}] \leavevmode
negate a statement (see below).

\item[{(expr)}] \leavevmode
group an expression.

\end{description}

\begin{notice}{note}{Note}

The \code{is} and \code{in} operators support negation using an infix notation
too: \code{foo is not bar} and \code{foo not in bar} instead of \code{not foo is bar}
and \code{not foo in bar}.  All other expressions require a prefix notation:
\code{not (foo and bar).}
\end{notice}


\subsection{Other Operators}
\label{templates:other-operators}
The following operators are very useful but don't fit into any of the other
two categories:
\begin{description}
\item[{in}] \leavevmode
Perform sequence / mapping containment test.  Returns true if the left
operand is contained in the right.  \code{\{\{ 1 in {[}1, 2, 3{]} \}\}} would for
example return true.

\item[{is}] \leavevmode
Performs a {\hyperref[templates:tests]{\emph{test}}}.

\item[{\textbar{}}] \leavevmode
Applies a {\hyperref[templates:filters]{\emph{filter}}}.

\end{description}
\begin{description}
\item[{\textasciitilde{}}] \leavevmode
Converts all operands into strings and concatenates them.
\code{\{\{ "Hello " \textasciitilde{} name \textasciitilde{} "!" \}\}} would return (assuming \emph{name} is
\code{'John'}) \code{Hello John!}.

\item[{()}] \leavevmode
Call a callable: \code{\{\{ post.render() \}\}}.  Inside of the parentheses you
can use positional arguments and keyword arguments like in python:
\code{\{\{ post.render(user, full=true) \}\}}.

\item[{. / {[}{]}}] \leavevmode
Get an attribute of an object.  (See {\hyperref[templates:variables]{\emph{Variables}}})

\end{description}


\subsection{If Expression}
\label{templates:id10}\label{templates:if-expression}
It is also possible to use inline \emph{if} expressions.  These are useful in some
situations.  For example you can use this to extend from one template if a
variable is defined, otherwise from the default layout template:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{extends} \PYG{n+nv}{layout\PYGZus{}template} \PYG{k}{if} \PYG{n+nv}{layout\PYGZus{}template} \PYG{k}{is} \PYG{n+nf}{defined} \PYG{k}{else} \PYG{l+s+s1}{'master.html'} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}

The general syntax is \code{\textless{}do something\textgreater{} if \textless{}something is true\textgreater{} else \textless{}do
something else\textgreater{}}.

The \emph{else} part is optional.  If not provided the else block implicitly
evaluates into an undefined object:

\begin{Verbatim}[commandchars=@\[\]]
{{ '@PYGZlb[]@%s@PYGZrb[]' @% page.title if page.title }}
\end{Verbatim}


\section{List of Builtin Filters}
\label{templates:builtin-filters}\label{templates:list-of-builtin-filters}\index{abs() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:abs}\pysiglinewithargsret{\bfcode{abs}}{\emph{number}}{}
Return the absolute value of the argument.

\end{fulllineitems}

\index{attr() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:attr}\pysiglinewithargsret{\bfcode{attr}}{\emph{obj}, \emph{name}}{}
Get an attribute of an object.  \code{foo\textbar{}attr("bar")} works like
\code{foo{[}"bar"{]}} just that always an attribute is returned and items are not
looked up.

See {\hyperref[templates:notes-on-subscriptions]{\emph{Notes on subscriptions}}} for more details.

\end{fulllineitems}

\index{batch() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:batch}\pysiglinewithargsret{\bfcode{batch}}{\emph{value}, \emph{linecount}, \emph{fill\_with=None}}{}
A filter that batches items. It works pretty much like \emph{slice}
just the other way round. It returns a list of lists with the
given number of items. If you provide a second parameter this
is used to fill missing items. See this example:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nt}{\textless{}table}\PYG{n+nt}{\textgreater{}}
\PYG{c+cp}{\PYGZob{}\%}- \PYG{k}{for} \PYG{n+nv}{row} \PYG{k}{in} \PYG{n+nv}{items}\PYG{o}{\textbar{}}\PYG{n+nf}{batch}\PYG{o}{(}\PYG{l+m}{3}\PYG{o}{,} \PYG{l+s+s1}{'\&nbsp;'}\PYG{o}{)} \PYG{c+cp}{\%\PYGZcb{}}
  \PYG{n+nt}{\textless{}tr}\PYG{n+nt}{\textgreater{}}
  \PYG{c+cp}{\PYGZob{}\%}- \PYG{k}{for} \PYG{n+nv}{column} \PYG{k}{in} \PYG{n+nv}{row} \PYG{c+cp}{\%\PYGZcb{}}
    \PYG{n+nt}{\textless{}td}\PYG{n+nt}{\textgreater{}}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{column} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{n+nt}{\textless{}/td\textgreater{}}
  \PYG{c+cp}{\PYGZob{}\%}- \PYG{k}{endfor} \PYG{c+cp}{\%\PYGZcb{}}
  \PYG{n+nt}{\textless{}/tr\textgreater{}}
\PYG{c+cp}{\PYGZob{}\%}- \PYG{k}{endfor} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{n+nt}{\textless{}/table\textgreater{}}
\end{Verbatim}

\end{fulllineitems}

\index{capitalize() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:capitalize}\pysiglinewithargsret{\bfcode{capitalize}}{\emph{s}}{}
Capitalize a value. The first character will be uppercase, all others
lowercase.

\end{fulllineitems}

\index{center() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:center}\pysiglinewithargsret{\bfcode{center}}{\emph{value}, \emph{width=80}}{}
Centers the value in a field of a given width.

\end{fulllineitems}

\index{default() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:default}\pysiglinewithargsret{\bfcode{default}}{\emph{value}, \emph{default\_value=u'`}, \emph{boolean=False}}{}
If the value is undefined it will return the passed default value,
otherwise the value of the variable:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{my\PYGZus{}variable}\PYG{o}{\textbar{}}\PYG{n+nf}{default}\PYG{o}{(}\PYG{l+s+s1}{'my\PYGZus{}variable is not defined'}\PYG{o}{)} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}
\end{Verbatim}

This will output the value of \code{my\_variable} if the variable was
defined, otherwise \code{'my\_variable is not defined'}. If you want
to use default with variables that evaluate to false you have to
set the second parameter to \emph{true}:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{l+s+s1}{''}\PYG{o}{\textbar{}}\PYG{n+nf}{default}\PYG{o}{(}\PYG{l+s+s1}{'the string was empty'}\PYG{o}{,} \PYG{k+kp}{true}\PYG{o}{)} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}
\end{Verbatim}
\begin{quote}\begin{description}
\item[{Aliases }] \leavevmode
\code{d}

\end{description}\end{quote}

\end{fulllineitems}

\index{dictsort() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:dictsort}\pysiglinewithargsret{\bfcode{dictsort}}{\emph{value}, \emph{case\_sensitive=False}, \emph{by='key'}}{}
Sort a dict and yield (key, value) pairs. Because python dicts are
unsorted you may want to use this function to order them by either
key or value:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{for} \PYG{n+nv}{item} \PYG{k}{in} \PYG{n+nv}{mydict}\PYG{o}{\textbar{}}\PYG{n+nf}{dictsort} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{x}{    sort the dict by key, case insensitive}

\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{for} \PYG{n+nv}{item} \PYG{k}{in} \PYG{n+nv}{mydict}\PYG{o}{\textbar{}}\PYG{n+nf}{dicsort}\PYG{o}{(}\PYG{k+kp}{true}\PYG{o}{)} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{x}{    sort the dict by key, case sensitive}

\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{for} \PYG{n+nv}{item} \PYG{k}{in} \PYG{n+nv}{mydict}\PYG{o}{\textbar{}}\PYG{n+nf}{dictsort}\PYG{o}{(}\PYG{k+kp}{false}\PYG{o}{,} \PYG{l+s+s1}{'value'}\PYG{o}{)} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{x}{    sort the dict by key, case insensitive, sorted}
\PYG{x}{    normally and ordered by value.}
\end{Verbatim}

\end{fulllineitems}

\index{escape() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:escape}\pysiglinewithargsret{\bfcode{escape}}{\emph{s}}{}
Convert the characters \&, \textless{}, \textgreater{}, ` and '' in string s to HTML-safe
sequences.  Use this if you need to display text that might contain
such characters in HTML.  Marks return value as markup string.
\begin{quote}\begin{description}
\item[{Aliases }] \leavevmode
\code{e}

\end{description}\end{quote}

\end{fulllineitems}

\index{filesizeformat() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:filesizeformat}\pysiglinewithargsret{\bfcode{filesizeformat}}{\emph{value}, \emph{binary=False}}{}
Format the value like a `human-readable' file size (i.e. 13 KB,
4.1 MB, 102 bytes, etc).  Per default decimal prefixes are used (mega,
giga, etc.), if the second parameter is set to \emph{True} the binary
prefixes are used (mebi, gibi).

\end{fulllineitems}

\index{first() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:first}\pysiglinewithargsret{\bfcode{first}}{\emph{seq}}{}
Return the first item of a sequence.

\end{fulllineitems}

\index{float() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:float}\pysiglinewithargsret{\bfcode{float}}{\emph{value}, \emph{default=0.0}}{}
Convert the value into a floating point number. If the
conversion doesn't work it will return \code{0.0}. You can
override this default using the first parameter.

\end{fulllineitems}

\index{forceescape() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:forceescape}\pysiglinewithargsret{\bfcode{forceescape}}{\emph{value}}{}
Enforce HTML escaping.  This will probably double escape variables.

\end{fulllineitems}

\index{format() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:format}\pysiglinewithargsret{\bfcode{format}}{\emph{value}, \emph{*args}, \emph{**kwargs}}{}
Apply python string formatting on an object:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{l+s+s2}{"\%s - \%s"}\PYG{o}{\textbar{}}\PYG{n+nf}{format}\PYG{o}{(}\PYG{l+s+s2}{"Hello?"}\PYG{o}{,} \PYG{l+s+s2}{"Foo!"}\PYG{o}{)} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}
\PYG{x}{    -\textgreater{} Hello? - Foo!}
\end{Verbatim}

\end{fulllineitems}

\index{groupby() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:groupby}\pysiglinewithargsret{\bfcode{groupby}}{\emph{value}, \emph{attribute}}{}
Group a sequence of objects by a common attribute.

If you for example have a list of dicts or objects that represent persons
with \emph{gender}, \emph{first\_name} and \emph{last\_name} attributes and you want to
group all users by genders you can do something like the following
snippet:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nt}{\textless{}ul}\PYG{n+nt}{\textgreater{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{for} \PYG{n+nv}{group} \PYG{k}{in} \PYG{n+nv}{persons}\PYG{o}{\textbar{}}\PYG{n+nf}{groupby}\PYG{o}{(}\PYG{l+s+s1}{'gender'}\PYG{o}{)} \PYG{c+cp}{\%\PYGZcb{}}
    \PYG{n+nt}{\textless{}li}\PYG{n+nt}{\textgreater{}}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{group}\PYG{n+nv}{.grouper} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{n+nt}{\textless{}ul}\PYG{n+nt}{\textgreater{}}
    \PYG{c+cp}{\PYGZob{}\%} \PYG{k}{for} \PYG{n+nv}{person} \PYG{k}{in} \PYG{n+nv}{group}\PYG{n+nv}{.list} \PYG{c+cp}{\%\PYGZcb{}}
        \PYG{n+nt}{\textless{}li}\PYG{n+nt}{\textgreater{}}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{person}\PYG{n+nv}{.first\PYGZus{}name} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}} \PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{person}\PYG{n+nv}{.last\PYGZus{}name} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{n+nt}{\textless{}/li\textgreater{}}
    \PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endfor} \PYG{c+cp}{\%\PYGZcb{}}\PYG{n+nt}{\textless{}/ul\textgreater{}}\PYG{n+nt}{\textless{}/li\textgreater{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endfor} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{n+nt}{\textless{}/ul\textgreater{}}
\end{Verbatim}

Additionally it's possible to use tuple unpacking for the grouper and
list:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nt}{\textless{}ul}\PYG{n+nt}{\textgreater{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{for} \PYG{n+nv}{grouper}\PYG{o}{,} \PYG{n+nv}{list} \PYG{k}{in} \PYG{n+nv}{persons}\PYG{o}{\textbar{}}\PYG{n+nf}{groupby}\PYG{o}{(}\PYG{l+s+s1}{'gender'}\PYG{o}{)} \PYG{c+cp}{\%\PYGZcb{}}
    ...
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endfor} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{n+nt}{\textless{}/ul\textgreater{}}
\end{Verbatim}

As you can see the item we're grouping by is stored in the \emph{grouper}
attribute and the \emph{list} contains all the objects that have this grouper
in common.

\end{fulllineitems}

\index{indent() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:indent}\pysiglinewithargsret{\bfcode{indent}}{\emph{s}, \emph{width=4}, \emph{indentfirst=False}}{}
Return a copy of the passed string, each line indented by
4 spaces. The first line is not indented. If you want to
change the number of spaces or indent the first line too
you can pass additional parameters to the filter:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{mytext}\PYG{o}{\textbar{}}\PYG{n+nf}{indent}\PYG{o}{(}\PYG{l+m}{2}\PYG{o}{,} \PYG{k+kp}{true}\PYG{o}{)} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}
\PYG{x}{    indent by two spaces and indent the first line too.}
\end{Verbatim}

\end{fulllineitems}

\index{int() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:int}\pysiglinewithargsret{\bfcode{int}}{\emph{value}, \emph{default=0}}{}
Convert the value into an integer. If the
conversion doesn't work it will return \code{0}. You can
override this default using the first parameter.

\end{fulllineitems}

\index{join() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:join}\pysiglinewithargsret{\bfcode{join}}{\emph{eval\_ctx}, \emph{value}, \emph{d=u'`}}{}
Return a string which is the concatenation of the strings in the
sequence. The separator between elements is an empty string per
default, you can define it with the optional parameter:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{o}{[}\PYG{l+m}{1}\PYG{o}{,} \PYG{l+m}{2}\PYG{o}{,} \PYG{l+m}{3}\PYG{o}{]}\PYG{o}{\textbar{}}\PYG{n+nf}{join}\PYG{o}{(}\PYG{l+s+s1}{'\textbar{}'}\PYG{o}{)} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}
\PYG{x}{    -\textgreater{} 1\textbar{}2\textbar{}3}

\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{o}{[}\PYG{l+m}{1}\PYG{o}{,} \PYG{l+m}{2}\PYG{o}{,} \PYG{l+m}{3}\PYG{o}{]}\PYG{o}{\textbar{}}\PYG{n+nf}{join} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}
\PYG{x}{    -\textgreater{} 123}
\end{Verbatim}

\end{fulllineitems}

\index{last() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:last}\pysiglinewithargsret{\bfcode{last}}{\emph{seq}}{}
Return the last item of a sequence.

\end{fulllineitems}

\index{length() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:length}\pysiglinewithargsret{\bfcode{length}}{\emph{object}}{}
Return the number of items of a sequence or mapping.
\begin{quote}\begin{description}
\item[{Aliases }] \leavevmode
\code{count}

\end{description}\end{quote}

\end{fulllineitems}

\index{list() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:list}\pysiglinewithargsret{\bfcode{list}}{\emph{value}}{}
Convert the value into a list.  If it was a string the returned list
will be a list of characters.

\end{fulllineitems}

\index{lower() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:lower}\pysiglinewithargsret{\bfcode{lower}}{\emph{s}}{}
Convert a value to lowercase.

\end{fulllineitems}

\index{pprint() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:pprint}\pysiglinewithargsret{\bfcode{pprint}}{\emph{value}, \emph{verbose=False}}{}
Pretty print a variable. Useful for debugging.

With Jinja 1.2 onwards you can pass it a parameter.  If this parameter
is truthy the output will be more verbose (this requires \emph{pretty})

\end{fulllineitems}

\index{random() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:random}\pysiglinewithargsret{\bfcode{random}}{\emph{seq}}{}
Return a random item from the sequence.

\end{fulllineitems}

\index{replace() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:replace}\pysiglinewithargsret{\bfcode{replace}}{\emph{eval\_ctx}, \emph{s}, \emph{old}, \emph{new}, \emph{count=None}}{}
Return a copy of the value with all occurrences of a substring
replaced with a new one. The first argument is the substring
that should be replaced, the second is the replacement string.
If the optional third argument \code{count} is given, only the first
\code{count} occurrences are replaced:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{l+s+s2}{"Hello World"}\PYG{o}{\textbar{}}\PYG{n+nf}{replace}\PYG{o}{(}\PYG{l+s+s2}{"Hello"}\PYG{o}{,} \PYG{l+s+s2}{"Goodbye"}\PYG{o}{)} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}
\PYG{x}{    -\textgreater{} Goodbye World}

\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{l+s+s2}{"aaaaargh"}\PYG{o}{\textbar{}}\PYG{n+nf}{replace}\PYG{o}{(}\PYG{l+s+s2}{"a"}\PYG{o}{,} \PYG{l+s+s2}{"d'oh, "}\PYG{o}{,} \PYG{l+m}{2}\PYG{o}{)} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}
\PYG{x}{    -\textgreater{} d'oh, d'oh, aaargh}
\end{Verbatim}

\end{fulllineitems}

\index{reverse() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:reverse}\pysiglinewithargsret{\bfcode{reverse}}{\emph{value}}{}
Reverse the object or return an iterator the iterates over it the other
way round.

\end{fulllineitems}

\index{round() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:round}\pysiglinewithargsret{\bfcode{round}}{\emph{value}, \emph{precision=0}, \emph{method='common'}}{}
Round the number to a given precision. The first
parameter specifies the precision (default is \code{0}), the
second the rounding method:
\begin{itemize}
\item {} 
\code{'common'} rounds either up or down

\item {} 
\code{'ceil'} always rounds up

\item {} 
\code{'floor'} always rounds down

\end{itemize}

If you don't specify a method \code{'common'} is used.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{l+m}{4}\PYG{l+m}{2.55}\PYG{o}{\textbar{}}\PYG{n+nf}{round} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}
\PYG{x}{    -\textgreater{} 43.0}
\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{l+m}{4}\PYG{l+m}{2.55}\PYG{o}{\textbar{}}\PYG{n+nf}{round}\PYG{o}{(}\PYG{l+m}{1}\PYG{o}{,} \PYG{l+s+s1}{'floor'}\PYG{o}{)} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}
\PYG{x}{    -\textgreater{} 42.5}
\end{Verbatim}

Note that even if rounded to 0 precision, a float is returned.  If
you need a real integer, pipe it through \emph{int}:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{l+m}{4}\PYG{l+m}{2.55}\PYG{o}{\textbar{}}\PYG{n+nf}{round}\PYG{o}{\textbar{}}\PYG{n+nf}{int} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}
\PYG{x}{    -\textgreater{} 43}
\end{Verbatim}

\end{fulllineitems}

\index{safe() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:safe}\pysiglinewithargsret{\bfcode{safe}}{\emph{value}}{}
Mark the value as safe which means that in an environment with automatic
escaping enabled this variable will not be escaped.

\end{fulllineitems}

\index{slice() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:slice}\pysiglinewithargsret{\bfcode{slice}}{\emph{value}, \emph{slices}, \emph{fill\_with=None}}{}
Slice an iterator and return a list of lists containing
those items. Useful if you want to create a div containing
three ul tags that represent columns:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nt}{\textless{}div} \PYG{n+na}{class=}\PYG{l+s}{"columwrapper"}\PYG{n+nt}{\textgreater{}}
  \PYG{c+cp}{\PYGZob{}\%}- \PYG{k}{for} \PYG{n+nv}{column} \PYG{k}{in} \PYG{n+nv}{items}\PYG{o}{\textbar{}}\PYG{n+nf}{slice}\PYG{o}{(}\PYG{l+m}{3}\PYG{o}{)} \PYG{c+cp}{\%\PYGZcb{}}
    \PYG{n+nt}{\textless{}ul} \PYG{n+na}{class=}\PYG{l+s}{"column-}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nb}{loop}\PYG{n+nv}{.index} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{l+s}{"}\PYG{n+nt}{\textgreater{}}
    \PYG{c+cp}{\PYGZob{}\%}- \PYG{k}{for} \PYG{n+nv}{item} \PYG{k}{in} \PYG{n+nv}{column} \PYG{c+cp}{\%\PYGZcb{}}
      \PYG{n+nt}{\textless{}li}\PYG{n+nt}{\textgreater{}}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{item} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{n+nt}{\textless{}/li\textgreater{}}
    \PYG{c+cp}{\PYGZob{}\%}- \PYG{k}{endfor} \PYG{c+cp}{\%\PYGZcb{}}
    \PYG{n+nt}{\textless{}/ul\textgreater{}}
  \PYG{c+cp}{\PYGZob{}\%}- \PYG{k}{endfor} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{n+nt}{\textless{}/div\textgreater{}}
\end{Verbatim}

If you pass it a second argument it's used to fill missing
values on the last iteration.

\end{fulllineitems}

\index{sort() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:sort}\pysiglinewithargsret{\bfcode{sort}}{\emph{value}, \emph{reverse=False}, \emph{case\_sensitive=False}}{}
Sort an iterable.  Per default it sorts ascending, if you pass it
true as first argument it will reverse the sorting.

If the iterable is made of strings the third parameter can be used to
control the case sensitiveness of the comparison which is disabled by
default.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{for} \PYG{n+nv}{item} \PYG{k}{in} \PYG{n+nv}{iterable}\PYG{o}{\textbar{}}\PYG{n+nf}{sort} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{x}{    ...}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endfor} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}

\end{fulllineitems}

\index{string() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:string}\pysiglinewithargsret{\bfcode{string}}{\emph{s}}{}
Make a string unicode if it isn't already.  That way a markup
string is not converted back to unicode.

\end{fulllineitems}

\index{striptags() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:striptags}\pysiglinewithargsret{\bfcode{striptags}}{\emph{value}}{}
Strip SGML/XML tags and replace adjacent whitespace by one space.

\end{fulllineitems}

\index{sum() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:sum}\pysiglinewithargsret{\bfcode{sum}}{\emph{sequence}\optional{, \emph{start}}}{}
Returns the sum of a sequence of numbers (NOT strings) plus the value
of parameter `start' (which defaults to 0).  When the sequence is
empty, returns start.

\end{fulllineitems}

\index{title() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:title}\pysiglinewithargsret{\bfcode{title}}{\emph{s}}{}
Return a titlecased version of the value. I.e. words will start with
uppercase letters, all remaining characters are lowercase.

\end{fulllineitems}

\index{trim() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:trim}\pysiglinewithargsret{\bfcode{trim}}{\emph{value}}{}
Strip leading and trailing whitespace.

\end{fulllineitems}

\index{truncate() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:truncate}\pysiglinewithargsret{\bfcode{truncate}}{\emph{s}, \emph{length=255}, \emph{killwords=False}, \emph{end='...'}}{}
Return a truncated copy of the string. The length is specified
with the first parameter which defaults to \code{255}. If the second
parameter is \code{true} the filter will cut the text at length. Otherwise
it will try to save the last word. If the text was in fact
truncated it will append an ellipsis sign (\code{"..."}). If you want a
different ellipsis sign than \code{"..."} you can specify it using the
third parameter.

\end{fulllineitems}

\index{upper() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:upper}\pysiglinewithargsret{\bfcode{upper}}{\emph{s}}{}
Convert a value to uppercase.

\end{fulllineitems}

\index{urlize() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:urlize}\pysiglinewithargsret{\bfcode{urlize}}{\emph{eval\_ctx}, \emph{value}, \emph{trim\_url\_limit=None}, \emph{nofollow=False}}{}
Converts URLs in plain text into clickable links.

If you pass the filter an additional integer it will shorten the urls
to that number. Also a third argument exists that makes the urls
``nofollow'':

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{mytext}\PYG{o}{\textbar{}}\PYG{n+nf}{urlize}\PYG{o}{(}\PYG{l+m}{4}\PYG{l+m}{0}\PYG{o}{,} \PYG{k+kp}{true}\PYG{o}{)} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}
\PYG{x}{    links are shortened to 40 chars and defined with rel="nofollow"}
\end{Verbatim}

\end{fulllineitems}

\index{wordcount() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:wordcount}\pysiglinewithargsret{\bfcode{wordcount}}{\emph{s}}{}
Count the words in that string.

\end{fulllineitems}

\index{wordwrap() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:wordwrap}\pysiglinewithargsret{\bfcode{wordwrap}}{\emph{s}, \emph{width=79}, \emph{break\_long\_words=True}}{}
Return a copy of the string passed to the filter wrapped after
\code{79} characters.  You can override this default using the first
parameter.  If you set the second parameter to \emph{false} Jinja will not
split words apart if they are longer than \emph{width}.

\end{fulllineitems}

\index{xmlattr() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:xmlattr}\pysiglinewithargsret{\bfcode{xmlattr}}{\emph{\_eval\_ctx}, \emph{d}, \emph{autospace=True}}{}
Create an SGML/XML attribute string based on the items in a dict.
All values that are neither \emph{none} nor \emph{undefined} are automatically
escaped:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nt}{\textless{}ul}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{o}{\PYGZob{}}\PYG{l+s+s1}{'class'}\PYG{o}{:} \PYG{l+s+s1}{'my\PYGZus{}list'}\PYG{o}{,} \PYG{l+s+s1}{'missing'}\PYG{o}{:} \PYG{k+kp}{none}\PYG{o}{,}
        \PYG{l+s+s1}{'id'}\PYG{o}{:} \PYG{l+s+s1}{'list-\%d'}\PYG{o}{\textbar{}}\PYG{n+nf}{format}\PYG{o}{(}\PYG{n+nv}{variable}\PYG{o}{)}\PYG{o}{\PYGZcb{}}\PYG{o}{\textbar{}}\PYG{n+nf}{xmlattr} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{n+nt}{\textgreater{}}
...
\PYG{n+nt}{\textless{}/ul\textgreater{}}
\end{Verbatim}

Results in something like this:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nt}{\textless{}ul} \PYG{n+na}{class=}\PYG{l+s}{"my\PYGZus{}list"} \PYG{n+na}{id=}\PYG{l+s}{"list-42"}\PYG{n+nt}{\textgreater{}}
...
\PYG{n+nt}{\textless{}/ul\textgreater{}}
\end{Verbatim}

As you can see it automatically prepends a space in front of the item
if the filter returned something unless the second parameter is false.

\end{fulllineitems}



\section{List of Builtin Tests}
\label{templates:builtin-tests}\label{templates:list-of-builtin-tests}\index{callable() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:callable}\pysiglinewithargsret{\bfcode{callable}}{\emph{object}}{}
Return whether the object is callable (i.e., some kind of function).
Note that classes are callable, as are instances with a \_\_call\_\_() method.

\end{fulllineitems}

\index{defined() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:defined}\pysiglinewithargsret{\bfcode{defined}}{\emph{value}}{}
Return true if the variable is defined:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{if} \PYG{n+nv}{variable} \PYG{k}{is} \PYG{n+nf}{defined} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{x}{    value of variable: }\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{variable} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{else} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{x}{    variable is not defined}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endif} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}

See the {\hyperref[templates:default]{\code{default()}}} filter for a simple way to set undefined
variables.

\end{fulllineitems}

\index{divisibleby() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:divisibleby}\pysiglinewithargsret{\bfcode{divisibleby}}{\emph{value}, \emph{num}}{}
Check if a variable is divisible by a number.

\end{fulllineitems}

\index{escaped() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:escaped}\pysiglinewithargsret{\bfcode{escaped}}{\emph{value}}{}
Check if the value is escaped.

\end{fulllineitems}

\index{even() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:even}\pysiglinewithargsret{\bfcode{even}}{\emph{value}}{}
Return true if the variable is even.

\end{fulllineitems}

\index{iterable() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:iterable}\pysiglinewithargsret{\bfcode{iterable}}{\emph{value}}{}
Check if it's possible to iterate over an object.

\end{fulllineitems}

\index{lower() (built-in function)}

\begin{fulllineitems}
\pysiglinewithargsret{\bfcode{lower}}{\emph{value}}{}
Return true if the variable is lowercased.

\end{fulllineitems}

\index{none() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:none}\pysiglinewithargsret{\bfcode{none}}{\emph{value}}{}
Return true if the variable is none.

\end{fulllineitems}

\index{number() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:number}\pysiglinewithargsret{\bfcode{number}}{\emph{value}}{}
Return true if the variable is a number.

\end{fulllineitems}

\index{odd() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:odd}\pysiglinewithargsret{\bfcode{odd}}{\emph{value}}{}
Return true if the variable is odd.

\end{fulllineitems}

\index{sameas() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:sameas}\pysiglinewithargsret{\bfcode{sameas}}{\emph{value}, \emph{other}}{}
Check if an object points to the same memory address than another
object:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{if} \PYG{n+nv}{foo}\PYG{n+nv}{.attribute} \PYG{k}{is} \PYG{n+nf}{sameas} \PYG{k+kp}{false} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{x}{    the foo attribute really is the {}`False{}` singleton}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endif} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}

\end{fulllineitems}

\index{sequence() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:sequence}\pysiglinewithargsret{\bfcode{sequence}}{\emph{value}}{}
Return true if the variable is a sequence. Sequences are variables
that are iterable.

\end{fulllineitems}

\index{string() (built-in function)}

\begin{fulllineitems}
\pysiglinewithargsret{\bfcode{string}}{\emph{value}}{}
Return true if the object is a string.

\end{fulllineitems}

\index{undefined() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:undefined}\pysiglinewithargsret{\bfcode{undefined}}{\emph{value}}{}
Like {\hyperref[templates:defined]{\code{defined()}}} but the other way round.

\end{fulllineitems}

\index{upper() (built-in function)}

\begin{fulllineitems}
\pysiglinewithargsret{\bfcode{upper}}{\emph{value}}{}
Return true if the variable is uppercased.

\end{fulllineitems}



\section{List of Global Functions}
\label{templates:builtin-globals}\label{templates:list-of-global-functions}
The following functions are available in the global scope by default:
\index{range() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:range}\pysiglinewithargsret{\bfcode{range}}{\optional{\emph{start}}, \emph{stop}\optional{, \emph{step}}}{}
Return a list containing an arithmetic progression of integers.
range(i, j) returns {[}i, i+1, i+2, ..., j-1{]}; start (!) defaults to 0.
When step is given, it specifies the increment (or decrement).
For example, range(4) returns {[}0, 1, 2, 3{]}.  The end point is omitted!
These are exactly the valid indices for a list of 4 elements.

This is useful to repeat a template block multiple times for example
to fill a list.  Imagine you have 7 users in the list but you want to
render three empty items to enforce a height with CSS:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nt}{\textless{}ul}\PYG{n+nt}{\textgreater{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{for} \PYG{n+nv}{user} \PYG{k}{in} \PYG{n+nv}{users} \PYG{c+cp}{\%\PYGZcb{}}
    \PYG{n+nt}{\textless{}li}\PYG{n+nt}{\textgreater{}}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{user}\PYG{n+nv}{.username} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{n+nt}{\textless{}/li\textgreater{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endfor} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{for} \PYG{n+nv}{number} \PYG{k}{in} \PYG{n+nv}{range}\PYG{o}{(}\PYG{l+m}{1}\PYG{l+m}{0} \PYG{o}{-} \PYG{n+nv}{users}\PYG{o}{\textbar{}}\PYG{n+nf}{count}\PYG{o}{)} \PYG{c+cp}{\%\PYGZcb{}}
    \PYG{n+nt}{\textless{}li} \PYG{n+na}{class=}\PYG{l+s}{"empty"}\PYG{n+nt}{\textgreater{}}\PYG{n+nt}{\textless{}span}\PYG{n+nt}{\textgreater{}}...\PYG{n+nt}{\textless{}/span\textgreater{}}\PYG{n+nt}{\textless{}/li\textgreater{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endfor} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{n+nt}{\textless{}/ul\textgreater{}}
\end{Verbatim}

\end{fulllineitems}

\index{lipsum() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:lipsum}\pysiglinewithargsret{\bfcode{lipsum}}{\emph{n=5}, \emph{html=True}, \emph{min=20}, \emph{max=100}}{}
Generates some lorem ipsum for the template.  Per default five paragraphs
with HTML are generated each paragraph between 20 and 100 words.  If html
is disabled regular text is returned.  This is useful to generate simple
contents for layout testing.

\end{fulllineitems}

\index{dict() (built-in function)}

\begin{fulllineitems}
\phantomsection\label{templates:dict}\pysiglinewithargsret{\bfcode{dict}}{\emph{**items}}{}
A convenient alternative to dict literals.  \code{\{'foo': 'bar'\}} is the same
as \code{dict(foo='bar')}.

\end{fulllineitems}

\index{cycler (built-in class)}

\begin{fulllineitems}
\phantomsection\label{templates:cycler}\pysiglinewithargsret{\strong{class }\bfcode{cycler}}{\emph{*items}}{}
The cycler allows you to cycle among values similar to how \emph{loop.cycle}
works.  Unlike \emph{loop.cycle} however you can use this cycler outside of
loops or over multiple loops.

This is for example very useful if you want to show a list of folders and
files, with the folders on top, but both in the same list with alternating
row colors.

The following example shows how \emph{cycler} can be used:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{set} \PYG{n+nv}{row\PYGZus{}class} \PYG{o}{=} \PYG{n+nv}{cycler}\PYG{o}{(}\PYG{l+s+s1}{'odd'}\PYG{o}{,} \PYG{l+s+s1}{'even'}\PYG{o}{)} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{n+nt}{\textless{}ul} \PYG{n+na}{class=}\PYG{l+s}{"browser"}\PYG{n+nt}{\textgreater{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{for} \PYG{n+nv}{folder} \PYG{k}{in} \PYG{n+nv}{folders} \PYG{c+cp}{\%\PYGZcb{}}
  \PYG{n+nt}{\textless{}li} \PYG{n+na}{class=}\PYG{l+s}{"folder }\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{row\PYGZus{}class}\PYG{n+nv}{.next}\PYG{o}{(}\PYG{o}{)} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{l+s}{"}\PYG{n+nt}{\textgreater{}}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{folder}\PYG{o}{\textbar{}}\PYG{n+nf}{e} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{n+nt}{\textless{}/li\textgreater{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endfor} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{for} \PYG{n+nv}{filename} \PYG{k}{in} \PYG{n+nv}{files} \PYG{c+cp}{\%\PYGZcb{}}
  \PYG{n+nt}{\textless{}li} \PYG{n+na}{class=}\PYG{l+s}{"file }\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{row\PYGZus{}class}\PYG{n+nv}{.next}\PYG{o}{(}\PYG{o}{)} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{l+s}{"}\PYG{n+nt}{\textgreater{}}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{filename}\PYG{o}{\textbar{}}\PYG{n+nf}{e} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{n+nt}{\textless{}/li\textgreater{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endfor} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{n+nt}{\textless{}/ul\textgreater{}}
\end{Verbatim}

A cycler has the following attributes and methods:
\index{reset() (cycler method)}

\begin{fulllineitems}
\phantomsection\label{templates:cycler.reset}\pysiglinewithargsret{\bfcode{reset}}{}{}
Resets the cycle to the first item.

\end{fulllineitems}

\index{next() (cycler method)}

\begin{fulllineitems}
\phantomsection\label{templates:cycler.next}\pysiglinewithargsret{\bfcode{next}}{}{}
Goes one item a head and returns the then current item.

\end{fulllineitems}

\index{current (cycler attribute)}

\begin{fulllineitems}
\phantomsection\label{templates:cycler.current}\pysigline{\bfcode{current}}{}
Returns the current item.

\end{fulllineitems}


\textbf{new in Jinja 2.1}

\end{fulllineitems}

\index{joiner (built-in class)}

\begin{fulllineitems}
\phantomsection\label{templates:joiner}\pysiglinewithargsret{\strong{class }\bfcode{joiner}}{\emph{sep='}, \emph{`}}{}
A tiny helper that can be use to ``join'' multiple sections.  A joiner is
passed a string and will return that string every time it's calld, except
the first time in which situation it returns an empty string.  You can
use this to join things:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{set} \PYG{n+nv}{pipe} \PYG{o}{=} \PYG{n+nv}{joiner}\PYG{o}{(}\PYG{l+s+s2}{"\textbar{}"}\PYG{o}{)} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{if} \PYG{n+nv}{categories} \PYG{c+cp}{\%\PYGZcb{}} \PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{pipe}\PYG{o}{(}\PYG{o}{)} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}
    Categories: \PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{categories}\PYG{o}{\textbar{}}\PYG{n+nf}{join}\PYG{o}{(}\PYG{l+s+s2}{", "}\PYG{o}{)} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endif} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{if} \PYG{n+nv}{author} \PYG{c+cp}{\%\PYGZcb{}} \PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{pipe}\PYG{o}{(}\PYG{o}{)} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}
    Author: \PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{author}\PYG{o}{(}\PYG{o}{)} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endif} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{if} \PYG{n+nv}{can\PYGZus{}edit} \PYG{c+cp}{\%\PYGZcb{}} \PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{pipe}\PYG{o}{(}\PYG{o}{)} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}
    \PYG{n+nt}{\textless{}a} \PYG{n+na}{href=}\PYG{l+s}{"?action=edit"}\PYG{n+nt}{\textgreater{}}Edit\PYG{n+nt}{\textless{}/a\textgreater{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endif} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}

\textbf{new in Jinja 2.1}

\end{fulllineitems}



\section{Extensions}
\label{templates:extensions}
The following sections cover the built-in Jinja2 extensions that may be
enabled by the application.  The application could also provide further
extensions not covered by this documentation.  In that case there should
be a separate document explaining the extensions.


\subsection{i18n}
\label{templates:i18n}\label{templates:i18n-in-templates}
If the i18n extension is enabled it's possible to mark parts in the template
as translatable.  To mark a section as translatable you can use \emph{trans}:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nt}{\textless{}p}\PYG{n+nt}{\textgreater{}}\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{trans} \PYG{c+cp}{\%\PYGZcb{}}Hello \PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{user} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}!\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endtrans} \PYG{c+cp}{\%\PYGZcb{}}\PYG{n+nt}{\textless{}/p\textgreater{}}
\end{Verbatim}

To translate a template expression --- say, using template filters or just
accessing an attribute of an object --- you need to bind the expression to a
name for use within the translation block:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nt}{\textless{}p}\PYG{n+nt}{\textgreater{}}\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{trans} \PYG{n+nv}{user}\PYG{o}{=}\PYG{n+nv}{user}\PYG{n+nv}{.username} \PYG{c+cp}{\%\PYGZcb{}}Hello \PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{user} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}!\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endtrans} \PYG{c+cp}{\%\PYGZcb{}}\PYG{n+nt}{\textless{}/p\textgreater{}}
\end{Verbatim}

If you need to bind more than one expression inside a \emph{trans} tag, separate
the pieces with a comma (\code{,}):

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{trans} \PYG{n+nv}{book\PYGZus{}title}\PYG{o}{=}\PYG{n+nv}{book}\PYG{n+nv}{.title}\PYG{o}{,} \PYG{n+nv}{author}\PYG{o}{=}\PYG{n+nv}{author}\PYG{n+nv}{.name} \PYG{c+cp}{\%\PYGZcb{}}
This is \PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{book\PYGZus{}title} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}} by \PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{author} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endtrans} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}

Inside trans tags no statements are allowed, only variable tags are.

To pluralize, specify both the singular and plural forms with the \emph{pluralize}
tag, which appears between \emph{trans} and \emph{endtrans}:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{trans} \PYG{n+nv}{count}\PYG{o}{=}\PYG{n+nv}{list}\PYG{o}{\textbar{}}\PYG{n+nf}{length} \PYG{c+cp}{\%\PYGZcb{}}
There is \PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{count} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}} \PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{name} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}} object.
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{pluralize} \PYG{c+cp}{\%\PYGZcb{}}
There are \PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{count} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}} \PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{name} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}} objects.
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endtrans} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}

Per default the first variable in a block is used to determine the correct
singular or plural form.  If that doesn't work out you can specify the name
which should be used for pluralizing by adding it as parameter to \emph{pluralize}:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{trans} \PYG{p}{.}\PYG{p}{.}\PYG{p}{.}\PYG{o}{,} \PYG{n+nv}{user\PYGZus{}count}\PYG{o}{=}\PYG{n+nv}{users}\PYG{o}{\textbar{}}\PYG{n+nf}{length} \PYG{c+cp}{\%\PYGZcb{}}...
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{pluralize} \PYG{n+nv}{user\PYGZus{}count} \PYG{c+cp}{\%\PYGZcb{}}...\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endtrans} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}

It's also possible to translate strings in expressions.  For that purpose
three functions exist:

\_   \emph{gettext}: translate a single string
-   \emph{ngettext}: translate a pluralizable string
-   \emph{\_}: alias for \emph{gettext}

For example you can print a translated string easily this way:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{k+kp}{\PYGZus{}}\PYG{o}{(}\PYG{l+s+s1}{'Hello World!'}\PYG{o}{)} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}
\end{Verbatim}

To use placeholders you can use the \emph{format} filter:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{k+kp}{\PYGZus{}}\PYG{o}{(}\PYG{l+s+s1}{'Hello \%(user)s!'}\PYG{o}{)}\PYG{o}{\textbar{}}\PYG{n+nf}{format}\PYG{o}{(}\PYG{n+nv}{user}\PYG{o}{=}\PYG{n+nv}{user}\PYG{n+nv}{.username}\PYG{o}{)} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}
\end{Verbatim}

For multiple placeholders always use keyword arguments to \emph{format} as other
languages may not use the words in the same order.
Changed in version 2.5.
If newstyle gettext calls are activated ({\hyperref[extensions:newstyle-gettext]{\emph{Newstyle Gettext}}}), using
placeholders is a lot easier:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{gettext}\PYG{o}{(}\PYG{l+s+s1}{'Hello World!'}\PYG{o}{)} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}
\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{gettext}\PYG{o}{(}\PYG{l+s+s1}{'Hello \%(name)s!'}\PYG{o}{,} \PYG{n+nv}{name}\PYG{o}{=}\PYG{l+s+s1}{'World'}\PYG{o}{)} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}
\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{ngettext}\PYG{o}{(}\PYG{l+s+s1}{'\%(num)d apple'}\PYG{o}{,} \PYG{l+s+s1}{'\%(num)d apples'}\PYG{o}{,} \PYG{n+nv}{apples}\PYG{o}{\textbar{}}\PYG{n+nf}{count}\PYG{o}{)} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}
\end{Verbatim}

Note that the \emph{ngettext} function's format string automatically recieves
the count as \emph{num} parameter additionally to the regular parameters.


\subsection{Expression Statement}
\label{templates:expression-statement}
If the expression-statement extension is loaded a tag called \emph{do} is available
that works exactly like the regular variable expression (\code{\{\{ ... \}\}}) just
that it doesn't print anything.  This can be used to modify lists:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{do} \PYG{n+nv}{navigation}\PYG{n+nv}{.append}\PYG{o}{(}\PYG{l+s+s1}{'a string'}\PYG{o}{)} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}


\subsection{Loop Controls}
\label{templates:loop-controls}
If the application enables the {\hyperref[extensions:loopcontrols-extension]{\emph{Loop Controls}}} it's possible to
use \emph{break} and \emph{continue} in loops.  When \emph{break} is reached, the loop is
terminated, if \emph{continue} is eached the processing is stopped and continues
with the next iteration.

Here a loop that skips every second item:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{for} \PYG{n+nv}{user} \PYG{k}{in} \PYG{n+nv}{users} \PYG{c+cp}{\%\PYGZcb{}}
    \PYG{c+cp}{\PYGZob{}\%}- \PYG{k}{if} \PYG{n+nb}{loop}\PYG{n+nv}{.index} \PYG{k}{is} \PYG{n+nf}{even} \PYG{c+cp}{\%\PYGZcb{}}\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{continue} \PYG{c+cp}{\%\PYGZcb{}}\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endif} \PYG{c+cp}{\%\PYGZcb{}}
    ...
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endfor} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}

Likewise a look that stops processing after the 10th iteration:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{for} \PYG{n+nv}{user} \PYG{k}{in} \PYG{n+nv}{users} \PYG{c+cp}{\%\PYGZcb{}}
    \PYG{c+cp}{\PYGZob{}\%}- \PYG{k}{if} \PYG{n+nb}{loop}\PYG{n+nv}{.index} \PYG{o}{\textgreater{}=} \PYG{l+m}{1}\PYG{l+m}{0} \PYG{c+cp}{\%\PYGZcb{}}\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{break} \PYG{c+cp}{\%\PYGZcb{}}\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endif} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{c+cp}{\PYGZob{}\%}- \PYG{k}{endfor} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}


\subsection{With Statement}
\label{templates:with-statement}New in version 2.3.
If the application enables the {\hyperref[extensions:with-extension]{\emph{With Statement}}} it is possible to
use the \emph{with} keyword in templates.  This makes it possible to create
a new inner scope.  Variables set within this scope are not visible
outside of the scope.

With in a nutshell:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{with} \PYG{c+cp}{\%\PYGZcb{}}
    \PYG{c+cp}{\PYGZob{}\%} \PYG{k}{set} \PYG{n+nv}{foo} \PYG{o}{=} \PYG{l+m}{4}\PYG{l+m}{2} \PYG{c+cp}{\%\PYGZcb{}}
    \PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{foo} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}           foo is 42 here
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endwith} \PYG{c+cp}{\%\PYGZcb{}}
foo is not visible here any longer
\end{Verbatim}

Because it is common to set variables at the beginning of the scope
you can do that within the with statement.  The following two examples
are equivalent:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{with} \PYG{n+nv}{foo} \PYG{o}{=} \PYG{l+m}{4}\PYG{l+m}{2} \PYG{c+cp}{\%\PYGZcb{}}
    \PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{foo} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endwith} \PYG{c+cp}{\%\PYGZcb{}}

\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{with} \PYG{c+cp}{\%\PYGZcb{}}
    \PYG{c+cp}{\PYGZob{}\%} \PYG{k}{set} \PYG{n+nv}{foo} \PYG{o}{=} \PYG{l+m}{4}\PYG{l+m}{2} \PYG{c+cp}{\%\PYGZcb{}}
    \PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{foo} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endwith} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}


\section{Autoescape Extension}
\label{templates:autoescape-overrides}\label{templates:autoescape-extension}New in version 2.4.
If the application enables the {\hyperref[extensions:autoescape-extension]{\emph{Autoescape Extension}}} one can
activate and deactivate the autoescaping from within the templates.

Example:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{autoescape} \PYG{k+kp}{true} \PYG{c+cp}{\%\PYGZcb{}}
    Autoescaping is active within this block
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endautoescape} \PYG{c+cp}{\%\PYGZcb{}}

\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{autoescape} \PYG{k+kp}{false} \PYG{c+cp}{\%\PYGZcb{}}
    Autoescaping is inactive within this block
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endautoescape} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}

After the \emph{endautoescape} the behavior is reverted to what it was before.


\chapter{Extensions}
\label{extensions:extensions}\label{extensions:jinja-extensions}\label{extensions::doc}
Jinja2 supports extensions that can add extra filters, tests, globals or even
extend the parser.  The main motivation of extensions is it to move often used
code into a reusable class like adding support for internationalization.


\section{Adding Extensions}
\label{extensions:adding-extensions}
Extensions are added to the Jinja2 environment at creation time.  Once the
environment is created additional extensions cannot be added.  To add an
extension pass a list of extension classes or import paths to the
\emph{environment} parameter of the \code{Environment} constructor.  The following
example creates a Jinja2 environment with the i18n extension loaded:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n}{jinja\PYGZus{}env} \PYG{o}{=} \PYG{n}{Environment}\PYG{p}{(}\PYG{n}{extensions}\PYG{o}{=}\PYG{p}{[}\PYG{l+s}{'}\PYG{l+s}{jinja2.ext.i18n}\PYG{l+s}{'}\PYG{p}{]}\PYG{p}{)}
\end{Verbatim}


\section{i18n Extension}
\label{extensions:i18n-extension}\label{extensions:id1}
\textbf{Import name:} \emph{jinja2.ext.i18n}

Jinja2 currently comes with one extension, the i18n extension.  It can be
used in combination with \href{http://docs.python.org/dev/library/gettext}{gettext} or \href{http://babel.edgewall.org/}{babel}.  If the i18n extension is
enabled Jinja2 provides a \emph{trans} statement that marks the wrapped string as
translatable and calls \emph{gettext}.

After enabling dummy \emph{\_} function that forwards calls to \emph{gettext} is added
to the environment globals.  An internationalized application then has to
provide at least an \emph{gettext} and optoinally a \emph{ngettext} function into the
namespace.  Either globally or for each rendering.


\subsection{Environment Methods}
\label{extensions:environment-methods}
After enabling of the extension the environment provides the following
additional methods:
\index{install\_gettext\_translations() (jinja2.Environment method)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.Environment.install_gettext_translations}\pysiglinewithargsret{\code{jinja2.Environment.}\bfcode{install\_gettext\_translations}}{\emph{translations}, \emph{newstyle=False}}{}
Installs a translation globally for that environment.  The tranlations
object provided must implement at least \emph{ugettext} and \emph{ungettext}.
The \emph{gettext.NullTranslations} and \emph{gettext.GNUTranslations} classes
as well as \href{http://babel.edgewall.org/}{Babel}s \emph{Translations} class are supported.
Changed in version 2.5: newstyle gettext added
\end{fulllineitems}

\index{install\_null\_translations() (jinja2.Environment method)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.Environment.install_null_translations}\pysiglinewithargsret{\code{jinja2.Environment.}\bfcode{install\_null\_translations}}{\emph{newstyle=False}}{}
Install dummy gettext functions.  This is useful if you want to prepare
the application for internationalization but don't want to implement the
full internationalization system yet.
Changed in version 2.5: newstyle gettext added
\end{fulllineitems}

\index{install\_gettext\_callables() (jinja2.Environment method)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.Environment.install_gettext_callables}\pysiglinewithargsret{\code{jinja2.Environment.}\bfcode{install\_gettext\_callables}}{\emph{gettext}, \emph{ngettext}, \emph{newstyle=False}}{}
Installs the given \emph{gettext} and \emph{ngettext} callables into the
environment as globals.  They are supposed to behave exactly like the
standard library's \code{gettext.ugettext()} and
\code{gettext.ungettext()} functions.

If \emph{newstyle} is activated, the callables are wrapped to work like
newstyle callables.  See {\hyperref[extensions:newstyle-gettext]{\emph{Newstyle Gettext}}} for more information.
New in version 2.5.
\end{fulllineitems}

\index{uninstall\_gettext\_translations() (jinja2.Environment method)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.Environment.uninstall_gettext_translations}\pysiglinewithargsret{\code{jinja2.Environment.}\bfcode{uninstall\_gettext\_translations}}{}{}
Uninstall the translations again.

\end{fulllineitems}

\index{extract\_translations() (jinja2.Environment method)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.Environment.extract_translations}\pysiglinewithargsret{\code{jinja2.Environment.}\bfcode{extract\_translations}}{\emph{source}}{}
Extract localizable strings from the given template node or source.

For every string found this function yields a \code{(lineno, function,
message)} tuple, where:
\begin{itemize}
\item {} 
\emph{lineno} is the number of the line on which the string was found,

\item {} 
\emph{function} is the name of the \emph{gettext} function used (if the
string was extracted from embedded Python code), and

\item {} 
\emph{message} is the string itself (a \emph{unicode} object, or a tuple
of \emph{unicode} objects for functions with multiple string arguments).

\end{itemize}

If \href{http://babel.edgewall.org/}{Babel} is installed {\hyperref[integration:babel-integration]{\emph{the babel integration}}}
can be used to extract strings for babel.

\end{fulllineitems}


For a web application that is available in multiple languages but gives all
the users the same language (for example a multilingual forum software
installed for a French community) may load the translations once and add the
translation methods to the environment at environment generation time:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n}{translations} \PYG{o}{=} \PYG{n}{get\PYGZus{}gettext\PYGZus{}translations}\PYG{p}{(}\PYG{p}{)}
\PYG{n}{env} \PYG{o}{=} \PYG{n}{Environment}\PYG{p}{(}\PYG{n}{extensions}\PYG{o}{=}\PYG{p}{[}\PYG{l+s}{'}\PYG{l+s}{jinja2.ext.i18n}\PYG{l+s}{'}\PYG{p}{]}\PYG{p}{)}
\PYG{n}{env}\PYG{o}{.}\PYG{n}{install\PYGZus{}gettext\PYGZus{}translations}\PYG{p}{(}\PYG{n}{translations}\PYG{p}{)}
\end{Verbatim}

The \emph{get\_gettext\_translations} function would return the translator for the
current configuration.  (For example by using \emph{gettext.find})

The usage of the \emph{i18n} extension for template designers is covered as part
{\hyperref[templates:i18n-in-templates]{\emph{of the template documentation}}}.


\subsection{Newstyle Gettext}
\label{extensions:id2}\label{extensions:newstyle-gettext}New in version 2.5.
Starting with version 2.5 you can use newstyle gettext calls.  These are
inspired by trac's internal gettext functions and are fully supported by
the babel extraction tool.  They might not work as expected by other
extraction tools in case you are not using Babel's.

What's the big difference between standard and newstyle gettext calls?  In
general they are less to type and less error prone.  Also if they are used
in an autoescaping environment they better support automatic escaping.
Here some common differences between old and new calls:

standard gettext:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{gettext}\PYG{o}{(}\PYG{l+s+s1}{'Hello World!'}\PYG{o}{)} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}
\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{gettext}\PYG{o}{(}\PYG{l+s+s1}{'Hello \%(name)s!'}\PYG{o}{)}\PYG{o}{\textbar{}}\PYG{n+nf}{format}\PYG{o}{(}\PYG{n+nv}{name}\PYG{o}{=}\PYG{l+s+s1}{'World'}\PYG{o}{)} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}
\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{ngettext}\PYG{o}{(}\PYG{l+s+s1}{'\%(num)d apple'}\PYG{o}{,} \PYG{l+s+s1}{'\%(num)d apples'}\PYG{o}{,} \PYG{n+nv}{apples}\PYG{o}{\textbar{}}\PYG{n+nf}{count}\PYG{o}{)}\PYG{o}{\textbar{}}\PYG{n+nf}{format}\PYG{o}{(}
    \PYG{n+nv}{num}\PYG{o}{=}\PYG{n+nv}{apples}\PYG{o}{\textbar{}}\PYG{n+nf}{count}
\PYG{o}{)}\PYG{c+cp}{\PYGZcb{}\PYGZcb{}}
\end{Verbatim}

newstyle gettext looks like this instead:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{gettext}\PYG{o}{(}\PYG{l+s+s1}{'Hello World!'}\PYG{o}{)} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}
\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{gettext}\PYG{o}{(}\PYG{l+s+s1}{'Hello \%(name)s!'}\PYG{o}{,} \PYG{n+nv}{name}\PYG{o}{=}\PYG{l+s+s1}{'World'}\PYG{o}{)} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}
\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{ngettext}\PYG{o}{(}\PYG{l+s+s1}{'\%(num)d apple'}\PYG{o}{,} \PYG{l+s+s1}{'\%(num)d apples'}\PYG{o}{,} \PYG{n+nv}{apples}\PYG{o}{\textbar{}}\PYG{n+nf}{count}\PYG{o}{)} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}
\end{Verbatim}

The advantages of newstyle gettext is that you have less to type and that
named placeholders become mandatory.  The latter sounds like a
disadvantage but solves a lot of troubles translators are often facing
when they are unable to switch the positions of two placeholder.  With
newstyle gettext, all format strings look the same.

Furthermore with newstyle gettext, string formatting is also used if no
placeholders are used which makes all strings behave exactly the same.
Last but not least are newstyle gettext calls able to properly mark
strings for autoescaping which solves lots of escaping related issues many
templates are experiencing over time when using autoescaping.


\section{Expression Statement}
\label{extensions:expression-statement}
\textbf{Import name:} \emph{jinja2.ext.do}

The ``do'' aka expression-statement extension adds a simple \emph{do} tag to the
template engine that works like a variable expression but ignores the
return value.


\section{Loop Controls}
\label{extensions:loop-controls}\label{extensions:loopcontrols-extension}
\textbf{Import name:} \emph{jinja2.ext.loopcontrols}

This extension adds support for \emph{break} and \emph{continue} in loops.  After
enabling Jinja2 provides those two keywords which work exactly like in
Python.


\section{With Statement}
\label{extensions:with-statement}\label{extensions:with-extension}
\textbf{Import name:} \emph{jinja2.ext.with\_}
New in version 2.3.
This extension adds support for the with keyword.  Using this keyword it
is possible to enforce a nested scope in a template.  Variables can be
declared directly in the opening block of the with statement or using a
standard \emph{set} statement directly within.


\section{Autoescape Extension}
\label{extensions:autoescape-extension}\label{extensions:id3}
\textbf{Import name:} \emph{jinja2.ext.autoescape}
New in version 2.4.
The autoescape extension allows you to toggle the autoescape feature from
within the template.  If the environment's \code{autoescape}
setting is set to \emph{False} it can be activated, if it's \emph{True} it can be
deactivated.  The setting overriding is scoped.


\section{Writing Extensions}
\label{extensions:writing-extensions}\label{extensions:id4}\label{extensions:module-jinja2.ext}\index{jinja2.ext (module)}
By writing extensions you can add custom tags to Jinja2.  This is a non trival
task and usually not needed as the default tags and expressions cover all
common use cases.  The i18n extension is a good example of why extensions are
useful, another one would be fragment caching.

When writing extensions you have to keep in mind that you are working with the
Jinja2 template compiler which does not validate the node tree you are possing
to it.  If the AST is malformed you will get all kinds of compiler or runtime
errors that are horrible to debug.  Always make sure you are using the nodes
you create correctly.  The API documentation below shows which nodes exist and
how to use them.


\subsection{Example Extension}
\label{extensions:example-extension}
The following example implements a \emph{cache} tag for Jinja2 by using the
\href{http://werkzeug.pocoo.org/}{Werkzeug} caching contrib module:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{k+kn}{from} \PYG{n+nn}{jinja2} \PYG{k+kn}{import} \PYG{n}{nodes}
\PYG{k+kn}{from} \PYG{n+nn}{jinja2.ext} \PYG{k+kn}{import} \PYG{n}{Extension}


\PYG{k}{class} \PYG{n+nc}{FragmentCacheExtension}\PYG{p}{(}\PYG{n}{Extension}\PYG{p}{)}\PYG{p}{:}
    \PYG{c}{\# a set of names that trigger the extension.}
    \PYG{n}{tags} \PYG{o}{=} \PYG{n+nb}{set}\PYG{p}{(}\PYG{p}{[}\PYG{l+s}{'}\PYG{l+s}{cache}\PYG{l+s}{'}\PYG{p}{]}\PYG{p}{)}

    \PYG{k}{def} \PYG{n+nf}{\PYGZus{}\PYGZus{}init\PYGZus{}\PYGZus{}}\PYG{p}{(}\PYG{n+nb+bp}{self}\PYG{p}{,} \PYG{n}{environment}\PYG{p}{)}\PYG{p}{:}
        \PYG{n+nb}{super}\PYG{p}{(}\PYG{n}{FragmentCacheExtension}\PYG{p}{,} \PYG{n+nb+bp}{self}\PYG{p}{)}\PYG{o}{.}\PYG{n}{\PYGZus{}\PYGZus{}init\PYGZus{}\PYGZus{}}\PYG{p}{(}\PYG{n}{environment}\PYG{p}{)}

        \PYG{c}{\# add the defaults to the environment}
        \PYG{n}{environment}\PYG{o}{.}\PYG{n}{extend}\PYG{p}{(}
            \PYG{n}{fragment\PYGZus{}cache\PYGZus{}prefix}\PYG{o}{=}\PYG{l+s}{'}\PYG{l+s}{'}\PYG{p}{,}
            \PYG{n}{fragment\PYGZus{}cache}\PYG{o}{=}\PYG{n+nb+bp}{None}
        \PYG{p}{)}

    \PYG{k}{def} \PYG{n+nf}{parse}\PYG{p}{(}\PYG{n+nb+bp}{self}\PYG{p}{,} \PYG{n}{parser}\PYG{p}{)}\PYG{p}{:}
        \PYG{c}{\# the first token is the token that started the tag.  In our case}
        \PYG{c}{\# we only listen to {}`{}`'cache'{}`{}` so this will be a name token with}
        \PYG{c}{\# {}`cache{}` as value.  We get the line number so that we can give}
        \PYG{c}{\# that line number to the nodes we create by hand.}
        \PYG{n}{lineno} \PYG{o}{=} \PYG{n}{parser}\PYG{o}{.}\PYG{n}{stream}\PYG{o}{.}\PYG{n}{next}\PYG{p}{(}\PYG{p}{)}\PYG{o}{.}\PYG{n}{lineno}

        \PYG{c}{\# now we parse a single expression that is used as cache key.}
        \PYG{n}{args} \PYG{o}{=} \PYG{p}{[}\PYG{n}{parser}\PYG{o}{.}\PYG{n}{parse\PYGZus{}expression}\PYG{p}{(}\PYG{p}{)}\PYG{p}{]}

        \PYG{c}{\# if there is a comma, the user provided a timeout.  If not use}
        \PYG{c}{\# None as second parameter.}
        \PYG{k}{if} \PYG{n}{parser}\PYG{o}{.}\PYG{n}{stream}\PYG{o}{.}\PYG{n}{skip\PYGZus{}if}\PYG{p}{(}\PYG{l+s}{'}\PYG{l+s}{comma}\PYG{l+s}{'}\PYG{p}{)}\PYG{p}{:}
            \PYG{n}{args}\PYG{o}{.}\PYG{n}{append}\PYG{p}{(}\PYG{n}{parser}\PYG{o}{.}\PYG{n}{parse\PYGZus{}expression}\PYG{p}{(}\PYG{p}{)}\PYG{p}{)}
        \PYG{k}{else}\PYG{p}{:}
            \PYG{n}{args}\PYG{o}{.}\PYG{n}{append}\PYG{p}{(}\PYG{n}{nodes}\PYG{o}{.}\PYG{n}{Const}\PYG{p}{(}\PYG{n+nb+bp}{None}\PYG{p}{)}\PYG{p}{)}

        \PYG{c}{\# now we parse the body of the cache block up to {}`endcache{}` and}
        \PYG{c}{\# drop the needle (which would always be {}`endcache{}` in that case)}
        \PYG{n}{body} \PYG{o}{=} \PYG{n}{parser}\PYG{o}{.}\PYG{n}{parse\PYGZus{}statements}\PYG{p}{(}\PYG{p}{[}\PYG{l+s}{'}\PYG{l+s}{name:endcache}\PYG{l+s}{'}\PYG{p}{]}\PYG{p}{,} \PYG{n}{drop\PYGZus{}needle}\PYG{o}{=}\PYG{n+nb+bp}{True}\PYG{p}{)}

        \PYG{c}{\# now return a {}`CallBlock{}` node that calls our \PYGZus{}cache\PYGZus{}support}
        \PYG{c}{\# helper method on this extension.}
        \PYG{k}{return} \PYG{n}{nodes}\PYG{o}{.}\PYG{n}{CallBlock}\PYG{p}{(}\PYG{n+nb+bp}{self}\PYG{o}{.}\PYG{n}{call\PYGZus{}method}\PYG{p}{(}\PYG{l+s}{'}\PYG{l+s}{\PYGZus{}cache\PYGZus{}support}\PYG{l+s}{'}\PYG{p}{,} \PYG{n}{args}\PYG{p}{)}\PYG{p}{,}
                               \PYG{p}{[}\PYG{p}{]}\PYG{p}{,} \PYG{p}{[}\PYG{p}{]}\PYG{p}{,} \PYG{n}{body}\PYG{p}{)}\PYG{o}{.}\PYG{n}{set\PYGZus{}lineno}\PYG{p}{(}\PYG{n}{lineno}\PYG{p}{)}

    \PYG{k}{def} \PYG{n+nf}{\PYGZus{}cache\PYGZus{}support}\PYG{p}{(}\PYG{n+nb+bp}{self}\PYG{p}{,} \PYG{n}{name}\PYG{p}{,} \PYG{n}{timeout}\PYG{p}{,} \PYG{n}{caller}\PYG{p}{)}\PYG{p}{:}
        \PYG{l+s+sd}{"""Helper callback."""}
        \PYG{n}{key} \PYG{o}{=} \PYG{n+nb+bp}{self}\PYG{o}{.}\PYG{n}{environment}\PYG{o}{.}\PYG{n}{fragment\PYGZus{}cache\PYGZus{}prefix} \PYG{o}{+} \PYG{n}{name}

        \PYG{c}{\# try to load the block from the cache}
        \PYG{c}{\# if there is no fragment in the cache, render it and store}
        \PYG{c}{\# it in the cache.}
        \PYG{n}{rv} \PYG{o}{=} \PYG{n+nb+bp}{self}\PYG{o}{.}\PYG{n}{environment}\PYG{o}{.}\PYG{n}{fragment\PYGZus{}cache}\PYG{o}{.}\PYG{n}{get}\PYG{p}{(}\PYG{n}{key}\PYG{p}{)}
        \PYG{k}{if} \PYG{n}{rv} \PYG{o+ow}{is} \PYG{o+ow}{not} \PYG{n+nb+bp}{None}\PYG{p}{:}
            \PYG{k}{return} \PYG{n}{rv}
        \PYG{n}{rv} \PYG{o}{=} \PYG{n}{caller}\PYG{p}{(}\PYG{p}{)}
        \PYG{n+nb+bp}{self}\PYG{o}{.}\PYG{n}{environment}\PYG{o}{.}\PYG{n}{fragment\PYGZus{}cache}\PYG{o}{.}\PYG{n}{add}\PYG{p}{(}\PYG{n}{key}\PYG{p}{,} \PYG{n}{rv}\PYG{p}{,} \PYG{n}{timeout}\PYG{p}{)}
        \PYG{k}{return} \PYG{n}{rv}
\end{Verbatim}

And here is how you use it in an environment:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{k+kn}{from} \PYG{n+nn}{jinja2} \PYG{k+kn}{import} \PYG{n}{Environment}
\PYG{k+kn}{from} \PYG{n+nn}{werkzeug.contrib.cache} \PYG{k+kn}{import} \PYG{n}{SimpleCache}

\PYG{n}{env} \PYG{o}{=} \PYG{n}{Environment}\PYG{p}{(}\PYG{n}{extensions}\PYG{o}{=}\PYG{p}{[}\PYG{n}{FragmentCacheExtension}\PYG{p}{]}\PYG{p}{)}
\PYG{n}{env}\PYG{o}{.}\PYG{n}{fragment\PYGZus{}cache} \PYG{o}{=} \PYG{n}{SimpleCache}\PYG{p}{(}\PYG{p}{)}
\end{Verbatim}

Inside the template it's then possible to mark blocks as cacheable.  The
following example caches a sidebar for 300 seconds:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{cache} \PYG{l+s+s1}{'sidebar'}\PYG{o}{,} \PYG{l+m}{3}\PYG{l+m}{0}\PYG{l+m}{0} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{n+nt}{\textless{}div} \PYG{n+na}{class=}\PYG{l+s}{"sidebar"}\PYG{n+nt}{\textgreater{}}
    ...
\PYG{n+nt}{\textless{}/div\textgreater{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endcache} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}


\subsection{Extension API}
\label{extensions:extension-api}\label{extensions:werkzeug}
Extensions always have to extend the {\hyperref[extensions:jinja2.ext.Extension]{\code{jinja2.ext.Extension}}} class:
\index{Extension (class in jinja2.ext)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.ext.Extension}\pysiglinewithargsret{\strong{class }\code{jinja2.ext.}\bfcode{Extension}}{\emph{environment}}{}
Extensions can be used to add extra functionality to the Jinja template
system at the parser level.  Custom extensions are bound to an environment
but may not store environment specific data on \emph{self}.  The reason for
this is that an extension can be bound to another environment (for
overlays) by creating a copy and reassigning the \emph{environment} attribute.

As extensions are created by the environment they cannot accept any
arguments for configuration.  One may want to work around that by using
a factory function, but that is not possible as extensions are identified
by their import name.  The correct way to configure the extension is
storing the configuration values on the environment.  Because this way the
environment ends up acting as central configuration storage the
attributes may clash which is why extensions have to ensure that the names
they choose for configuration are not too generic.  \code{prefix} for example
is a terrible name, \code{fragment\_cache\_prefix} on the other hand is a good
name as includes the name of the extension (fragment cache).
\index{identifier (jinja2.ext.Extension attribute)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.ext.Extension.identifier}\pysigline{\bfcode{identifier}}{}
The identifier of the extension.  This is always the true import name
of the extension class and must not be changed.

\end{fulllineitems}

\index{tags (jinja2.ext.Extension attribute)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.ext.Extension.tags}\pysigline{\bfcode{tags}}{}
If the extension implements custom tags this is a set of tag names
the extension is listening for.

\end{fulllineitems}

\index{preprocess() (jinja2.ext.Extension method)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.ext.Extension.preprocess}\pysiglinewithargsret{\bfcode{preprocess}}{\emph{source}, \emph{name}, \emph{filename=None}}{}
This method is called before the actual lexing and can be used to
preprocess the source.  The \emph{filename} is optional.  The return value
must be the preprocessed source.

\end{fulllineitems}

\index{filter\_stream() (jinja2.ext.Extension method)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.ext.Extension.filter_stream}\pysiglinewithargsret{\bfcode{filter\_stream}}{\emph{stream}}{}
It's passed a {\hyperref[extensions:jinja2.lexer.TokenStream]{\code{TokenStream}}} that can be used
to filter tokens returned.  This method has to return an iterable of
{\hyperref[extensions:jinja2.lexer.Token]{\code{Token}}}s, but it doesn't have to return a
{\hyperref[extensions:jinja2.lexer.TokenStream]{\code{TokenStream}}}.

In the \emph{ext} folder of the Jinja2 source distribution there is a file
called \emph{inlinegettext.py} which implements a filter that utilizes this
method.

\end{fulllineitems}

\index{parse() (jinja2.ext.Extension method)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.ext.Extension.parse}\pysiglinewithargsret{\bfcode{parse}}{\emph{parser}}{}
If any of the {\hyperref[extensions:jinja2.ext.Extension.tags]{\code{tags}}} matched this method is called with the
parser as first argument.  The token the parser stream is pointing at
is the name token that matched.  This method has to return one or a
list of multiple nodes.

\end{fulllineitems}

\index{attr() (jinja2.ext.Extension method)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.ext.Extension.attr}\pysiglinewithargsret{\bfcode{attr}}{\emph{name}, \emph{lineno=None}}{}
Return an attribute node for the current extension.  This is useful
to pass constants on extensions to generated template code:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nb+bp}{self}\PYG{o}{.}\PYG{n}{attr}\PYG{p}{(}\PYG{l+s}{'}\PYG{l+s}{\PYGZus{}my\PYGZus{}attribute}\PYG{l+s}{'}\PYG{p}{,} \PYG{n}{lineno}\PYG{o}{=}\PYG{n}{lineno}\PYG{p}{)}
\end{Verbatim}

\end{fulllineitems}

\index{call\_method() (jinja2.ext.Extension method)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.ext.Extension.call_method}\pysiglinewithargsret{\bfcode{call\_method}}{\emph{name}, \emph{args=None}, \emph{kwargs=None}, \emph{dyn\_args=None}, \emph{dyn\_kwargs=None}, \emph{lineno=None}}{}
Call a method of the extension.  This is a shortcut for
{\hyperref[templates:attr]{\code{attr()}}} + {\hyperref[extensions:jinja2.nodes.Call]{\code{jinja2.nodes.Call}}}.

\end{fulllineitems}


\end{fulllineitems}



\subsection{Parser API}
\label{extensions:parser-api}
The parser passed to {\hyperref[extensions:jinja2.ext.Extension.parse]{\code{Extension.parse()}}} provides ways to parse
expressions of different types.  The following methods may be used by
extensions:
\index{Parser (class in jinja2.parser)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.parser.Parser}\pysiglinewithargsret{\strong{class }\code{jinja2.parser.}\bfcode{Parser}}{\emph{environment}, \emph{source}, \emph{name=None}, \emph{filename=None}, \emph{state=None}}{}
This is the central parsing class Jinja2 uses.  It's passed to
extensions and can be used to parse expressions or statements.
\index{filename (jinja2.ext.Parser attribute)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.ext.Parser.filename}\pysigline{\bfcode{filename}}{}
The filename of the template the parser processes.  This is \textbf{not}
the load name of the template.  For the load name see {\hyperref[extensions:jinja2.ext.Parser.name]{\code{name}}}.
For templates that were not loaded form the file system this is
\emph{None}.

\end{fulllineitems}

\index{name (jinja2.ext.Parser attribute)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.ext.Parser.name}\pysigline{\bfcode{name}}{}
The load name of the template.

\end{fulllineitems}

\index{stream (jinja2.ext.Parser attribute)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.ext.Parser.stream}\pysigline{\bfcode{stream}}{}
The current {\hyperref[extensions:jinja2.lexer.TokenStream]{\code{TokenStream}}}

\end{fulllineitems}

\index{parse\_expression() (jinja2.parser.Parser method)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.parser.Parser.parse_expression}\pysiglinewithargsret{\bfcode{parse\_expression}}{\emph{with\_condexpr=True}}{}
Parse an expression.  Per default all expressions are parsed, if
the optional \emph{with\_condexpr} parameter is set to \emph{False} conditional
expressions are not parsed.

\end{fulllineitems}

\index{parse\_tuple() (jinja2.parser.Parser method)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.parser.Parser.parse_tuple}\pysiglinewithargsret{\bfcode{parse\_tuple}}{\emph{simplified=False}, \emph{with\_condexpr=True}, \emph{extra\_end\_rules=None}, \emph{explicit\_parentheses=False}}{}
Works like \emph{parse\_expression} but if multiple expressions are
delimited by a comma a {\hyperref[extensions:jinja2.nodes.Tuple]{\code{Tuple}}} node is created.
This method could also return a regular expression instead of a tuple
if no commas where found.

The default parsing mode is a full tuple.  If \emph{simplified} is \emph{True}
only names and literals are parsed.  The \emph{no\_condexpr} parameter is
forwarded to \code{parse\_expression()}.

Because tuples do not require delimiters and may end in a bogus comma
an extra hint is needed that marks the end of a tuple.  For example
for loops support tuples between \emph{for} and \emph{in}.  In that case the
\emph{extra\_end\_rules} is set to \code{{[}'name:in'{]}}.

\emph{explicit\_parentheses} is true if the parsing was triggered by an
expression in parentheses.  This is used to figure out if an empty
tuple is a valid expression or not.

\end{fulllineitems}

\index{parse\_assign\_target() (jinja2.parser.Parser method)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.parser.Parser.parse_assign_target}\pysiglinewithargsret{\bfcode{parse\_assign\_target}}{\emph{with\_tuple=True}, \emph{name\_only=False}, \emph{extra\_end\_rules=None}}{}
Parse an assignment target.  As Jinja2 allows assignments to
tuples, this function can parse all allowed assignment targets.  Per
default assignments to tuples are parsed, that can be disable however
by setting \emph{with\_tuple} to \emph{False}.  If only assignments to names are
wanted \emph{name\_only} can be set to \emph{True}.  The \emph{extra\_end\_rules}
parameter is forwarded to the tuple parsing function.

\end{fulllineitems}

\index{parse\_statements() (jinja2.parser.Parser method)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.parser.Parser.parse_statements}\pysiglinewithargsret{\bfcode{parse\_statements}}{\emph{end\_tokens}, \emph{drop\_needle=False}}{}
Parse multiple statements into a list until one of the end tokens
is reached.  This is used to parse the body of statements as it also
parses template data if appropriate.  The parser checks first if the
current token is a colon and skips it if there is one.  Then it checks
for the block end and parses until if one of the \emph{end\_tokens} is
reached.  Per default the active token in the stream at the end of
the call is the matched end token.  If this is not wanted \emph{drop\_needle}
can be set to \emph{True} and the end token is removed.

\end{fulllineitems}

\index{free\_identifier() (jinja2.parser.Parser method)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.parser.Parser.free_identifier}\pysiglinewithargsret{\bfcode{free\_identifier}}{\emph{lineno=None}}{}
Return a new free identifier as {\hyperref[extensions:jinja2.nodes.InternalName]{\code{InternalName}}}.

\end{fulllineitems}

\index{fail() (jinja2.parser.Parser method)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.parser.Parser.fail}\pysiglinewithargsret{\bfcode{fail}}{\emph{msg}, \emph{lineno=None}, \emph{exc=\textless{}class `jinja2.exceptions.TemplateSyntaxError'\textgreater{}}}{}
Convenience method that raises \emph{exc} with the message, passed
line number or last line number as well as the current name and
filename.

\end{fulllineitems}


\end{fulllineitems}

\index{TokenStream (class in jinja2.lexer)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.lexer.TokenStream}\pysiglinewithargsret{\strong{class }\code{jinja2.lexer.}\bfcode{TokenStream}}{\emph{generator}, \emph{name}, \emph{filename}}{}
A token stream is an iterable that yields \code{Token}s.  The
parser however does not iterate over it but calls \code{next()} to go
one token ahead.  The current active token is stored as {\hyperref[extensions:jinja2.ext.TokenStream.current]{\code{current}}}.
\index{current (jinja2.ext.TokenStream attribute)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.ext.TokenStream.current}\pysigline{\bfcode{current}}{}
The current {\hyperref[extensions:jinja2.lexer.Token]{\code{Token}}}.

\end{fulllineitems}

\index{push() (jinja2.lexer.TokenStream method)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.lexer.TokenStream.push}\pysiglinewithargsret{\bfcode{push}}{\emph{token}}{}
Push a token back to the stream.

\end{fulllineitems}

\index{look() (jinja2.lexer.TokenStream method)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.lexer.TokenStream.look}\pysiglinewithargsret{\bfcode{look}}{}{}
Look at the next token.

\end{fulllineitems}

\index{eos (jinja2.lexer.TokenStream attribute)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.lexer.TokenStream.eos}\pysigline{\bfcode{eos}}{}
Are we at the end of the stream?

\end{fulllineitems}

\index{skip() (jinja2.lexer.TokenStream method)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.lexer.TokenStream.skip}\pysiglinewithargsret{\bfcode{skip}}{\emph{n=1}}{}
Got n tokens ahead.

\end{fulllineitems}

\index{next() (jinja2.lexer.TokenStream method)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.lexer.TokenStream.next}\pysiglinewithargsret{\bfcode{next}}{}{}
Go one token ahead and return the old one

\end{fulllineitems}

\index{next\_if() (jinja2.lexer.TokenStream method)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.lexer.TokenStream.next_if}\pysiglinewithargsret{\bfcode{next\_if}}{\emph{expr}}{}
Perform the token test and return the token if it matched.
Otherwise the return value is \emph{None}.

\end{fulllineitems}

\index{skip\_if() (jinja2.lexer.TokenStream method)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.lexer.TokenStream.skip_if}\pysiglinewithargsret{\bfcode{skip\_if}}{\emph{expr}}{}
Like \code{next\_if()} but only returns \emph{True} or \emph{False}.

\end{fulllineitems}

\index{expect() (jinja2.lexer.TokenStream method)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.lexer.TokenStream.expect}\pysiglinewithargsret{\bfcode{expect}}{\emph{expr}}{}
Expect a given token type and return it.  This accepts the same
argument as {\hyperref[extensions:jinja2.lexer.Token.test]{\code{jinja2.lexer.Token.test()}}}.

\end{fulllineitems}


\end{fulllineitems}

\index{Token (class in jinja2.lexer)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.lexer.Token}\pysigline{\strong{class }\code{jinja2.lexer.}\bfcode{Token}}{}
Token class.
\index{lineno (jinja2.ext.Token attribute)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.ext.Token.lineno}\pysigline{\bfcode{lineno}}{}
The line number of the token

\end{fulllineitems}

\index{type (jinja2.ext.Token attribute)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.ext.Token.type}\pysigline{\bfcode{type}}{}
The type of the token.  This string is interned so you may compare
it with arbitrary strings using the \emph{is} operator.

\end{fulllineitems}

\index{value (jinja2.ext.Token attribute)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.ext.Token.value}\pysigline{\bfcode{value}}{}
The value of the token.

\end{fulllineitems}

\index{test() (jinja2.lexer.Token method)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.lexer.Token.test}\pysiglinewithargsret{\bfcode{test}}{\emph{expr}}{}
Test a token against a token expression.  This can either be a
token type or \code{'token\_type:token\_value'}.  This can only test
against string values and types.

\end{fulllineitems}

\index{test\_any() (jinja2.lexer.Token method)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.lexer.Token.test_any}\pysiglinewithargsret{\bfcode{test\_any}}{\emph{*iterable}}{}
Test against multiple token expressions.

\end{fulllineitems}


\end{fulllineitems}


There is also a utility function in the lexer module that can count newline
characters in strings:
\index{count\_newlines() (in module jinja2.lexer)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.lexer.count_newlines}\pysiglinewithargsret{\code{jinja2.lexer.}\bfcode{count\_newlines}}{\emph{value}}{}
Count the number of newline characters in the string.  This is
useful for extensions that filter a stream.

\end{fulllineitems}



\subsection{AST}
\label{extensions:ast}
The AST (Abstract Syntax Tree) is used to represent a template after parsing.
It's build of nodes that the compiler then converts into executable Python
code objects.  Extensions that provide custom statements can return nodes to
execute custom Python code.

The list below describes all nodes that are currently available.  The AST may
change between Jinja2 versions but will stay backwards compatible.

For more information have a look at the repr of {\hyperref[api:jinja2.Environment.parse]{\code{jinja2.Environment.parse()}}}.
\phantomsection\label{extensions:module-jinja2.nodes}\index{jinja2.nodes (module)}\index{Node (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Node}\pysigline{\strong{class }\code{jinja2.nodes.}\bfcode{Node}}{}
Baseclass for all Jinja2 nodes.  There are a number of nodes available
of different types.  There are three major types:
\begin{itemize}
\item {} 
{\hyperref[extensions:jinja2.nodes.Stmt]{\code{Stmt}}}: statements

\item {} 
{\hyperref[extensions:jinja2.nodes.Expr]{\code{Expr}}}: expressions

\item {} 
{\hyperref[extensions:jinja2.nodes.Helper]{\code{Helper}}}: helper nodes

\item {} 
{\hyperref[extensions:jinja2.nodes.Template]{\code{Template}}}: the outermost wrapper node

\end{itemize}

All nodes have fields and attributes.  Fields may be other nodes, lists,
or arbitrary values.  Fields are passed to the constructor as regular
positional arguments, attributes as keyword arguments.  Each node has
two attributes: \emph{lineno} (the line number of the node) and \emph{environment}.
The \emph{environment} attribute is set at the end of the parsing process for
all nodes automatically.
\index{find() (jinja2.nodes.Node method)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Node.find}\pysiglinewithargsret{\bfcode{find}}{\emph{node\_type}}{}
Find the first node of a given type.  If no such node exists the
return value is \emph{None}.

\end{fulllineitems}

\index{find\_all() (jinja2.nodes.Node method)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Node.find_all}\pysiglinewithargsret{\bfcode{find\_all}}{\emph{node\_type}}{}
Find all the nodes of a given type.  If the type is a tuple,
the check is performed for any of the tuple items.

\end{fulllineitems}

\index{iter\_child\_nodes() (jinja2.nodes.Node method)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Node.iter_child_nodes}\pysiglinewithargsret{\bfcode{iter\_child\_nodes}}{\emph{exclude=None}, \emph{only=None}}{}
Iterates over all direct child nodes of the node.  This iterates
over all fields and yields the values of they are nodes.  If the value
of a field is a list all the nodes in that list are returned.

\end{fulllineitems}

\index{iter\_fields() (jinja2.nodes.Node method)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Node.iter_fields}\pysiglinewithargsret{\bfcode{iter\_fields}}{\emph{exclude=None}, \emph{only=None}}{}
This method iterates over all fields that are defined and yields
\code{(key, value)} tuples.  Per default all fields are returned, but
it's possible to limit that to some fields by providing the \emph{only}
parameter or to exclude some using the \emph{exclude} parameter.  Both
should be sets or tuples of field names.

\end{fulllineitems}

\index{set\_ctx() (jinja2.nodes.Node method)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Node.set_ctx}\pysiglinewithargsret{\bfcode{set\_ctx}}{\emph{ctx}}{}
Reset the context of a node and all child nodes.  Per default the
parser will all generate nodes that have a `load' context as it's the
most common one.  This method is used in the parser to set assignment
targets and other nodes to a store context.

\end{fulllineitems}

\index{set\_environment() (jinja2.nodes.Node method)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Node.set_environment}\pysiglinewithargsret{\bfcode{set\_environment}}{\emph{environment}}{}
Set the environment for all nodes.

\end{fulllineitems}

\index{set\_lineno() (jinja2.nodes.Node method)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Node.set_lineno}\pysiglinewithargsret{\bfcode{set\_lineno}}{\emph{lineno}, \emph{override=False}}{}
Set the line numbers of the node and children.

\end{fulllineitems}


\end{fulllineitems}

\index{Expr (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Expr}\pysigline{\strong{class }\code{jinja2.nodes.}\bfcode{Expr}}{}
Baseclass for all expressions.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.Node]{\code{Node}}}

\end{description}\end{quote}
\index{as\_const() (jinja2.nodes.Expr method)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Expr.as_const}\pysiglinewithargsret{\bfcode{as\_const}}{\emph{eval\_ctx=None}}{}
Return the value of the expression as constant or raise
{\hyperref[extensions:jinja2.nodes.Impossible]{\code{Impossible}}} if this was not possible.

An {\hyperref[api:jinja2.nodes.EvalContext]{\code{EvalContext}}} can be provided, if none is given
a default context is created which requires the nodes to have
an attached environment.
Changed in version 2.4: the \emph{eval\_ctx} parameter was added.
\end{fulllineitems}

\index{can\_assign() (jinja2.nodes.Expr method)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Expr.can_assign}\pysiglinewithargsret{\bfcode{can\_assign}}{}{}
Check if it's possible to assign something to this node.

\end{fulllineitems}


\end{fulllineitems}

\index{BinExpr (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.BinExpr}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{BinExpr}}{\emph{left}, \emph{right}}{}
Baseclass for all binary expressions.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.Expr]{\code{Expr}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{Add (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Add}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{Add}}{\emph{left}, \emph{right}}{}
Add the left to the right node.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.BinExpr]{\code{BinExpr}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{And (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.And}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{And}}{\emph{left}, \emph{right}}{}
Short circuited AND.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.BinExpr]{\code{BinExpr}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{Div (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Div}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{Div}}{\emph{left}, \emph{right}}{}
Divides the left by the right node.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.BinExpr]{\code{BinExpr}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{FloorDiv (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.FloorDiv}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{FloorDiv}}{\emph{left}, \emph{right}}{}
Divides the left by the right node and truncates conver the
result into an integer by truncating.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.BinExpr]{\code{BinExpr}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{Mod (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Mod}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{Mod}}{\emph{left}, \emph{right}}{}
Left modulo right.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.BinExpr]{\code{BinExpr}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{Mul (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Mul}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{Mul}}{\emph{left}, \emph{right}}{}
Multiplies the left with the right node.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.BinExpr]{\code{BinExpr}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{Or (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Or}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{Or}}{\emph{left}, \emph{right}}{}
Short circuited OR.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.BinExpr]{\code{BinExpr}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{Pow (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Pow}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{Pow}}{\emph{left}, \emph{right}}{}
Left to the power of right.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.BinExpr]{\code{BinExpr}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{Sub (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Sub}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{Sub}}{\emph{left}, \emph{right}}{}
Substract the right from the left node.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.BinExpr]{\code{BinExpr}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{Call (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Call}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{Call}}{\emph{node}, \emph{args}, \emph{kwargs}, \emph{dyn\_args}, \emph{dyn\_kwargs}}{}
Calls an expression.  \emph{args} is a list of arguments, \emph{kwargs} a list
of keyword arguments (list of {\hyperref[extensions:jinja2.nodes.Keyword]{\code{Keyword}}} nodes), and \emph{dyn\_args}
and \emph{dyn\_kwargs} has to be either \emph{None} or a node that is used as
node for dynamic positional (\code{*args}) or keyword (\code{**kwargs})
arguments.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.Expr]{\code{Expr}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{Compare (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Compare}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{Compare}}{\emph{expr}, \emph{ops}}{}
Compares an expression with some other expressions.  \emph{ops} must be a
list of {\hyperref[extensions:jinja2.nodes.Operand]{\code{Operand}}}s.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.Expr]{\code{Expr}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{Concat (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Concat}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{Concat}}{\emph{nodes}}{}
Concatenates the list of expressions provided after converting them to
unicode.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.Expr]{\code{Expr}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{CondExpr (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.CondExpr}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{CondExpr}}{\emph{test}, \emph{expr1}, \emph{expr2}}{}
A conditional expression (inline if expression).  (\code{\{\{
foo if bar else baz \}\}})
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.Expr]{\code{Expr}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{ContextReference (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.ContextReference}\pysigline{\strong{class }\code{jinja2.nodes.}\bfcode{ContextReference}}{}
Returns the current template context.  It can be used like a
{\hyperref[extensions:jinja2.nodes.Name]{\code{Name}}} node, with a \code{'load'} ctx and will return the
current {\hyperref[api:jinja2.runtime.Context]{\code{Context}}} object.

Here an example that assigns the current template name to a
variable named \emph{foo}:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n}{Assign}\PYG{p}{(}\PYG{n}{Name}\PYG{p}{(}\PYG{l+s}{'}\PYG{l+s}{foo}\PYG{l+s}{'}\PYG{p}{,} \PYG{n}{ctx}\PYG{o}{=}\PYG{l+s}{'}\PYG{l+s}{store}\PYG{l+s}{'}\PYG{p}{)}\PYG{p}{,}
       \PYG{n}{Getattr}\PYG{p}{(}\PYG{n}{ContextReference}\PYG{p}{(}\PYG{p}{)}\PYG{p}{,} \PYG{l+s}{'}\PYG{l+s}{name}\PYG{l+s}{'}\PYG{p}{)}\PYG{p}{)}
\end{Verbatim}
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.Expr]{\code{Expr}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{EnvironmentAttribute (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.EnvironmentAttribute}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{EnvironmentAttribute}}{\emph{name}}{}
Loads an attribute from the environment object.  This is useful for
extensions that want to call a callback stored on the environment.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.Expr]{\code{Expr}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{ExtensionAttribute (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.ExtensionAttribute}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{ExtensionAttribute}}{\emph{identifier}, \emph{name}}{}
Returns the attribute of an extension bound to the environment.
The identifier is the identifier of the \code{Extension}.

This node is usually constructed by calling the
{\hyperref[extensions:jinja2.ext.Extension.attr]{\code{attr()}}} method on an extension.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.Expr]{\code{Expr}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{Filter (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Filter}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{Filter}}{\emph{node}, \emph{name}, \emph{args}, \emph{kwargs}, \emph{dyn\_args}, \emph{dyn\_kwargs}}{}
This node applies a filter on an expression.  \emph{name} is the name of
the filter, the rest of the fields are the same as for {\hyperref[extensions:jinja2.nodes.Call]{\code{Call}}}.

If the \emph{node} of a filter is \emph{None} the contents of the last buffer are
filtered.  Buffers are created by macros and filter blocks.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.Expr]{\code{Expr}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{Getattr (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Getattr}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{Getattr}}{\emph{node}, \emph{attr}, \emph{ctx}}{}
Get an attribute or item from an expression that is a ascii-only
bytestring and prefer the attribute.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.Expr]{\code{Expr}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{Getitem (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Getitem}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{Getitem}}{\emph{node}, \emph{arg}, \emph{ctx}}{}
Get an attribute or item from an expression and prefer the item.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.Expr]{\code{Expr}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{ImportedName (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.ImportedName}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{ImportedName}}{\emph{importname}}{}
If created with an import name the import name is returned on node
access.  For example \code{ImportedName('cgi.escape')} returns the \emph{escape}
function from the cgi module on evaluation.  Imports are optimized by the
compiler so there is no need to assign them to local variables.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.Expr]{\code{Expr}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{InternalName (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.InternalName}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{InternalName}}{\emph{name}}{}
An internal name in the compiler.  You cannot create these nodes
yourself but the parser provides a
{\hyperref[extensions:jinja2.parser.Parser.free_identifier]{\code{free\_identifier()}}} method that creates
a new identifier for you.  This identifier is not available from the
template and is not threated specially by the compiler.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.Expr]{\code{Expr}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{Literal (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Literal}\pysigline{\strong{class }\code{jinja2.nodes.}\bfcode{Literal}}{}
Baseclass for literals.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.Expr]{\code{Expr}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{Const (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Const}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{Const}}{\emph{value}}{}
All constant values.  The parser will return this node for simple
constants such as \code{42} or \code{"foo"} but it can be used to store more
complex values such as lists too.  Only constants with a safe
representation (objects where \code{eval(repr(x)) == x} is true).
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.Literal]{\code{Literal}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{Dict (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Dict}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{Dict}}{\emph{items}}{}
Any dict literal such as \code{\{1: 2, 3: 4\}}.  The items must be a list of
{\hyperref[extensions:jinja2.nodes.Pair]{\code{Pair}}} nodes.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.Literal]{\code{Literal}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{List (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.List}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{List}}{\emph{items}}{}
Any list literal such as \code{{[}1, 2, 3{]}}
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.Literal]{\code{Literal}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{TemplateData (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.TemplateData}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{TemplateData}}{\emph{data}}{}
A constant template string.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.Literal]{\code{Literal}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{Tuple (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Tuple}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{Tuple}}{\emph{items}, \emph{ctx}}{}
For loop unpacking and some other things like multiple arguments
for subscripts.  Like for {\hyperref[extensions:jinja2.nodes.Name]{\code{Name}}} \emph{ctx} specifies if the tuple
is used for loading the names or storing.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.Literal]{\code{Literal}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{MarkSafe (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.MarkSafe}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{MarkSafe}}{\emph{expr}}{}
Mark the wrapped expression as safe (wrap it as \emph{Markup}).
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.Expr]{\code{Expr}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{MarkSafeIfAutoescape (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.MarkSafeIfAutoescape}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{MarkSafeIfAutoescape}}{\emph{expr}}{}
Mark the wrapped expression as safe (wrap it as \emph{Markup}) but
only if autoescaping is active.
New in version 2.5.\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.Expr]{\code{Expr}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{Name (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Name}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{Name}}{\emph{name}, \emph{ctx}}{}
Looks up a name or stores a value in a name.
The \emph{ctx} of the node can be one of the following values:
\begin{itemize}
\item {} 
\emph{store}: store a value in the name

\item {} 
\emph{load}: load that name

\item {} 
\emph{param}: like \emph{store} but if the name was defined as function parameter.

\end{itemize}
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.Expr]{\code{Expr}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{Slice (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Slice}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{Slice}}{\emph{start}, \emph{stop}, \emph{step}}{}
Represents a slice object.  This must only be used as argument for
\code{Subscript}.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.Expr]{\code{Expr}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{Test (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Test}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{Test}}{\emph{node}, \emph{name}, \emph{args}, \emph{kwargs}, \emph{dyn\_args}, \emph{dyn\_kwargs}}{}
Applies a test on an expression.  \emph{name} is the name of the test, the
rest of the fields are the same as for {\hyperref[extensions:jinja2.nodes.Call]{\code{Call}}}.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.Expr]{\code{Expr}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{UnaryExpr (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.UnaryExpr}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{UnaryExpr}}{\emph{node}}{}
Baseclass for all unary expressions.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.Expr]{\code{Expr}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{Neg (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Neg}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{Neg}}{\emph{node}}{}
Make the expression negative.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.UnaryExpr]{\code{UnaryExpr}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{Not (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Not}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{Not}}{\emph{node}}{}
Negate the expression.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.UnaryExpr]{\code{UnaryExpr}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{Pos (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Pos}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{Pos}}{\emph{node}}{}
Make the expression positive (noop for most expressions)
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.UnaryExpr]{\code{UnaryExpr}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{Helper (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Helper}\pysigline{\strong{class }\code{jinja2.nodes.}\bfcode{Helper}}{}
Nodes that exist in a specific context only.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.Node]{\code{Node}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{Keyword (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Keyword}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{Keyword}}{\emph{key}, \emph{value}}{}
A key, value pair for keyword arguments where key is a string.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.Helper]{\code{Helper}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{Operand (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Operand}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{Operand}}{\emph{op}, \emph{expr}}{}
Holds an operator and an expression.
The following operators are available: \code{\%}, \code{**}, \code{*}, \code{+}, \code{-}, \code{//}, \code{/}, \code{eq}, \code{gt}, \code{gteq}, \code{in}, \code{lt}, \code{lteq}, \code{ne}, \code{not}, \code{notin}
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.Helper]{\code{Helper}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{Pair (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Pair}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{Pair}}{\emph{key}, \emph{value}}{}
A key, value pair for dicts.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.Helper]{\code{Helper}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{Stmt (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Stmt}\pysigline{\strong{class }\code{jinja2.nodes.}\bfcode{Stmt}}{}
Base node for all statements.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.Node]{\code{Node}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{Assign (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Assign}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{Assign}}{\emph{target}, \emph{node}}{}
Assigns an expression to a target.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.Stmt]{\code{Stmt}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{Block (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Block}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{Block}}{\emph{name}, \emph{body}, \emph{scoped}}{}
A node that represents a block.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.Stmt]{\code{Stmt}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{Break (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Break}\pysigline{\strong{class }\code{jinja2.nodes.}\bfcode{Break}}{}
Break a loop.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.Stmt]{\code{Stmt}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{CallBlock (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.CallBlock}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{CallBlock}}{\emph{call}, \emph{args}, \emph{defaults}, \emph{body}}{}
Like a macro without a name but a call instead.  \emph{call} is called with
the unnamed macro as \emph{caller} argument this node holds.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.Stmt]{\code{Stmt}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{Continue (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Continue}\pysigline{\strong{class }\code{jinja2.nodes.}\bfcode{Continue}}{}
Continue a loop.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.Stmt]{\code{Stmt}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{EvalContextModifier (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.EvalContextModifier}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{EvalContextModifier}}{\emph{options}}{}
Modifies the eval context.  For each option that should be modified,
a {\hyperref[extensions:jinja2.nodes.Keyword]{\code{Keyword}}} has to be added to the \code{options} list.

Example to change the \emph{autoescape} setting:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n}{EvalContextModifier}\PYG{p}{(}\PYG{n}{options}\PYG{o}{=}\PYG{p}{[}\PYG{n}{Keyword}\PYG{p}{(}\PYG{l+s}{'}\PYG{l+s}{autoescape}\PYG{l+s}{'}\PYG{p}{,} \PYG{n}{Const}\PYG{p}{(}\PYG{n+nb+bp}{True}\PYG{p}{)}\PYG{p}{)}\PYG{p}{]}\PYG{p}{)}
\end{Verbatim}
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.Stmt]{\code{Stmt}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{ScopedEvalContextModifier (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.ScopedEvalContextModifier}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{ScopedEvalContextModifier}}{\emph{options}, \emph{body}}{}
Modifies the eval context and reverts it later.  Works exactly like
{\hyperref[extensions:jinja2.nodes.EvalContextModifier]{\code{EvalContextModifier}}} but will only modify the
{\hyperref[api:jinja2.nodes.EvalContext]{\code{EvalContext}}} for nodes in the \code{body}.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.EvalContextModifier]{\code{EvalContextModifier}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{ExprStmt (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.ExprStmt}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{ExprStmt}}{\emph{node}}{}
A statement that evaluates an expression and discards the result.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.Stmt]{\code{Stmt}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{Extends (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Extends}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{Extends}}{\emph{template}}{}
Represents an extends statement.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.Stmt]{\code{Stmt}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{FilterBlock (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.FilterBlock}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{FilterBlock}}{\emph{body}, \emph{filter}}{}
Node for filter sections.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.Stmt]{\code{Stmt}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{For (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.For}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{For}}{\emph{target}, \emph{iter}, \emph{body}, \emph{else\_}, \emph{test}, \emph{recursive}}{}
The for loop.  \emph{target} is the target for the iteration (usually a
{\hyperref[extensions:jinja2.nodes.Name]{\code{Name}}} or {\hyperref[extensions:jinja2.nodes.Tuple]{\code{Tuple}}}), \emph{iter} the iterable.  \emph{body} is a list
of nodes that are used as loop-body, and \emph{else\_} a list of nodes for the
\emph{else} block.  If no else node exists it has to be an empty list.

For filtered nodes an expression can be stored as \emph{test}, otherwise \emph{None}.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.Stmt]{\code{Stmt}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{FromImport (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.FromImport}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{FromImport}}{\emph{template}, \emph{names}, \emph{with\_context}}{}
A node that represents the from import tag.  It's important to not
pass unsafe names to the name attribute.  The compiler translates the
attribute lookups directly into getattr calls and does \emph{not} use the
subscript callback of the interface.  As exported variables may not
start with double underscores (which the parser asserts) this is not a
problem for regular Jinja code, but if this node is used in an extension
extra care must be taken.

The list of names may contain tuples if aliases are wanted.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.Stmt]{\code{Stmt}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{If (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.If}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{If}}{\emph{test}, \emph{body}, \emph{else\_}}{}
If \emph{test} is true, \emph{body} is rendered, else \emph{else\_}.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.Stmt]{\code{Stmt}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{Import (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Import}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{Import}}{\emph{template}, \emph{target}, \emph{with\_context}}{}
A node that represents the import tag.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.Stmt]{\code{Stmt}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{Include (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Include}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{Include}}{\emph{template}, \emph{with\_context}, \emph{ignore\_missing}}{}
A node that represents the include tag.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.Stmt]{\code{Stmt}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{Macro (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Macro}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{Macro}}{\emph{name}, \emph{args}, \emph{defaults}, \emph{body}}{}
A macro definition.  \emph{name} is the name of the macro, \emph{args} a list of
arguments and \emph{defaults} a list of defaults if there are any.  \emph{body} is
a list of nodes for the macro body.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.Stmt]{\code{Stmt}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{Output (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Output}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{Output}}{\emph{nodes}}{}
A node that holds multiple expressions which are then printed out.
This is used both for the \emph{print} statement and the regular template data.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.Stmt]{\code{Stmt}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{Scope (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Scope}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{Scope}}{\emph{body}}{}
An artificial scope.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.Stmt]{\code{Stmt}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{Template (class in jinja2.nodes)}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Template}\pysiglinewithargsret{\strong{class }\code{jinja2.nodes.}\bfcode{Template}}{\emph{body}}{}
Node that represents a template.  This must be the outermost node that
is passed to the compiler.
\begin{quote}\begin{description}
\item[{Node type}] \leavevmode
{\hyperref[extensions:jinja2.nodes.Node]{\code{Node}}}

\end{description}\end{quote}

\end{fulllineitems}

\index{Impossible}

\begin{fulllineitems}
\phantomsection\label{extensions:jinja2.nodes.Impossible}\pysigline{\strong{exception }\code{jinja2.nodes.}\bfcode{Impossible}}{}
Raised if the node could not perform a requested action.

\end{fulllineitems}



\chapter{Integration}
\label{integration::doc}\label{integration:integration}
Jinja2 provides some code for integration into other tools such as frameworks,
the \href{http://babel.edgewall.org/}{Babel} library or your favourite editor for fancy code highlighting.
This is a brief description of whats included.


\section{Babel Integration}
\label{integration:babel-integration}\label{integration:id1}
Jinja provides support for extracting gettext messages from templates via a
\href{http://babel.edgewall.org/}{Babel} extractor entry point called \emph{jinja2.ext.babel\_extract}.  The Babel
support is implemented as part of the {\hyperref[extensions:i18n-extension]{\emph{i18n Extension}}} extension.

Gettext messages extracted from both \emph{trans} tags and code expressions.

To extract gettext messages from templates, the project needs a Jinja2 section
in its Babel extraction method \href{http://babel.edgewall.org/wiki/Documentation/messages.html\#extraction-method-mapping-and-configuration}{mapping file}:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{k}{[jinja2: **/templates/**.html]}
\PYG{n+na}{encoding} \PYG{o}{=} \PYG{l+s}{utf-8}
\end{Verbatim}

The syntax related options of the \code{Environment} are also available as
configuration values in the mapping file.  For example to tell the extraction
that templates use \code{\%} as \emph{line\_statement\_prefix} you can use this code:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{k}{[jinja2: **/templates/**.html]}
\PYG{n+na}{encoding} \PYG{o}{=} \PYG{l+s}{utf-8}
\PYG{n+na}{line\PYGZus{}statement\PYGZus{}prefix} \PYG{o}{=} \PYG{l+s}{\%}
\end{Verbatim}

{\hyperref[extensions:jinja-extensions]{\emph{Extensions}}} may also be defined by passing a comma separated list
of import paths as \emph{extensions} value.  The i18n extension is added
automatically.


\section{Pylons}
\label{integration:mapping-file}\label{integration:pylons}
With \href{http://www.pylonshq.com/}{Pylons} 0.9.7 onwards it's incredible easy to integrate Jinja into a
Pylons powered application.

The template engine is configured in \emph{config/environment.py}.  The configuration
for Jinja2 looks something like that:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{k+kn}{from} \PYG{n+nn}{jinja2} \PYG{k+kn}{import} \PYG{n}{Environment}\PYG{p}{,} \PYG{n}{PackageLoader}
\PYG{n}{config}\PYG{p}{[}\PYG{l+s}{'}\PYG{l+s}{pylons.app\PYGZus{}globals}\PYG{l+s}{'}\PYG{p}{]}\PYG{o}{.}\PYG{n}{jinja\PYGZus{}env} \PYG{o}{=} \PYG{n}{Environment}\PYG{p}{(}
    \PYG{n}{loader}\PYG{o}{=}\PYG{n}{PackageLoader}\PYG{p}{(}\PYG{l+s}{'}\PYG{l+s}{yourapplication}\PYG{l+s}{'}\PYG{p}{,} \PYG{l+s}{'}\PYG{l+s}{templates}\PYG{l+s}{'}\PYG{p}{)}
\PYG{p}{)}
\end{Verbatim}

After that you can render Jinja templates by using the \emph{render\_jinja} function
from the \emph{pylons.templating} module.

Additionally it's a good idea to set the Pylons' \emph{c} object into strict mode.
Per default any attribute to not existing attributes on the \emph{c} object return
an empty string and not an undefined object.  To change this just use this
snippet and add it into your \emph{config/environment.py}:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n}{config}\PYG{p}{[}\PYG{l+s}{'}\PYG{l+s}{pylons.strict\PYGZus{}c}\PYG{l+s}{'}\PYG{p}{]} \PYG{o}{=} \PYG{n+nb+bp}{True}
\end{Verbatim}


\section{TextMate}
\label{integration:id2}\label{integration:textmate}
Inside the \emph{ext} folder of Jinja2 there is a bundle for TextMate that supports
syntax highlighting for Jinja1 and Jinja2 for text based templates as well as
HTML.  It also contains a few often used snippets.


\section{Vim}
\label{integration:vim}
A syntax plugin for \href{http://www.vim.org/}{Vim} exists in the Vim-scripts directory as well as the
ext folder of Jinja2.  \href{http://www.vim.org/scripts/script.php?script\_id=1856}{The script}
supports Jinja1 and Jinja2.  Once installed two file types are available \emph{jinja}
and \emph{htmljinja}.  The first one for text based templates, the latter for HTML
templates.

Copy the files into your \emph{syntax} folder.


\chapter{Switching from other Template Engines}
\label{switching:switching-from-other-template-engines}\label{switching::doc}\label{switching:id3}
If you have used a different template engine in the past and want to swtich
to Jinja2 here is a small guide that shows the basic syntatic and semantic
changes between some common, similar text template engines for Python.


\section{Jinja1}
\label{switching:jinja1}
Jinja2 is mostly compatible with Jinja1 in terms of API usage and template
syntax.  The differences between Jinja1 and 2 are explained in the following
list.


\subsection{API}
\label{switching:api}\begin{description}
\item[{Loaders}] \leavevmode
Jinja2 uses a different loader API.  Because the internal representation
of templates changed there is no longer support for external caching
systems such as memcached.  The memory consumed by templates is comparable
with regular Python modules now and external caching doesn't give any
advantage.  If you have used a custom loader in the past have a look at
the new {\hyperref[api:loaders]{\emph{loader API}}}.

\item[{Loading templates from strings}] \leavevmode
In the past it was possible to generate templates from a string with the
default environment configuration by using \emph{jinja.from\_string}.  Jinja2
provides a \code{Template} class that can be used to do the same, but
with optional additional configuration.

\item[{Automatic unicode conversion}] \leavevmode
Jinja1 performed automatic conversion of bytestrings in a given encoding
into unicode objects.  This conversion is no longer implemented as it
was inconsistent as most libraries are using the regular Python ASCII
bytestring to Unicode conversion.  An application powered by Jinja2
\emph{has to} use unicode internally everywhere or make sure that Jinja2 only
gets unicode strings passed.

\item[{i18n}] \leavevmode
Jinja1 used custom translators for internationalization.  i18n is now
available as Jinja2 extension and uses a simpler, more gettext friendly
interface and has support for babel.  For more details see
{\hyperref[extensions:i18n-extension]{\emph{i18n Extension}}}.

\item[{Internal methods}] \leavevmode
Jinja1 exposed a few internal methods on the environment object such
as \emph{call\_function}, \emph{get\_attribute} and others.  While they were marked
as being an internal method it was possible to override them.  Jinja2
doesn't have equivalent methods.

\item[{Sandbox}] \leavevmode
Jinja1 was running sandbox mode by default.  Few applications actually
used that feature so it became optional in Jinja2.  For more details
about the sandboxed execution see \code{SandboxedEnvironment}.

\item[{Context}] \leavevmode
Jinja1 had a stacked context as storage for variables passed to the
environment.  In Jinja2 a similar object exists but it doesn't allow
modifications nor is it a singleton.  As inheritance is dynamic now
multiple context objects may exist during template evaluation.

\item[{Filters and Tests}] \leavevmode
Filters and tests are regular functions now.  It's no longer necessary
and allowed to use factory functions.

\end{description}


\subsection{Templates}
\label{switching:templates}
Jinja2 has mostly the same syntax as Jinja1.  What's different is that
macros require parentheses around the argument list now.

Additionally Jinja2 allows dynamic inheritance now and dynamic includes.
The old helper function \emph{rendertemplate} is gone now, \emph{include} can be used
instead.  Includes no longer import macros and variable assignments, for
that the new \emph{import} tag is used.  This concept is explained in the
{\hyperref[templates:import]{\emph{Import}}} documentation.

Another small change happened in the \emph{for}-tag.  The special loop variable
doesn't have a \emph{parent} attribute, instead you have to alias the loop
yourself.  See {\hyperref[tricks:accessing-the-parent-loop]{\emph{Accessing the parent Loop}}} for more details.


\section{Django}
\label{switching:django}
If you have previously worked with Django templates, you should find
Jinja2 very familiar.  In fact, most of the syntax elements look and
work the same.

However, Jinja2 provides some more syntax elements covered in the
documentation and some work a bit different.

This section covers the template changes.  As the API is fundamentally
different we won't cover it here.


\subsection{Method Calls}
\label{switching:method-calls}
In Django method calls work implicitly.  With Jinja2 you have to specify that
you want to call an object.  Thus this Django code:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{for} \PYG{n+nv}{page} \PYG{k}{in} \PYG{n+nv}{user}\PYG{n+nv}{.get\PYGZus{}created\PYGZus{}pages} \PYG{c+cp}{\%\PYGZcb{}}
    ...
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endfor} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}

will look like this in Jinja:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{for} \PYG{n+nv}{page} \PYG{k}{in} \PYG{n+nv}{user}\PYG{n+nv}{.get\PYGZus{}created\PYGZus{}pages}\PYG{o}{(}\PYG{o}{)} \PYG{c+cp}{\%\PYGZcb{}}
    ...
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endfor} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}

This allows you to pass variables to the function which is also used for macros
which is not possible in Django.


\subsection{Conditions}
\label{switching:conditions}
In Django you can use the following constructs to check for equality:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{ifequal} \PYG{n+nv}{foo} \PYG{l+s+s2}{"bar"} \PYG{c+cp}{\%\PYGZcb{}}
    ...
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{else} \PYG{c+cp}{\%\PYGZcb{}}
    ...
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endifequal} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}

In Jinja2 you can use the normal if statement in combination with operators:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{if} \PYG{n+nv}{foo} \PYG{o}{==} \PYG{l+s+s1}{'bar'} \PYG{c+cp}{\%\PYGZcb{}}
    ...
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{else} \PYG{c+cp}{\%\PYGZcb{}}
    ...
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endif} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}

You can also have multiple elif branches in your template:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{if} \PYG{n+nv}{something} \PYG{c+cp}{\%\PYGZcb{}}
    ...
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{elif} \PYG{n+nv}{otherthing} \PYG{c+cp}{\%\PYGZcb{}}
    ...
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{elif} \PYG{n+nv}{foothing} \PYG{c+cp}{\%\PYGZcb{}}
    ...
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{else} \PYG{c+cp}{\%\PYGZcb{}}
    ...
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endif} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}


\subsection{Filter Arguments}
\label{switching:filter-arguments}
Jinja2 provides more than one argument for filters.  Also the syntax for
argument passing is different.  A template that looks like this in Django:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{items}\PYG{o}{\textbar{}}\PYG{n+nf}{join}\PYG{l+s+s2}{:", "} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}
\end{Verbatim}

looks like this in Jinja2:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{items}\PYG{o}{\textbar{}}\PYG{n+nf}{join}\PYG{o}{(}\PYG{l+s+s1}{', '}\PYG{o}{)} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}
\end{Verbatim}

In fact it's a bit more verbose but it allows different types of arguments -
including variables - and more than one of them.


\subsection{Tests}
\label{switching:tests}
In addition to filters there also are tests you can perform using the is
operator.  Here are some examples:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{if} \PYG{n+nv}{user}\PYG{n+nv}{.user\PYGZus{}id} \PYG{k}{is} \PYG{n+nf}{odd} \PYG{c+cp}{\%\PYGZcb{}}
    \PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{user}\PYG{n+nv}{.username}\PYG{o}{\textbar{}}\PYG{n+nf}{e} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}} is odd
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{else} \PYG{c+cp}{\%\PYGZcb{}}
    hmm. \PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{user}\PYG{n+nv}{.username}\PYG{o}{\textbar{}}\PYG{n+nf}{e} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}} looks pretty normal
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endif} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}


\subsection{Loops}
\label{switching:loops}
For loops work very similar to Django, the only incompatibility is that in
Jinja2 the special variable for the loop context is called \emph{loop} and not
\emph{forloop} like in Django.


\subsection{Cycle}
\label{switching:cycle}
The \code{\{\% cycle \%\}} tag does not exist in Jinja because of it's implicit
nature.  However you can achieve mostly the same by using the \emph{cycle}
method on a loop object.

The following Django template:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{for} \PYG{n+nv}{user} \PYG{k}{in} \PYG{n+nv}{users} \PYG{c+cp}{\%\PYGZcb{}}
    \PYG{n+nt}{\textless{}li} \PYG{n+na}{class=}\PYG{l+s}{"}\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{cycle} \PYG{l+s+s1}{'odd'} \PYG{l+s+s1}{'even'} \PYG{c+cp}{\%\PYGZcb{}}\PYG{l+s}{"}\PYG{n+nt}{\textgreater{}}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{user} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{n+nt}{\textless{}/li\textgreater{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endfor} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}

Would look like this in Jinja:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{for} \PYG{n+nv}{user} \PYG{k}{in} \PYG{n+nv}{users} \PYG{c+cp}{\%\PYGZcb{}}
    \PYG{n+nt}{\textless{}li} \PYG{n+na}{class=}\PYG{l+s}{"}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nb}{loop}\PYG{n+nv}{.cycle}\PYG{o}{(}\PYG{l+s+s1}{'odd'}\PYG{o}{,} \PYG{l+s+s1}{'even'}\PYG{o}{)} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{l+s}{"}\PYG{n+nt}{\textgreater{}}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{user} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{n+nt}{\textless{}/li\textgreater{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endfor} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}

There is no equivalent of \code{\{\% cycle ... as variable \%\}}.


\section{Mako}
\label{switching:mako}
If you have used Mako so far and want to switch to Jinja2 you can configure
Jinja2 to look more like Mako:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n}{env} \PYG{o}{=} \PYG{n}{Environment}\PYG{p}{(}\PYG{l+s}{'}\PYG{l+s}{\textless{}}\PYG{l+s}{\%}\PYG{l+s}{'}\PYG{p}{,} \PYG{l+s}{'}\PYG{l+s}{\%}\PYG{l+s}{\textgreater{}}\PYG{l+s}{'}\PYG{p}{,} \PYG{l+s}{'}\PYG{l+s}{\$\PYGZob{}}\PYG{l+s}{'}\PYG{p}{,} \PYG{l+s}{'}\PYG{l+s}{\PYGZcb{}}\PYG{l+s}{'}\PYG{p}{,} \PYG{l+s}{'}\PYG{l+s}{\%}\PYG{l+s}{'}\PYG{p}{)}
\end{Verbatim}

Once the environment is configure like that Jinja2 should be able to interpret
a small subset of Mako templates.  Jinja2 does not support embedded Python code
so you would have to move that out of the template.  The syntax for defs (in
Jinja2 defs are called macros) and template inheritance is different too.  The
following Mako template:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\textless{}\%}\PYG{n+nb}{inherit} \PYG{n+na}{file=}\PYG{l+s}{"layout.html"} \PYG{c+cp}{/\textgreater{}}
\PYG{c+cp}{\textless{}\%}\PYG{n+nb}{def} \PYG{n+na}{name=}\PYG{l+s}{"title()"}\PYG{c+cp}{\textgreater{}}Page Title\PYG{c+cp}{\textless{}/\%}\PYG{n+nb}{def}\PYG{c+cp}{\textgreater{}}
\PYG{n+nt}{\textless{}ul}\PYG{n+nt}{\textgreater{}}
\PYG{c+cp}{\%} \PYG{k}{for} \PYG{n}{item} \PYG{o+ow}{in} \PYG{n+nb}{list}\PYG{p}{:}
    \PYG{n+nt}{\textless{}li}\PYG{n+nt}{\textgreater{}}\PYG{c+cp}{\$\PYGZob{}}\PYG{n}{item}\PYG{c+cp}{\PYGZcb{}}\PYG{n+nt}{\textless{}/li\textgreater{}}
\PYG{c+cp}{\%}\PYG{k}{ endfor}
\PYG{n+nt}{\textless{}/ul\textgreater{}}
\end{Verbatim}

Looks like this in Jinja2 with the above configuration:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\textless{}\%} \PYG{n}{extends} \PYG{l+s}{"}\PYG{l+s}{layout.html}\PYG{l+s}{"} \PYG{c+cp}{\%\textgreater{}}
\PYG{c+cp}{\textless{}\%} \PYG{n}{block} \PYG{n}{title} \PYG{c+cp}{\%\textgreater{}}Page Title\PYG{c+cp}{\textless{}\%} \PYG{n}{endblock} \PYG{c+cp}{\%\textgreater{}}
\PYG{c+cp}{\textless{}\%} \PYG{n}{block} \PYG{n}{body} \PYG{c+cp}{\%\textgreater{}}
\PYG{n+nt}{\textless{}ul}\PYG{n+nt}{\textgreater{}}
\PYG{c+cp}{\%} \PYG{k}{for} \PYG{n}{item} \PYG{o+ow}{in} \PYG{n+nb}{list}\PYG{p}{:}
    \PYG{n+nt}{\textless{}li}\PYG{n+nt}{\textgreater{}}\PYG{c+cp}{\$\PYGZob{}}\PYG{n}{item}\PYG{c+cp}{\PYGZcb{}}\PYG{n+nt}{\textless{}/li\textgreater{}}
\PYG{c+cp}{\%}\PYG{k}{ endfor}
\PYG{n+nt}{\textless{}/ul\textgreater{}}
\PYG{c+cp}{\textless{}\%} \PYG{n}{endblock} \PYG{c+cp}{\%\textgreater{}}
\end{Verbatim}


\chapter{Tips and Tricks}
\label{tricks:tips-and-tricks}\label{tricks::doc}
This part of the documentation shows some tips and tricks for Jinja2
templates.


\section{Null-Master Fallback}
\label{tricks:null-master-fallback}\label{tricks:id1}
Jinja2 supports dynamic inheritance and does not distinguish between parent
and child template as long as no \emph{extends} tag is visited.  While this leads
to the surprising behavior that everything before the first \emph{extends} tag
including whitespace is printed out instead of being igored, it can be used
for a neat trick.

Usually child templates extend from one template that adds a basic HTML
skeleton.  However it's possible put the \emph{extends} tag into an \emph{if} tag to
only extend from the layout template if the \emph{standalone} variable evaluates
to false which it does per default if it's not defined.  Additionally a very
basic skeleton is added to the file so that if it's indeed rendered with
\emph{standalone} set to \emph{True} a very basic HTML skeleton is added:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{if} \PYG{k}{not} \PYG{n+nv}{standalone} \PYG{c+cp}{\%\PYGZcb{}}\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{extends} \PYG{l+s+s1}{'master.html'} \PYG{c+cp}{\%\PYGZcb{}}\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endif} -\PYG{c+cp}{\%\PYGZcb{}}
\PYG{c+cp}{\textless{}!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"\textgreater{}}
\PYG{n+nt}{\textless{}title}\PYG{n+nt}{\textgreater{}}\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{block} \PYG{n+nv}{title} \PYG{c+cp}{\%\PYGZcb{}}The Page Title\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endblock} \PYG{c+cp}{\%\PYGZcb{}}\PYG{n+nt}{\textless{}/title\textgreater{}}
\PYG{n+nt}{\textless{}link} \PYG{n+na}{rel=}\PYG{l+s}{"stylesheet"} \PYG{n+na}{href=}\PYG{l+s}{"style.css"} \PYG{n+na}{type=}\PYG{l+s}{"text/css"}\PYG{n+nt}{\textgreater{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{block} \PYG{n+nv}{body} \PYG{c+cp}{\%\PYGZcb{}}
  \PYG{n+nt}{\textless{}p}\PYG{n+nt}{\textgreater{}}This is the page body.\PYG{n+nt}{\textless{}/p\textgreater{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endblock} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}


\section{Alternating Rows}
\label{tricks:alternating-rows}
If you want to have different styles for each row of a table or
list you can use the \emph{cycle} method on the \emph{loop} object:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nt}{\textless{}ul}\PYG{n+nt}{\textgreater{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{for} \PYG{n+nv}{row} \PYG{k}{in} \PYG{n+nv}{rows} \PYG{c+cp}{\%\PYGZcb{}}
  \PYG{n+nt}{\textless{}li} \PYG{n+na}{class=}\PYG{l+s}{"}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nb}{loop}\PYG{n+nv}{.cycle}\PYG{o}{(}\PYG{l+s+s1}{'odd'}\PYG{o}{,} \PYG{l+s+s1}{'even'}\PYG{o}{)} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{l+s}{"}\PYG{n+nt}{\textgreater{}}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{row} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{n+nt}{\textless{}/li\textgreater{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endfor} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{n+nt}{\textless{}/ul\textgreater{}}
\end{Verbatim}

\emph{cycle} can take an unlimited amount of strings.  Each time this
tag is encountered the next item from the list is rendered.


\section{Highlighting Active Menu Items}
\label{tricks:highlighting-active-menu-items}
Often you want to have a navigation bar with an active navigation
item.  This is really simple to achieve.  Because assignments outside
of \emph{block}s in child templates are global and executed before the layout
template is evaluated it's possible to define the active menu item in the
child template:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{extends} \PYG{l+s+s2}{"layout.html"} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{set} \PYG{n+nv}{active\PYGZus{}page} \PYG{o}{=} \PYG{l+s+s2}{"index"} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}

The layout template can then access \emph{active\_page}.  Additionally it makes
sense to defined a default for that variable:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{set} \PYG{n+nv}{navigation\PYGZus{}bar} \PYG{o}{=} \PYG{o}{[}
    \PYG{o}{(}\PYG{l+s+s1}{'/'}\PYG{o}{,} \PYG{l+s+s1}{'index'}\PYG{o}{,} \PYG{l+s+s1}{'Index'}\PYG{o}{)}\PYG{o}{,}
    \PYG{o}{(}\PYG{l+s+s1}{'/downloads/'}\PYG{o}{,} \PYG{l+s+s1}{'downloads'}\PYG{o}{,} \PYG{l+s+s1}{'Downloads'}\PYG{o}{)}\PYG{o}{,}
    \PYG{o}{(}\PYG{l+s+s1}{'/about/'}\PYG{o}{,} \PYG{l+s+s1}{'about'}\PYG{o}{,} \PYG{l+s+s1}{'About'}\PYG{o}{)}
\PYG{o}{]} -\PYG{c+cp}{\%\PYGZcb{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{set} \PYG{n+nv}{active\PYGZus{}page} \PYG{o}{=} \PYG{n+nv}{active\PYGZus{}page}\PYG{o}{\textbar{}}\PYG{n+nf}{default}\PYG{o}{(}\PYG{l+s+s1}{'index'}\PYG{o}{)} -\PYG{c+cp}{\%\PYGZcb{}}
...
\PYG{n+nt}{\textless{}ul} \PYG{n+na}{id=}\PYG{l+s}{"navigation"}\PYG{n+nt}{\textgreater{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{for} \PYG{n+nv}{href}\PYG{o}{,} \PYG{n+nv}{id}\PYG{o}{,} \PYG{n+nv}{caption} \PYG{k}{in} \PYG{n+nv}{navigation\PYGZus{}bar} \PYG{c+cp}{\%\PYGZcb{}}
  \PYG{n+nt}{\textless{}li}\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{if} \PYG{n+nv}{id} \PYG{o}{==} \PYG{n+nv}{active\PYGZus{}page} \PYG{c+cp}{\%\PYGZcb{}} \PYG{n+na}{class=}\PYG{l+s}{"active"}\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endif}
  \PYG{c+cp}{\%\PYGZcb{}}\PYG{n+nt}{\textgreater{}}\PYG{n+nt}{\textless{}a} \PYG{n+na}{href=}\PYG{l+s}{"}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{href}\PYG{o}{\textbar{}}\PYG{n+nf}{e} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{l+s}{"}\PYG{n+nt}{\textgreater{}}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{caption}\PYG{o}{\textbar{}}\PYG{n+nf}{e} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{n+nt}{\textless{}/a\textgreater{}}/li\textgreater{}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endfor} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{n+nt}{\textless{}/ul\textgreater{}}
...
\end{Verbatim}


\section{Accessing the parent Loop}
\label{tricks:id2}\label{tricks:accessing-the-parent-loop}
The special \emph{loop} variable always points to the innermost loop.  If it's
desired to have access to an outer loop it's possible to alias it:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nt}{\textless{}table}\PYG{n+nt}{\textgreater{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{for} \PYG{n+nv}{row} \PYG{k}{in} \PYG{n+nv}{table} \PYG{c+cp}{\%\PYGZcb{}}
  \PYG{n+nt}{\textless{}tr}\PYG{n+nt}{\textgreater{}}
  \PYG{c+cp}{\PYGZob{}\%} \PYG{k}{set} \PYG{n+nv}{rowloop} \PYG{o}{=} \PYG{n+nb}{loop} \PYG{c+cp}{\%\PYGZcb{}}
  \PYG{c+cp}{\PYGZob{}\%} \PYG{k}{for} \PYG{n+nv}{cell} \PYG{k}{in} \PYG{n+nv}{row} \PYG{c+cp}{\%\PYGZcb{}}
    \PYG{n+nt}{\textless{}td} \PYG{n+na}{id=}\PYG{l+s}{"cell-}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{rowloop}\PYG{n+nv}{.index} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{l+s}{-}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nb}{loop}\PYG{n+nv}{.index} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{n+nt}{\textgreater{}}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{cell} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{n+nt}{\textless{}/td\textgreater{}}
  \PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endfor} \PYG{c+cp}{\%\PYGZcb{}}
  \PYG{n+nt}{\textless{}/tr\textgreater{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endfor} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{n+nt}{\textless{}/table\textgreater{}}
\end{Verbatim}


\chapter{Frequently Asked Questions}
\label{faq::doc}\label{faq:frequently-asked-questions}
This page answers some of the often asked questions about Jinja.


\section{Why is it called Jinja?}
\label{faq:why-is-it-called-jinja}
The name Jinja was chosen because it's the name of a Japanese temple and
temple and template share a similar pronunciation.  It is not named after
the capital city of Uganda.


\section{How fast is it?}
\label{faq:how-fast-is-it}
We really hate benchmarks especially since they don't reflect much.  The
performance of a template depends on many factors and you would have to
benchmark different engines in different situations.  The benchmarks from the
testsuite show that Jinja2 has a similar performance to \href{http://www.makotemplates.org/}{Mako} and is between
10 and 20 times faster than Django's template engine or Genshi.  These numbers
should be taken with tons of salt as the benchmarks that took these numbers
only test a few performance related situations such as looping.  Generally
speaking the performance of a template engine doesn't matter much as the
usual bottleneck in a web application is either the database or the application
code.


\section{How Compatible is Jinja2 with Django?}
\label{faq:mako}\label{faq:how-compatible-is-jinja2-with-django}
The default syntax of Jinja2 matches Django syntax in many ways.  However
this similarity doesn't mean that you can use a Django template unmodified
in Jinja2.  For example filter arguments use a function call syntax rather
than a colon to separate filter name and arguments.  Additionally the
extension interface in Jinja is fundamentally different from the Django one
which means that your custom tags won't work any longer.

Generally speaking you will use much less custom extensions as the Jinja
template system allows you to use a certain subset of Python expressions
which can replace most Django extensions.  For example instead of using
something like this:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{load} \PYG{n+nv}{comments} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{get\PYGZus{}latest\PYGZus{}comments} \PYG{l+m}{1}\PYG{l+m}{0} \PYG{k}{as} \PYG{n+nv}{latest\PYGZus{}comments} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{for} \PYG{n+nv}{comment} \PYG{k}{in} \PYG{n+nv}{latest\PYGZus{}comments} \PYG{c+cp}{\%\PYGZcb{}}
    ...
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endfor} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}

You will most likely provide an object with attributes to retrieve
comments from the database:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{for} \PYG{n+nv}{comment} \PYG{k}{in} \PYG{n+nv}{models}\PYG{n+nv}{.comments}\PYG{n+nv}{.latest}\PYG{o}{(}\PYG{l+m}{1}\PYG{l+m}{0}\PYG{o}{)} \PYG{c+cp}{\%\PYGZcb{}}
    ...
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endfor} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}

Or directly provide the model for quick testing:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{for} \PYG{n+nv}{comment} \PYG{k}{in} \PYG{n+nv}{Comment}\PYG{n+nv}{.objects}\PYG{n+nv}{.order\PYGZus{}by}\PYG{o}{(}\PYG{l+s+s1}{'-pub\PYGZus{}date'}\PYG{o}{)}\PYG{o}{[}\PYG{o}{:}\PYG{l+m}{1}\PYG{l+m}{0}\PYG{o}{]} \PYG{c+cp}{\%\PYGZcb{}}
    ...
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endfor} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}

Please keep in mind that even though you may put such things into templates
it still isn't a good idea.  Queries should go into the view code and not
the template!


\section{Isn't it a terrible idea to put Logic into Templates?}
\label{faq:isn-t-it-a-terrible-idea-to-put-logic-into-templates}
Without a doubt you should try to remove as much logic from templates as
possible.  But templates without any logic mean that you have to do all
the processing in the code which is boring and stupid.  A template engine
that does that is shipped with Python and called \emph{string.Template}.  Comes
without loops and if conditions and is by far the fastest template engine
you can get for Python.

So some amount of logic is required in templates to keep everyone happy.
And Jinja leaves it pretty much to you how much logic you want to put into
templates.  There are some restrictions in what you can do and what not.

Jinja2 neither allows you to put arbitrary Python code into templates nor
does it allow all Python expressions.  The operators are limited to the
most common ones and more advanced expressions such as list comprehensions
and generator expressions are not supported.  This keeps the template engine
easier to maintain and templates more readable.


\section{Why is Autoescaping not the Default?}
\label{faq:why-is-autoescaping-not-the-default}
There are multiple reasons why automatic escaping is not the default mode
and also not the recommended one.  While automatic escaping of variables
means that you will less likely have an XSS problem it also causes a huge
amount of extra processing in the template engine which can cause serious
performance problems.  As Python doesn't provide a way to mark strings as
unsafe Jinja has to hack around that limitation by providing a custom
string class (the \code{Markup} string) that safely interacts with safe
and unsafe strings.

With explicit escaping however the template engine doesn't have to perform
any safety checks on variables.  Also a human knows not to escape integers
or strings that may never contain characters one has to escape or already
HTML markup.  For example when iterating over a list over a table of
integers and floats for a table of statistics the template designer can
omit the escaping because he knows that integers or floats don't contain
any unsafe parameters.

Additionally Jinja2 is a general purpose template engine and not only used
for HTML/XML generation.  For example you may generate LaTeX, emails,
CSS, JavaScript, or configuration files.


\section{Why is the Context immutable?}
\label{faq:why-is-the-context-immutable}
When writing a \code{contextfunction()} or something similar you may have
noticed that the context tries to stop you from modifying it.  If you have
managed to modify the context by using an internal context API you may
have noticed that changes in the context don't seem to be visible in the
template.  The reason for this is that Jinja uses the context only as
primary data source for template variables for performance reasons.

If you want to modify the context write a function that returns a variable
instead that one can assign to a variable by using set:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{set} \PYG{n+nv}{comments} \PYG{o}{=} \PYG{n+nv}{get\PYGZus{}latest\PYGZus{}comments}\PYG{o}{(}\PYG{o}{)} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}


\section{What is the speedups module and why is it missing?}
\label{faq:what-is-the-speedups-module-and-why-is-it-missing}
To achieve a good performance with automatic escaping enabled, the escaping
function was also implemented in pure C in older Jinja2 releases and used if
Jinja2 was installed with the speedups module.

Because this feature itself is very useful for non-template engines as
well it was moved into a separate project on PyPI called \href{http://pypi.python.org/pypi/MarkupSafe}{MarkupSafe}.

Jinja2 no longer ships with a C implementation of it but only the pure
Python implementation.  It will however check if MarkupSafe is available
and installed, and if it is, use the Markup class from MarkupSafe.

So if you want the speedups, just import MarkupSafe.


\section{My tracebacks look weird.  What's happening?}
\label{faq:markupsafe}\label{faq:my-tracebacks-look-weird-what-s-happening}
If the debugsupport module is not compiled and you are using a Python
installation without ctypes (Python 2.4 without ctypes, Jython or Google's
AppEngine) Jinja2 is unable to provide correct debugging information and
the traceback may be incomplete.  There is currently no good workaround
for Jython or the AppEngine as ctypes is unavailable there and it's not
possible to use the debugsupport extension.


\section{Why is there no Python 2.3 support?}
\label{faq:why-is-there-no-python-2-3-support}
Python 2.3 is missing a lot of features that are used heavily in Jinja2.  This
decision was made as with the upcoming Python 2.6 and 3.0 versions it becomes
harder to maintain the code for older Python versions.  If you really need
Python 2.3 support you either have to use \href{http://jinja.pocoo.org/1/}{Jinja 1} or other templating
engines that still support 2.3.


\section{My Macros are overriden by something}
\label{faq:my-macros-are-overriden-by-something}
In some situations the Jinja scoping appears arbitrary:

layout.tmpl:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{macro} \PYG{n+nv}{foo}\PYG{o}{(}\PYG{o}{)} \PYG{c+cp}{\%\PYGZcb{}}\PYG{x}{LAYOUT}\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endmacro} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{block} \PYG{n+nv}{body} \PYG{c+cp}{\%\PYGZcb{}}\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endblock} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}

child.tmpl:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{extends} \PYG{l+s+s1}{'layout.tmpl'} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{macro} \PYG{n+nv}{foo}\PYG{o}{(}\PYG{o}{)} \PYG{c+cp}{\%\PYGZcb{}}\PYG{x}{CHILD}\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endmacro} \PYG{c+cp}{\%\PYGZcb{}}
\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{block} \PYG{n+nv}{body} \PYG{c+cp}{\%\PYGZcb{}}\PYG{c+cp}{\PYGZob{}\PYGZob{}} \PYG{n+nv}{foo}\PYG{o}{(}\PYG{o}{)} \PYG{c+cp}{\PYGZcb{}\PYGZcb{}}\PYG{c+cp}{\PYGZob{}\%} \PYG{k}{endblock} \PYG{c+cp}{\%\PYGZcb{}}
\end{Verbatim}

This will print \code{LAYOUT} in Jinja2.  This is a side effect of having
the parent template evaluated after the child one.  This allows child
templates passing information to the parent template.  To avoid this
issue rename the macro or variable in the parent template to have an
uncommon prefix.
\phantomsection\label{changelog:module-jinja2}\index{jinja2 (module)}

\chapter{Jinja2 Changelog}
\label{changelog:jinja-1}\label{changelog::doc}\label{changelog:jinja2-changelog}

\section{Version 2.5.3}
\label{changelog:version-2-5-3}
(bugfix release, released on October 17th 2010)
\begin{itemize}
\item {} 
fixed an operator precedence error introduced in 2.5.2.  Statements
like ``-foo.bar'' had their implicit parentheses applied around the
first part of the expression (``(-foo).bar'') instead of the more
correct ``-(foo.bar)''.

\end{itemize}


\section{Version 2.5.2}
\label{changelog:version-2-5-2}
(bugfix release, released on August 18th 2010)
\begin{itemize}
\item {} 
improved setup.py script to better work with assumptions people
might still have from it (\code{-{-}with-speedups}).

\item {} 
fixed a packaging error that excluded the new debug support.

\end{itemize}


\section{Version 2.5.1}
\label{changelog:version-2-5-1}
(bugfix release, released on August 17th 2010)
\begin{itemize}
\item {} 
StopIteration exceptions raised by functions called from templates
are now intercepted and converted to undefineds.  This solves a
lot of debugging grief.  (StopIteration is used internally to
abort template execution)

\item {} 
improved performance of macro calls slightly.

\item {} 
babel extraction can now properly extract newstyle gettext calls.

\item {} 
using the variable \emph{num} in newstyle gettext for something else
than the pluralize count will no longer raise a \code{KeyError}.

\item {} 
removed builtin markup class and switched to markupsafe.  For backwards
compatibility the pure Python implementation still exists but is
pulled from markupsafe by the Jinja2 developers.  The debug support
went into a separate feature called ``debugsupport'' and is disabled
by default because it is only relevant for Python 2.4

\item {} 
fixed an issue with unary operators having the wrong precendence.

\end{itemize}


\section{Version 2.5}
\label{changelog:version-2-5}
(codename Incoherence, relased on May 29th 2010)
\begin{itemize}
\item {} 
improved the sort filter (should have worked like this for a
long time) by adding support for case insensitive searches.

\item {} 
fixed a bug for getattribute constant folding.

\item {} 
support for newstyle gettext translations which result in a
nicer in-template user interface and more consistent
catalogs. ({\hyperref[extensions:newstyle-gettext]{\emph{Newstyle Gettext}}})

\item {} 
it's now possible to register extensions after an environment
was created.

\end{itemize}


\section{Version 2.4.1}
\label{changelog:version-2-4-1}
(bugfix release, released on April 20th 2010)
\begin{itemize}
\item {} 
fixed an error reporting bug for undefineds.

\end{itemize}


\section{Version 2.4}
\label{changelog:version-2-4}
(codename Correlation, released on April 13th 2010)
\begin{itemize}
\item {} 
the environment template loading functions now transparently
pass through a template object if it was passed to it.  This
makes it possible to import or extend from a template object
that was passed to the template.

\item {} 
added a \code{ModuleLoader} that can load templates from
precompiled sources.  The environment now features a method
to compile the templates from a configured loader into a zip
file or folder.

\item {} 
the \_speedups C extension now supports Python 3.

\item {} 
added support for autoescaping toggling sections and support
for evaluation contexts ({\hyperref[api:eval-context]{\emph{Evaluation Context}}}).

\item {} 
extensions have a priority now.

\end{itemize}


\section{Version 2.3.1}
\label{changelog:version-2-3-1}
(bugfix release, released on February 19th 2010)
\begin{itemize}
\item {} 
fixed an error reporting bug on all python versions

\item {} 
fixed an error reporting bug on Python 2.4

\end{itemize}


\section{Version 2.3}
\label{changelog:version-2-3}
(3000 Pythons, released on February 10th 2010)
\begin{itemize}
\item {} 
fixes issue with code generator that causes unbound variables
to be generated if set was used in if-blocks and other small
identifier problems.

\item {} 
include tags are now able to select between multiple templates
and take the first that exists, if a list of templates is
given.

\item {} 
fixed a problem with having call blocks in outer scopes that
have an argument that is also used as local variable in an
inner frame (\#360).

\item {} 
greatly improved error message reporting (\#339)

\item {} 
implicit tuple expressions can no longer be totally empty.
This change makes \code{\{\% if \%\}...\{\% endif \%\}} a syntax error
now. (\#364)

\item {} 
added support for translator comments if extracted via babel.

\item {} 
added with-statement extension.

\item {} 
experimental Python 3 support.

\end{itemize}


\section{Version 2.2.1}
\label{changelog:version-2-2-1}
(bugfix release, released on September 14th 2009)
\begin{itemize}
\item {} 
fixes some smaller problems for Jinja2 on Jython.

\end{itemize}


\section{Version 2.2}
\label{changelog:version-2-2}
(codename Kong, released on September 13th 2009)
\begin{itemize}
\item {} 
Include statements can now be marked with \code{ignore missing} to skip
non existing templates.

\item {} 
Priority of \emph{not} raised.  It's now possible to write \emph{not foo in bar}
as an alias to \emph{foo not in bar} like in python.  Previously the grammar
required parentheses (\emph{not (foo in bar)}) which was odd.

\item {} 
Fixed a bug that caused syntax errors when defining macros or using the
\emph{\{\% call \%\}} tag inside loops.

\item {} 
Fixed a bug in the parser that made \code{\{\{ foo{[}1, 2{]} \}\}} impossible.

\item {} 
Made it possible to refer to names from outer scopes in included templates
that were unused in the callers frame (\#327)

\item {} 
Fixed a bug that caused internal errors if names where used as iteration
variable and regular variable \emph{after} the loop if that variable was unused
\emph{before} the loop.  (\#331)

\item {} 
Added support for optional \emph{scoped} modifier to blocks.

\item {} 
Added support for line-comments.

\item {} 
Added the \emph{meta} module.

\item {} 
Renamed (undocumented) attribute ``overlay'' to ``overlayed'' on the
environment because it was clashing with a method of the same name.

\item {} 
speedup extension is now disabled by default.

\end{itemize}


\section{Version 2.1.1}
\label{changelog:version-2-1-1}
(Bugfix release)
\begin{itemize}
\item {} 
Fixed a translation error caused by looping over empty recursive loops.

\end{itemize}


\section{Version 2.1}
\label{changelog:version-2-1}
(codename Yasuzō, released on November 23rd 2008)
\begin{itemize}
\item {} 
fixed a bug with nested loops and the special loop variable.  Before the
change an inner loop overwrote the loop variable from the outer one after
iteration.

\item {} 
fixed a bug with the i18n extension that caused the explicit pluralization
block to look up the wrong variable.

\item {} 
fixed a limitation in the lexer that made \code{\{\{ foo.0.0 \}\}} impossible.

\item {} 
index based subscribing of variables with a constant value returns an
undefined object now instead of raising an index error.  This was a bug
caused by eager optimizing.

\item {} 
the i18n extension looks up \emph{foo.ugettext} now followed by \emph{foo.gettext}
if an translations object is installed.  This makes dealing with custom
translations classes easier.

\item {} 
fixed a confusing behavior with conditional extending.  loops were partially
executed under some conditions even though they were not part of a visible
area.

\item {} 
added \emph{sort} filter that works like \emph{dictsort} but for arbitrary sequences.

\item {} 
fixed a bug with empty statements in macros.

\item {} 
implemented a bytecode cache system.  ({\hyperref[api:bytecode-cache]{\emph{Bytecode Cache}}})

\item {} 
the template context is now weakref-able

\item {} 
inclusions and imports ``with context'' forward all variables now, not only
the initial context.

\item {} 
added a cycle helper called \emph{cycler}.

\item {} 
added a joining helper called \emph{joiner}.

\item {} 
added a \emph{compile\_expression} method to the environment that allows compiling
of Jinja expressions into callable Python objects.

\item {} 
fixed an escaping bug in urlize

\end{itemize}


\section{Version 2.0}
\label{changelog:version-2-0}
(codename jinjavitus, released on July 17th 2008)
\begin{itemize}
\item {} 
the subscribing of objects (looking up attributes and items) changed from
slightly.  It's now possible to give attributes or items a higher priority
by either using dot-notation lookup or the bracket syntax.  This also
changed the AST slightly.  \emph{Subscript} is gone and was replaced with
{\hyperref[extensions:jinja2.nodes.Getitem]{\code{Getitem}}} and {\hyperref[extensions:jinja2.nodes.Getattr]{\code{Getattr}}}.

For more information see {\hyperref[templates:notes-on-subscriptions]{\emph{the implementation details}}}.

\item {} 
added support for preprocessing and token stream filtering for extensions.
This would allow extensions to allow simplified gettext calls in template
data and something similar.

\item {} 
added {\hyperref[api:jinja2.environment.TemplateStream.dump]{\code{jinja2.environment.TemplateStream.dump()}}}.

\item {} 
added missing support for implicit string literal concatenation.
\code{\{\{ "foo" "bar" \}\}} is equivalent to \code{\{\{ "foobar" \}\}}

\item {} 
\emph{else} is optional for conditional expressions.  If not given it evaluates
to \emph{false}.

\item {} 
improved error reporting for undefined values by providing a position.

\item {} 
\emph{filesizeformat} filter uses decimal prefixes now per default and can be
set to binary mode with the second parameter.

\item {} 
fixed bug in finalizer

\end{itemize}


\section{Version 2.0rc1}
\label{changelog:version-2-0rc1}
(no codename, released on June 9th 2008)
\begin{itemize}
\item {} 
first release of Jinja2

\end{itemize}



\renewcommand{\indexname}{Index}
\printindex
\end{document}
