Jinja 2 templating language Documentation

class

jinja2.nodes.Compare(expr, ops)

Compares an expression with some other expressions. ops must be a list of

Operands.

Node type

class

jinja2.nodes.Concat(nodes)

Concatenates the list of expressions provided after converting them to unicode.

Node type

class

jinja2.nodes.CondExpr(test, expr1, expr2)

A conditional expression (inline if expression). (

{{ foo if bar else baz }})

Node type

’load’ ctx and will return the current Context object.

class

jinja2.nodes.ContextReference

Returns the current template context. It can be used like a

Name node, with a

Here an example that assigns the current template name to a variable named foo:

Assign(Name( 'foo' , ctx= 'store' ),

Getattr(ContextReference(), 'name' ))

Node type

class

jinja2.nodes.EnvironmentAttribute(name)

Loads an attribute from the environment object. This is useful for extensions that want to call a callback stored on the environment.

Node type

attr() method on an extension.

class

jinja2.nodes.ExtensionAttribute(identifier, name)

Returns the attribute of an extension bound to the environment. The identifier is the identifier of the

Extension.

This node is usually constructed by calling the

Node type

class

jinja2.nodes.Filter(node, name, args, kwargs, dyn_args, dyn_kwargs)

This node applies a filter on an expression. name is the name of the filter, the rest of the fields are the same as for

{1: 2, 3: 4}. The items must be a list of Pair nodes.

class

jinja2.nodes.InternalName(name)

An internal name in the compiler. You cannot create these nodes yourself but the parser provides a

Literal

class

jinja2.nodes.Dict(items)

Any dict literal such as

Node type

Literal

class

jinja2.nodes.List(items)

Literal

class

class

jinja2.nodes.Slice(start, stop, step)

Represents a slice object. This must only be used as argument for

Subscript.

Node type

part of the i18n Extension extension.

class

jinja2.nodes.Test(node, name, args, kwargs, dyn_args, dyn_kwargs)

jinja2.nodes.Operand(op, expr)

jinja2.nodes.EvalContextModifier(options)

Modifies the eval context. For each option that should be modified, a

Keyword

has to be added to the options list.

Example to change the autoescape setting:

EvalContextModifier(options=[Keyword( 'autoescape' , Const( True ))])

Node type

Stmt

class

jinja2.nodes.ScopedEvalContextModifier(options, body)

Modifies the eval context and reverts it later.

jinja2.nodes.For(target, iter, body, else_, test, recursive)

The for loop. target is the target for the iteration (usually a

Name or Tuple), iter the

iterable. body is a list of nodes that are used as loop-body, and else_ a list of nodes for the else block. If no else node exists it has to be an empty list.

For filtered nodes an expression can be stored as test, otherwise None.

Node type

Stmt

class

jinja2.nodes.FromImport(template, names, 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 not use the subscript callback of the interface.

jinja2.nodes.With(targets, values, body)

Specific node for with statements. In older versions of Jinja the with statement was implemented on the base of the Scope node instead.

New in version 2.9.3.

Node type

Stmt

class

jinja2.nodes.Template(body)

Node that represents a template. This must be the outermost node that is passed to the compiler.

Node type

Node

exception

jinja2.nodes.Impossible

Raised if the node could not perform a requested action.

CHAPTER

Integration

Jinja2 provides some code for integration into other tools such as frameworks, the

Babel library or your favourite editor for fancy code highlighting. This is a brief description of whats included.

Files to help integration are available here.

Babel Integration

Jinja provides support for extracting gettext messages from templates via a Babel extractor entry point called jinja2.ext.babel_extract. The Babel support is implemented as

Gettext messages extracted from both trans tags and code expressions.

To extract gettext messages from templates, the project needs a Jinja2 section in its

Babel extraction method mapping file :

[jinja2: **/templates/**.html]

encoding = utf-8

The syntax related options of the

Environment are also available as configuration values in the mapping file. For example to tell the extraction that templates use

% as line_statement_prefix you can use this code:

[jinja2: **/templates/**.html]

encoding = utf-8 line_statement_prefix = %

Extensions may also be defined by passing a comma separated list of import paths as

extensions value. The i18n extension is added automatically.

Changed in version 2.7: Until 2.7 template syntax errors were always ignored. This was done since many people are dropping non template html files into the templates folder and it would randomly fail. The assumption was that testsuites will catch

syntax errors in templates anyways. If you don’t want that behavior you can add silent=false to the settings and exceptions are propagated.

Pylons

With Pylons 0.9.7 onwards it’s incredible easy to integrate Jinja into a Pylons powered application.

The template engine is configured in config/environment.py. The configuration for Jinja2 looks something like that:

from jinja2 import

Environment, PackageLoader config[ 'pylons.app_globals' ].jinja_env = Environment( loader=PackageLoader( 'yourapplication' , 'templates' )

)

After that you can render Jinja templates by using the render_jinja function from the pylons.templating module.

Additionally it’s a good idea to set the Pylons’ c object into strict mode. Per default any attribute to not existing attributes on the c object return an empty string and not an undefined object. To change this just use this snippet and add it into your config/environment.py: config[ 'pylons.strict_c' ] = True

TextMate

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.

Vim

A syntax plugin for Vim exists in the Vim-scripts directory as well as the ext folder at the root of the Jinja2 project.

The script supports Jinja1 and Jinja2. Once installed two file types are available jinja and htmljinja. The first one for text based templates, the latter for HTML templates.

Copy the files into your syntax folder.

100

CHAPTER

Switching from other Template Engines

If you have used a different template engine in the past and want to switch to Jinja2 here is a small guide that shows the basic syntactic and semantic changes between some common, similar text template engines for Python.

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.

API

Loaders

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 loader API.

Loading templates from strings

In the past it was possible to generate templates from a string with the default environment configuration by using jinja.from_string.

Jinja2 provides a

Template class that can be used to do the same, but with optional additional configuration.

Automatic unicode conversion

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 has to use unicode internally everywhere or make sure that Jinja2 only gets unicode strings passed.

i18n

Jinja1 used custom translators for internationalization. i18n is now available as

Jinja2 extension and uses a simpler, more gettext friendly interface and has sup-

port for babel. For more details see i18n Extension.

101

Internal methods

Jinja1 exposed a few internal methods on the environment object such as call_function, 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.

Sandbox

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

SandboxedEnvironment.

Context

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.

Filters and Tests

Filters and tests are regular functions now. It’s no longer necessary and allowed to use factory functions.

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 rendertemplate is gone now, include can be used instead. Includes no longer import macros and variable assignments, for that the new import tag is used.

This concept is explained in the Import documentation.

Another small change happened in the for-tag. The special loop variable doesn’t have

a parent attribute, instead you have to alias the loop yourself. See Accessing the parent

Loop for more details.

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.

Method Calls

In Django method calls work implicitly, while Jinja requires the explicit Python syntax.

Thus this Django code:

102

for

page

user.get_created_pages

...

endfor

...looks like this in Jinja:

for

page

user.get_created_pages() %}

...

endfor

This allows you to pass variables to the method, which is not possible in Django. This syntax is also used for macros.

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:

{{ items| join :", " }} looks like this in Jinja2:

It is a bit more verbose, but it allows different types of arguments - including variables

- and more than one of them.

Tests

In addition to filters there also are tests you can perform using the is operator. Here are some examples:

user.user_id

odd %}

{{ user.username| e }} is odd

else

%} hmm.

{{ user.username| e }} looks pretty normal

endif

Loops

For loops work very similarly to Django, but notably the Jinja2 special variable for the loop context is called loop, not forloop as in Django.

In addition, the Django empty argument is called else in Jinja2. For example, the Django template:

for

item

items %}

103

empty

No items!

endfor

...looks like this in Jinja2:

for

item

items %}

else

No items!

endfor

Cycle

The

{% cycle %} tag does not exist in Jinja2; however, you can achieve the same output by using the cycle method on the loop context special variable.

The following Django template:

for

user

users %}

class = " {%

cycle

'odd' 'even' %} " > {{ user }} </

endfor

...looks like this in Jinja2:

for

user

users %}

class = " {{ loop .cycle( 'odd' , 'even' ) }} " > {{ user }} </

endfor

There is no equivalent of

{% cycle ... as variable %}.

Mako

If you have used Mako so far and want to switch to Jinja2 you can configure Jinja2 to look more like Mako: env = Environment( '<%' , '%>' , '${' , '}' , '<%doc>' , '</%doc>' , '%' , '##' )

With an environment configured 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 (which are called macros in Jinja2) and template inheritance is different too. The following Mako template:

<% inherit file= "layout.html" />

<% def name= "title()" > Page Title </% def >

for

item

list :

> ${ item } </

104

endfor

Looks like this in Jinja2 with the above configuration:

<% extends "layout.html" %>

<% block title %> Page Title <% endblock %>

<% block body %>

for

item

list :

> ${ item } </

endfor

<% endblock %>

105

106

CHAPTER

Tips and Tricks

This part of the documentation shows some tips and tricks for Jinja2 templates.

Null-Master Fallback

Jinja2 supports dynamic inheritance and does not distinguish between parent and child template as long as no extends tag is visited. While this leads to the surprising behavior that everything before the first extends tag including whitespace is printed out instead of being ignored, 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 to put the extends tag into an if tag to only extend from the layout template if the 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 standalone set to True a very basic HTML skeleton is added:

if not

standalone %}{%

extends

'master.html' %}{%

endif

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

title

> {%

block

title %} The Page Title {%

endblock

%} </

title

link

rel = "stylesheet" href = "style.css" type = "text/css" >

block

body %}

>This is the page body.</

endblock

Alternating Rows

If you want to have different styles for each row of a table or list you can use the cycle method on the loop object:

for

row

rows %}

class = " {{ loop .cycle( 'odd' , 'even' ) }} " > {{ row }} </

107

endfor

> cycle can take an unlimited amount of strings. Each time this tag is encountered the next item from the list is rendered.

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 blocks 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:

extends

"layout.html" %}

set

active_page = "index" %}

The layout template can then access active_page. Additionally it makes sense to define a default for that variable:

set

navigation_bar = [

( '/' , 'index' , 'Index' ),

( '/downloads/' , 'downloads' , 'Downloads' ),

( '/about/' , 'about' , 'About' )

] %}

set

active_page = active_page| default ( 'index' ) %}

...

id = "navigation" >

for

href, id, caption

navigation_bar %}

id == active_page %} class = "active" {%

endif

%} ><

href = " {{ href| e }} " > {{ caption| e }} </

></

endfor

...

Accessing the parent Loop

The special 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:

table

for

row

table %}

set

rowloop = loop %}

for

cell

row %}

id = "cell{{ rowloop.index

}} {{ loop .index

}} " > {{ cell }} </

endfor

108

endfor

table

109

110

Part II

ADDITIONAL INFORMATION

111

112

CHAPTER

Frequently Asked Questions

This page answers some of the often asked questions about Jinja.

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 city in Uganda.

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 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.

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.

113

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:

load

comments %}

get_latest_comments

latest_comments %}

for

comment

latest_comments %}

...

endfor

You will most likely provide an object with attributes to retrieve comments from the database:

for

comment

models.comments.latest( 10 ) %}

...

endfor

Or directly provide the model for quick testing:

for

comment

Comment.objects.order_by( '-pub_date' )[: 10 ] %}

...

endfor

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!

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 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.

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

114

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

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.

Why is the Context immutable?

When writing a 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:

set

comments = get_latest_comments() %}

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.

If you are working in the Google AppEngine development server you can whitelist the ctypes module to restore the tracebacks. This however won’t work in production environments: import os if os.environ.get('SERVER_SOFTWARE', '').startswith('Dev'): from google.appengine.tools.devappserver2.python import sandbox sandbox._WHITE_LIST_C_MODULES += ['_ctypes', 'gestalt']

Credit for this snippet goes to Thomas Johansson

115

Why is there no Python 2.3/2.4/2.5/3.1/3.2 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 Jinja 1 or other templating engines that still support 2.3.

Python 2.4/2.5/3.1/3.2 support was removed when we switched to supporting

Python 2 and 3 by the same sourcecode (without using 2to3). It was required to drop support because only Python 2.6/2.7 and >=3.3 support byte and unicode literals in a way compatible to each other version. If you really need support for older Python 2

(or 3) versions, you can just use Jinja2 2.6.

My Macros are overridden by something

In some situations the Jinja scoping appears arbitrary: layout.tmpl:

macro

foo() %} LAYOUT {%

endmacro

block

body %}{%

endblock

%} child.tmpl:

extends

'layout.tmpl' %}

macro

foo() %} CHILD {%

endmacro

block

body %}{{ foo() }}{%

endblock

This will print

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.

116

CHAPTER

Jinja2 Changelog

Version 2.10

(feature release, release date to be decided)

• Added a new extension node called OverlayScope which can be used to create an unoptimized scope that will look up all variables from a derived context.

• Added an in test that works like the in operator. This can be used in combination with reject and select.

Version 2.9.5

(bugfix release, released on January 28th 2017)

• Restored the original repr of the internal _GroupTuple because this caused issues with ansible and it was an unintended change. (#654)

• Added back support for custom contexts that override the old resolve method since it was hard for people to spot that this could cause a regression.

• Correctly use the buffer for the else block of for loops. This caused invalid syntax errors to be caused on 2.x and completely wrong behavior on Python 3 (#669)

• Resolve an issue where the {% extends %} tag could not be used with async environments. (#668)

• Reduce memory footprint slightly by reducing our unicode database dump we use for identifier matching on Python 3 (#666)

• Fixed autoescaping not working for macros in async compilation mode. (#671)

117

Version 2.9.4

(bugfix release, released on January 10th 2017)

• Solved some warnings for string literals. (#646)

• Increment the bytecode cache version which was not done due to an oversight before.

• Corrected bad code generation and scoping for filtered loops. (#649)

• Resolved an issue where top-level output silencing after known extend blocks could generate invalid code when blocks where contained in if statements. (#651)

• Made the truncate.leeway default configurable to improve compatibility with older templates.

Version 2.9.3

(bugfix release, released on January 8th 2017)

• Restored the use of blocks in macros to the extend that was possible before. On

Python 3 it would render a generator repr instead of the block contents. (#645)

• Set a consistent behavior for assigning of variables in inner scopes when the variable is also read from an outer scope. This now sets the intended behavior in all situations however it does not restore the old behavior where limited assignments to outer scopes was possible. For more information and a discussion see

#641

• Resolved an issue where block scoped would not take advantage of the new scoping rules. In some more exotic cases a variable overriden in a local scope would not make it into a block.

• Change the code generation of the with statement to be in line with the new scoping rules. This resolves some unlikely bugs in edge cases. This also introduces a new internal With node that can be used by extensions.

Version 2.9.2

(bugfix release, released on January 8th 2017)

• Fixed a regression that caused for loops to not be able to use the same variable for the target as well as source iterator. (#640)

• Add support for a previously unknown behavior of macros. It used to be possible in some circumstances to explicitly provide a caller argument to macros.

While badly buggy and unintended it turns out that this is a common case that gets copy pasted around. To not completely break backwards compatibility with

118

the most common cases it’s now possible to provide an explicit keyword argument for caller if it’s given an explicit default. (#642)

Version 2.9.1

(bugfix release, released on January 7th 2017)

• Resolved a regression with call block scoping for macros. Nested caller blocks that used the same identifiers as outer macros could refer to the wrong variable incorrectly.

Version 2.9

(codename Derivation, released on January 7th 2017)

• Change cache key definition in environment. This fixes a performance regression introduced in 2.8.

• Added support for generator_stop on supported Python versions (Python 3.5 and later)

• Corrected a long standing issue with operator precedence of math operations not being what was expected.

• Added support for Python 3.6 async iterators through a new async mode.

• Added policies for filter defaults and similar things.

• urlize now sets “rel noopener” by default.

• Support attribute fallback for old-style classes in 2.x.

• Support toplevel set statements in extend situations.

• Restored behavior of Cycler for Python 3 users.

• Subtraction now follows the same behavior as other operators on undefined values.

• map and friends will now give better error messages if you forgot to quote the parameter.

• Depend on MarkupSafe 0.23 or higher.

• Improved the truncate filter to support better truncation in case the string is barely truncated at all.

• Change the logic for macro autoescaping to be based on the runtime autoescaping information at call time instead of macro define time.

• Ported a modified version of the tojson filter from Flask to Jinja2 and hooked it up with the new policy framework.

119

• Block sets are now marked safe by default.

• On Python 2 the asciification of ASCII strings can now be disabled with the compiler.ascii_str policy.

• Tests now no longer accept an arbitrary expression as first argument but a restricted one. This means that you can now properly use multiple tests in one expression without extra parentheses. In particular you can now write foo is divisibleby 2 or foo is divisibleby 3 as you would expect.

• Greatly changed the scoping system to be more consistent with what template designers and developers expect. There is now no more magic difference between the different include and import constructs. Context is now always propagated the same way. The only remaining differences is the defaults for with context and without context.

• The with and autoescape tags are now built-in.

• Added the new select_autoescape function which helps configuring better autoescaping easier.

Version 2.8.2

(bugfix release, unreleased)

• Fixed a runtime error in the sandbox when attributes of async generators were accessed.

Version 2.8.1

(bugfix release, released on December 29th 2016)

• Fixed the for_qs flag for urlencode.

• Fixed regression when applying int to non-string values.

• SECURITY: if the sandbox mode is used format expressions are now sandboxed with the same rules as in Jinja. This solves various information leakage problems that can occur with format strings.

Version 2.8

(codename Replacement, released on July 26th 2015)

• Added target parameter to urlize function.

• Added support for followsymlinks to the file system loader.

• The truncate filter now counts the length.

120

• Added equalto filter that helps with select filters.

• Changed cache keys to use absolute file names if available instead of load names.

• Fixed loop length calculation for some iterators.

• Changed how Jinja2 enforces strings to be native strings in Python 2 to work when people break their default encoding.

• Added

make_logging_undefined() which returns an undefined object that logs

failures into a logger.

• If unmarshalling of cached data fails the template will be reloaded now.

• Implemented a block set tag.

• Default cache size was increased to 400 from a low 50.

• Fixed is number test to accept long integers in all Python versions.

• Changed is number to accept Decimal as a number.

• Added a check for default arguments followed by non-default arguments. This change makes

{% macro m(x, y=1, z) %}...{% endmacro %} a syntax error.

The previous behavior for this code was broken anyway (resulting in the default value being applied to y).

• Add ability to use custom subclasses of jinja2.compiler.CodeGenerator and jinja2.runtime.Context by adding two new attributes to the environment

(code_generator_class and context_class) (pull request

#404).

• added support for context/environment/evalctx decorator functions on the finalize callback of the environment.

• escape query strings for urlencode properly. Previously slashes were not escaped in that place.

• Add ‘base’ parameter to ‘int’ filter.

Version 2.7.3

(bugfix release, released on June 6th 2014)

• Security issue: Corrected the security fix for the cache folder. This fix was provided by RedHat.

Version 2.7.2

(bugfix release, released on January 10th 2014)

• Prefix loader was not forwarding the locals properly to inner loaders. This is now fixed.

121

• Security issue: Changed the default folder for the filesystem cache to be user specific and read and write protected on UNIX systems. See Debian bug 734747 for more information.

Version 2.7.1

(bugfix release, released on August 7th 2013)

• Fixed a bug with call_filter not working properly on environment and context filters.

• Fixed lack of Python 3 support for bytecode caches.

• Reverted support for defining blocks in included templates as this broke existing templates for users.

• Fixed some warnings with hashing of undefineds and nodes if Python is run with warnings for Python 3.

• Added support for properly hashing undefined objects.

• Fixed a bug with the title filter not working on already uppercase strings.

Version 2.7

(codename Translation, released on May 20th 2013)

• Choice and prefix loaders now dispatch source and template lookup separately in order to work in combination with module loaders as advertised.

• Fixed filesizeformat.

• Added a non-silent option for babel extraction.

• Added urlencode filter that automatically quotes values for URL safe usage with utf-8 as only supported encoding. If applications want to change this encoding they can override the filter.

• Added keep-trailing-newline configuration to environments and templates to optionally preserve the final trailing newline.

• Accessing last on the loop context no longer causes the iterator to be consumed into a list.

• Python requirement changed: 2.6, 2.7 or >= 3.3 are required now, supported by same source code, using the “six” compatibility library.

• Allow contextfunction and other decorators to be applied to __call__.

• Added support for changing from newline to different signs in the wordwrap filter.

• Added support for ignoring memcache errors silently.

122

• Added support for keeping the trailing newline in templates.

• Added finer grained support for stripping whitespace on the left side of blocks.

• Added map, select, reject, selectattr and rejectattr filters.

• Added support for loop.depth to figure out how deep inside a recursive loop the code is.

• Disabled py_compile for pypy and python 3.

Version 2.6

(codename Convolution, released on July 24th 2011)

• internal attributes now raise an internal attribute error now instead of returning an undefined. This fixes problems when passing undefined objects to Python semantics expecting APIs.

• traceback support now works properly for PyPy. (Tested with 1.4)

• implemented operator intercepting for sandboxed environments. This allows application developers to disable builtin operators for better security. (For instance limit the mathematical operators to actual integers instead of longs)

• groupby filter now supports dotted notation for grouping by attributes of attributes.

• scoped blocks now properly treat toplevel assignments and imports. Previously an import suddenly “disappeared” in a scoped block.

• automatically detect newer Python interpreter versions before loading code from bytecode caches to prevent segfaults on invalid opcodes. The segfault in earlier

Jinja2 versions here was not a Jinja2 bug but a limitation in the underlying Python interpreter. If you notice Jinja2 segfaulting in earlier versions after an upgrade of the Python interpreter you don’t have to upgrade, it’s enough to flush the bytecode cache. This just no longer makes this necessary, Jinja2 will automatically detect these cases now.

• the sum filter can now sum up values by attribute. This is a backwards incompatible change. The argument to the filter previously was the optional starting index which defaults to zero. This now became the second argument to the function because it’s rarely used.

• like sum, sort now also makes it possible to order items by attribute.

• like sum and sort, join now also is able to join attributes of objects as string.

• the internal eval context now has a reference to the environment.

• added a mapping test to see if an object is a dict or an object with a similar interface.

123

Version 2.5.5

(re-release of 2.5.4 with built documentation removed for filesize.

Released on October 18th 2010)

• built documentation is no longer part of release.

Version 2.5.4

(bugfix release, released on October 17th 2010)

• Fixed extensions not loading properly with overlays.

• Work around a bug in cpython for the debugger that causes segfaults on 64bit big-endian architectures.

Version 2.5.3

(bugfix release, released on October 17th 2010)

• 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)”.

Version 2.5.2

(bugfix release, released on August 18th 2010)

• improved setup.py script to better work with assumptions people might still have from it (

--with-speedups).

• fixed a packaging error that excluded the new debug support.

Version 2.5.1

(bugfix release, released on August 17th 2010)

• 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)

• improved performance of macro calls slightly.

• babel extraction can now properly extract newstyle gettext calls.

124

• using the variable num in newstyle gettext for something else than the pluralize count will no longer raise a

KeyError.

• 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

• fixed an issue with unary operators having the wrong precedence.

Version 2.5

(codename Incoherence, released on May 29th 2010)

• improved the sort filter (should have worked like this for a long time) by adding support for case insensitive searches.

• fixed a bug for getattribute constant folding.

• support for newstyle gettext translations which result in a nicer in-template user

interface and more consistent catalogs. (Newstyle Gettext)

• it’s now possible to register extensions after an environment was created.

Version 2.4.1

(bugfix release, released on April 20th 2010)

• fixed an error reporting bug for undefineds.

Version 2.4

(codename Correlation, released on April 13th 2010)

• 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.

• added a

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.

• the _speedups C extension now supports Python 3.

• added support for autoescaping toggling sections and support for evaluation

contexts (Evaluation Context).

• extensions have a priority now.

125

Version 2.3.1

(bugfix release, released on February 19th 2010)

• fixed an error reporting bug on all python versions

• fixed an error reporting bug on Python 2.4

Version 2.3

(3000 Pythons, released on February 10th 2010)

• fixes issue with code generator that causes unbound variables to be generated if set was used in if-blocks and other small identifier problems.

• include tags are now able to select between multiple templates and take the first that exists, if a list of templates is given.

• 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).

• greatly improved error message reporting (#339)

• implicit tuple expressions can no longer be totally empty. This change makes

{% if %}...{% endif %} a syntax error now. (#364)

• added support for translator comments if extracted via babel.

• added with-statement extension.

• experimental Python 3 support.

Version 2.2.1

(bugfix release, released on September 14th 2009)

• fixes some smaller problems for Jinja2 on Jython.

Version 2.2

(codename Kong, released on September 13th 2009)

• Include statements can now be marked with ignore missing to skip non existing templates.

• Priority of not raised. It’s now possible to write not foo in bar as an alias to foo not in bar like in python. Previously the grammar required parentheses (not (foo in bar)) which was odd.

126

• Fixed a bug that caused syntax errors when defining macros or using the {% call

%} tag inside loops.

• Fixed a bug in the parser that made

{{ foo[1, 2] }} impossible.

• Made it possible to refer to names from outer scopes in included templates that were unused in the callers frame (#327)

• Fixed a bug that caused internal errors if names where used as iteration variable and regular variable after the loop if that variable was unused before the loop.

(#331)

• Added support for optional scoped modifier to blocks.

• Added support for line-comments.

• Added the meta module.

• Renamed (undocumented) attribute “overlay” to “overlayed” on the environment because it was clashing with a method of the same name.

• speedup extension is now disabled by default.

Version 2.1.1

(Bugfix release)

• Fixed a translation error caused by looping over empty recursive loops.

Version 2.1

(codename Yasuzo, released on November 23rd 2008)

• 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.

• fixed a bug with the i18n extension that caused the explicit pluralization block to look up the wrong variable.

• fixed a limitation in the lexer that made

{{ foo.0.0 }} impossible.

• 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.

• the i18n extension looks up foo.ugettext now followed by foo.gettext if an translations object is installed. This makes dealing with custom translations classes easier.

• fixed a confusing behavior with conditional extending. loops were partially executed under some conditions even though they were not part of a visible area.

• added sort filter that works like dictsort but for arbitrary sequences.

127

• fixed a bug with empty statements in macros.

• implemented a bytecode cache system. (Bytecode Cache)

• the template context is now weakref-able

• inclusions and imports “with context” forward all variables now, not only the initial context.

• added a cycle helper called cycler.

• added a joining helper called joiner.

• added a compile_expression method to the environment that allows compiling of

Jinja expressions into callable Python objects.

• fixed an escaping bug in urlize

Version 2.0

(codename jinjavitus, released on July 17th 2008)

• 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. Subscript is gone and was replaced with

Getitem and Getattr.

For more information see the implementation details.

• 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.

• added

jinja2.environment.TemplateStream.dump().

• added missing support for implicit string literal concatenation.

{{ "foo" "bar"

}} is equivalent to {{ "foobar" }}

• else is optional for conditional expressions. If not given it evaluates to false.

• improved error reporting for undefined values by providing a position.

• filesizeformat filter uses decimal prefixes now per default and can be set to binary mode with the second parameter.

• fixed bug in finalizer

Version 2.0rc1

(no codename, released on June 9th 2008)

• first release of Jinja2

128

Index

Symbols

_fail_with_undefined_error()

(jinja2.Undefined method), 19

_undefined_exception (jinja2.Undefined

attribute), 19

_undefined_hint (jinja2.Undefined

at-

tribute), 19

_undefined_name (jinja2.Undefined at-

tribute), 19

_undefined_obj (jinja2.Undefined

at-

tribute), 19

A

abs() (built-in function), 64

Add (class in jinja2.nodes), 91

add_extension()

method), 12

(jinja2.Environment

And (class in jinja2.nodes), 91 as_const() (jinja2.nodes.Expr method), 91

Assign (class in jinja2.nodes), 95

AssignBlock (class in jinja2.nodes), 95

attr() (built-in function), 64

attr() (jinja2.ext.Extension method), 87

autoescape (jinja2.EvalContext attribute),

B

BaseLoader (class in jinja2), 22

batch() (built-in function), 64

BinExpr (class in jinja2.nodes), 91

Block (class in jinja2.nodes), 96

blocks (jinja2.Context attribute), 22

blocks (jinja2.Template attribute), 36

Break (class in jinja2.nodes), 96

Bucket (class in jinja2.bccache), 26

bytecode_from_string()

(jinja2.bccache.Bucket method), 26

bytecode_to_string()

(jinja2.bccache.Bucket method), 26

BytecodeCache (class in jinja2), 25

C

Call (class in jinja2.nodes), 92

call() (jinja2.runtime.Context method), 22

call_binop() (jinja2.sandbox.SandboxedEnvironment

method), 39

call_method()

method), 87

(jinja2.ext.Extension

call_unop() (jinja2.sandbox.SandboxedEnvironment

method), 39

callable() (built-in function), 72

CallBlock (class in jinja2.nodes), 96

can_assign() (jinja2.nodes.Expr method),

capitalize() (built-in function), 65 center() (built-in function), 65

ChoiceLoader (class in jinja2), 25

clear() (jinja2.BytecodeCache method), 26

clear_caches() (in module jinja2), 30

code (jinja2.Bucket attribute), 26

code_generator_class (jinja2.Environment

attribute), 11

Compare (class in jinja2.nodes), 92

compile_expression() (jinja2.Environment

method), 12

compile_templates() (jinja2.Environment

method), 13

Concat (class in jinja2.nodes), 92

CondExpr (class in jinja2.nodes), 92

Const (class in jinja2.nodes), 93

129

Context (class in jinja2.runtime), 21

context_class (jinja2.Environment

at-

tribute), 11

contextfilter() (in module jinja2), 29

contextfunction() (in module jinja2), 30

ContextReference (class in jinja2.nodes),

Continue (class in jinja2.nodes), 96

count_newlines() (in module jinja2.lexer),

current (cycler attribute), 75

current (jinja2.ext.TokenStream attribute),

cycler (built-in class), 74

D

DebugUndefined (class in jinja2), 19

default() (built-in function), 65

default_binop_table

environmentfilter() (in module jinja2), 29

environmentfunction() (in module jinja2),

eos (jinja2.lexer.TokenStream attribute), 89

equalto() (built-in function), 73

escape() (built-in function), 65

escape() (in module jinja2), 30

escape() (jinja2.Markup class method), 31

escaped() (built-in function), 73

eval_ctx (jinja2.Context attribute), 22

EvalContext (class in jinja2.nodes), 34

evalcontextfilter() (in module jinja2), 29

evalcontextfunction() (in module jinja2),

EvalContextModifier

jinja2.nodes), 96

(class in

even() (built-in function), 73

expect() (jinja2.lexer.TokenStream

method), 89

Expr (class in jinja2.nodes), 91

default_unop_table

defined() (built-in function), 72

Dict (class in jinja2.nodes), 94

dict() (built-in function), 74

DictLoader (class in jinja2), 24

dictsort() (built-in function), 65

extend() (jinja2.Environment method), 13

Extends (class in jinja2.nodes), 96

Extension (class in jinja2.ext), 86

ExtensionAttribute (class in jinja2.nodes),

extract_translations() (jinja2.Environment

disable_buffering()

(jinja2.environment.TemplateStream

method), 16

F

Div (class in jinja2.nodes), 91

fail() (jinja2.parser.Parser method), 88

divisibleby() (built-in function), 73

filename (jinja2.ext.Parser attribute), 87

dump() (jinja2.environment.TemplateStream

filename (jinja2.Template attribute), 15

method), 16

filename (jinja2.TemplateSyntaxError atdump_bytecode() (jinja2.BytecodeCache

filesizeformat() (built-in function), 65

method), 26

FileSystemBytecodeCache (class in jinja2),

E

enable_buffering()

method), 82

FileSystemLoader (class in jinja2), 23

(jinja2.environment.TemplateStream

Filter (class in jinja2.nodes), 93

method), 17

Environment (class in jinja2), 9

filter_stream()

method), 87

(jinja2.ext.Extension

environment (jinja2.Bucket attribute), 26

environment (jinja2.Context attribute), 21

EnvironmentAttribute (class in

jinja2.nodes), 92

FilterBlock (class in jinja2.nodes), 96

filters (jinja2.Environment attribute), 11

find() (jinja2.nodes.Node method), 90 find_all() (jinja2.nodes.Node method), 90

130

find_referenced_templates() (in module

jinja2.meta), 37

find_undeclared_variables() (in module

jinja2.meta), 37

first() (built-in function), 65 float() (built-in function), 65

FloorDiv (class in jinja2.nodes), 91

For (class in jinja2.nodes), 96

forceescape() (built-in function), 66 format() (built-in function), 66

free_identifier()

FromImport (class in jinja2.nodes), 97

(jinja2.parser.Parser

from_string() (jinja2.Environment

method), 13

FunctionLoader (class in jinja2), 24

G

generate() (jinja2.Template method), 15

generate_async() (jinja2.Template

method), 16

ImmutableSandboxedEnvironment (class

in jinja2.sandbox), 40

Import (class in jinja2.nodes), 97

ImportedName (class in jinja2.nodes), 93

Impossible, 98

Include (class in jinja2.nodes), 97

indent() (built-in function), 66

install_gettext_callables()

(jinja2.Environment

install_gettext_translations()

(jinja2.Environment

method), method), install_null_translations()

(jinja2.Environment

method),

int() (built-in function), 66

intercepted_binops

(jinja2.sandbox.SandboxedEnvironment

Getattr (class in jinja2.nodes), 93

intercepted_unops

method), 28

get_all() (jinja2.runtime.Context method),

get_exported() (jinja2.runtime.Context

method), 22

get_or_select_template()

(jinja2.Environment

method),

get_source() (jinja2.BaseLoader method),

get_template()

method), 14

(jinja2.Environment

Getitem (class in jinja2.nodes), 93

globals (jinja2.Environment attribute), 11

globals (jinja2.Template attribute), 15

greaterthan() (built-in function), 73

groupby() (built-in function), 66

H

Helper (class in jinja2.nodes), 95

I

identifier (jinja2.ext.Extension attribute),

If (class in jinja2.nodes), 97

InternalName (class in jinja2.nodes), 93

is_internal_attribute() (in module

jinja2.sandbox), 41

is_safe_attribute()

(jinja2.sandbox.SandboxedEnvironment

method), 40

is_safe_callable()

(jinja2.sandbox.SandboxedEnvironment

method), 40

is_undefined() (in module jinja2), 30

is_up_to_date (jinja2.Template attribute),

iter_child_nodes()

method), 90

(jinja2.nodes.Node

iter_fields() (jinja2.nodes.Node method),

iterable() (built-in function), 73

J

jinja2 (module), 7, 116

jinja2.ext (module), 84

jinja2.nodes (module), 90

jinja2.sandbox (module), 39

join() (built-in function), 67

join_path() (jinja2.Environment method),

131

joiner (built-in class), 75

K

key (jinja2.Bucket attribute), 26

Keyword (class in jinja2.nodes), 95

Mod (class in jinja2.nodes), 91

modifies_known_mutable() (in module

jinja2.sandbox), 41

module (jinja2.Template attribute), 16

ModuleLoader (class in jinja2), 25

Mul (class in jinja2.nodes), 91

L N

last() (built-in function), 67 length() (built-in function), 67

lessthan() (built-in function), 73

lex() (jinja2.Environment method), 36

lineno (jinja2.ext.Token attribute), 89

lineno (jinja2.TemplateSyntaxError

at-

lipsum() (built-in function), 74

List (class in jinja2.nodes), 94

list() (built-in function), 67

list_templates() (jinja2.Environment

method), 14

Literal (class in jinja2.nodes), 93

load() (jinja2.BaseLoader method), 23

load_bytecode() (jinja2.bccache.Bucket

method), 27

load_bytecode() (jinja2.BytecodeCache

method), 26

Name (class in jinja2.nodes), 94

name (jinja2.Context attribute), 22

name (jinja2.ext.Parser attribute), 87

name (jinja2.Template attribute), 15

name (jinja2.TemplateSyntaxError

at-

Neg (class in jinja2.nodes), 95

new_context() (jinja2.Template method),

next() (cycler method), 75

next() (jinja2.lexer.TokenStream method),

next_if() (jinja2.lexer.TokenStream

method), 89

Node (class in jinja2.nodes), 90

none() (built-in function), 73

Not (class in jinja2.nodes), 95

number() (built-in function), 73

look() (jinja2.lexer.TokenStream method),

lower() (built-in function), 67, 73

O

odd() (built-in function), 73

Operand (class in jinja2.nodes), 95

M

Macro (class in jinja2.nodes), 97

make_logging_undefined() (in module

jinja2), 20

make_module() (jinja2.Template method),

Or (class in jinja2.nodes), 92

Output (class in jinja2.nodes), 97

overlay() (jinja2.Environment method), 11

P

map() (built-in function), 67

mapping() (built-in function), 73

MarkSafe (class in jinja2.nodes), 94

MarkSafeIfAutoescape

jinja2.nodes), 94

(class in

PackageLoader (class in jinja2), 24

Pair (class in jinja2.nodes), 95

parent (jinja2.Context attribute), 21

parse() (jinja2.Environment method), 36

parse() (jinja2.ext.Extension method), 87

parse_assign_target() (jinja2.parser.Parser

Markup (class in jinja2), 31

MemcachedBytecodeCache (class in

jinja2), 27

parse_expression()

(jinja2.parser.Parser

MemcachedBytecodeCache.MinimalClientInterface

(jinja2.parser.Parser

(class in jinja2), 27

message (jinja2.TemplateSyntaxError at-

parse_tuple()