- 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.
+ Jinja and hooked it up with the new policy framework.
- 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.
- 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
+- Changed how Jinja enforces strings to be native strings in Python 2
to work when people break their default encoding.
- Added :func:`make_logging_undefined` which returns an undefined
object that logs failures into a logger.
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
+ opcodes. The segfault in earlier Jinja versions here was not a
+ Jinja bug but a limitation in the underlying Python interpreter. If
+ you notice Jinja 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.
+ Jinja 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
than the pluralize count will no longer raise a :exc:`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
+ but is pulled from markupsafe by the Jinja 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.
Released 2009-09-14
-- Fixes some smaller problems for Jinja2 on Jython.
+- Fixes some smaller problems for Jinja on Jython.
Version 2.2
Released 2008-06-09
-- First release of Jinja2
+- First release of Jinja 2.
.. module:: jinja2
:noindex:
- :synopsis: public Jinja2 API
+ :synopsis: public Jinja API
-This document describes the API to Jinja2 and not the template language. It
+This document describes the API to Jinja 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.
+to the application and not those who are creating Jinja templates.
Basics
------
-Jinja2 uses a central object called the template :class:`Environment`.
+Jinja uses a central object called the template :class:`Environment`.
Instances of this class are used to store the configuration and 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
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
+The simplest way to configure Jinja to load templates for your application
looks roughly like this::
from jinja2 import Environment, PackageLoader, select_autoescape
.. admonition:: Notes on Autoescaping
- In future versions of Jinja2 we might enable autoescaping by default
+ In future versions of Jinja we might enable autoescaping by default
for security reasons. As such you are encouraged to explicitly
configure autoescaping now instead of relying on the default.
Unicode
-------
-Jinja2 is using Unicode internally which means that you have to pass Unicode
+Jinja 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 (``\n``).
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
+backwards compatible to ASCII. For Jinja 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
+It is not possible to use Jinja to process non-Unicode data. The reason
+for this is that Jinja uses Unicode already on the language level. For
+example Jinja 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
`Unicode documentation`_.
-Another important thing is how Jinja2 is handling string literals in
+Another important thing is how Jinja 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 `str` explicitly. For example
`datetime.strftime` does not accept Unicode arguments. To not break it
-completely Jinja2 is returning `str` for strings that fit into ASCII and
+completely Jinja is returning `str` for strings that fit into ASCII and
for everything else `unicode`:
>>> m = Template(u"{% set a, b = 'foo', 'föö' %}").module
--------------
The high-level API is the API you will use in the application to load and
-render Jinja2 templates. The :ref:`low-level-api` on the other side is only
-useful if you want to dig deeper into Jinja2 or :ref:`develop extensions
+render Jinja templates. The :ref:`low-level-api` on the other side is only
+useful if you want to dig deeper into Jinja or :ref:`develop extensions
<jinja-extensions>`.
.. autoclass:: Environment([options])
.. versionchanged:: 2.4
-Jinja2 now comes with autoescaping support. As of Jinja 2.9 the
+Jinja now comes with autoescaping support. As of Jinja 2.9 the
autoescape extension is removed and built-in. However autoescaping is
not yet enabled by default though this will most likely change in the
future. It's recommended to configure a sensible default for
Notes on Identifiers
--------------------
-Jinja2 uses the regular Python 2.x naming rules. Valid identifiers have to
-match ``[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.
+Jinja uses Python naming rules. Valid identifiers can be any combination
+of Unicode characters accepted by Python.
Filters and tests are looked up in separate namespaces and have slightly
modified identifier syntax. Filters and tests may contain dots to group
.. admonition:: Implementation
Context is immutable for the same reason Python's frame locals are
- immutable inside functions. Both Jinja2 and Python are not using the
+ immutable inside functions. Both Jinja 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
+ When a template accesses a variable the template does not define, Jinja
looks up the variable in the context, after that the variable is treated
as if it was defined in the template.
.. autoclass:: jinja2.BaseLoader
:members: get_source, load
-Here a list of the builtin loaders Jinja2 provides:
+Here a list of the builtin loaders Jinja provides:
.. autoclass:: jinja2.FileSystemLoader
Async Support
-------------
-Starting with version 2.9, Jinja2 also supports the Python `async` and
+Starting with version 2.9, Jinja also supports the Python `async` and
`await` constructs. As far as template designers go this feature is
entirely opaque to them however as a developer you should be aware of how
it's implemented as it influences what type of APIs you can safely expose
env.policies['urlize.rel'] = 'nofollow noopener'
``compiler.ascii_str``:
- This boolean controls on Python 2 if Jinja2 should store ASCII only
+ This boolean controls on Python 2 if Jinja should store ASCII only
literals as bytestring instead of unicode strings. This used to be
always enabled for Jinja versions below 2.9 and now can be changed.
Traditionally it was done this way since some APIs in Python 2 failed
---------
These helper functions and classes are useful if you add custom filters or
-functions to a Jinja2 environment.
+functions to a Jinja environment.
.. autofunction:: jinja2.environmentfilter
.. admonition:: Note
- The Jinja2 :class:`Markup` class is compatible with at least Pylons and
+ The Jinja :class:`Markup` class is compatible with at least Pylons and
Genshi. It's expected that more template engines and framework will pick
up the `__html__` concept soon.
.. admonition:: 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
+ The low-level API is fragile. Future Jinja versions will try not to
+ change it in a backwards incompatible way but modifications in the Jinja
+ core may shine through. For example if Jinja introduces a new AST node
in later versions that may be returned by :meth:`~Environment.parse`.
The Meta API
Extensions
==========
-Jinja2 supports extensions that can add extra filters, tests, globals or even
+Jinja supports extensions that can add extra filters, tests, globals or even
extend the parser. The main motivation of extensions is to move often used
code into a reusable class like adding support for internationalization.
Adding Extensions
-----------------
-Extensions are added to the Jinja2 environment at creation time. Once the
+Extensions are added to the Jinja 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
``extensions`` parameter of the :class:`~jinja2.Environment` constructor. The following
-example creates a Jinja2 environment with the i18n extension loaded::
+example creates a Jinja environment with the i18n extension loaded::
jinja_env = Environment(extensions=['jinja2.ext.i18n'])
**Import name:** ``jinja2.ext.loopcontrols``
This extension adds support for ``break`` and ``continue`` in loops. After
-enabling, Jinja2 provides those two keywords which work exactly like in
+enabling, Jinja provides those two keywords which work exactly like in
Python.
.. _with-extension:
.. module:: jinja2.ext
-By writing extensions you can add custom tags to Jinja2. This is a non-trivial
+By writing extensions you can add custom tags to Jinja. This is a non-trivial
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 passing
+Jinja template compiler which does not validate the node tree you are passing
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
Example Extension
~~~~~~~~~~~~~~~~~
-The following example implements a ``cache`` tag for Jinja2 by using the
+The following example implements a ``cache`` tag for Jinja by using the
`cachelib`_ library:
.. literalinclude:: cache_extension.py
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.
+change between Jinja versions but will stay backwards compatible.
For more information have a look at the repr of :meth:`jinja2.Environment.parse`.
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
+testsuite show that Jinja 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
.. _Mako: https://www.makotemplates.org/
-How Compatible is Jinja2 with Django?
--------------------------------------
+How Compatible is Jinja with Django?
+------------------------------------
-The default syntax of Jinja2 matches Django syntax in many ways. However
+The default syntax of Jinja 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
+in Jinja. 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.
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
+Jinja 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
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
+Additionally Jinja 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.
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
+AppEngine) Jinja 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.
Why is there no Python 2.3/2.4/2.5/2.6/3.1/3.2/3.3 support?
-----------------------------------------------------------
-Python 2.3 is missing a lot of features that are used heavily in Jinja2. This
+Python 2.3 is missing a lot of features that are used heavily in Jinja. 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
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.
+for older Python 2 (or 3) versions, you can just use Jinja 2.6.
Python 2.6/3.3 support was dropped because it got dropped in various upstream
projects (such as wheel or pytest), which would make it difficult to continue
-supporting it. Jinja2 2.10 was the last version supporting Python 2.6/3.3.
+supporting it. Jinja 2.10 was the last version supporting Python 2.6/3.3.
My Macros are overridden by something
-------------------------------------
{% macro foo() %}CHILD{% endmacro %}
{% block body %}{{ foo() }}{% endblock %}
-This will print ``LAYOUT`` in Jinja2. This is a side effect of having
+This will print ``LAYOUT`` in Jinja. 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
Integration
===========
-Jinja2 provides some code for integration into other tools such as frameworks,
+Jinja 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.
Gettext messages extracted from both `trans` tags and code expressions.
-To extract gettext messages from templates, the project needs a Jinja2 section
+To extract gettext messages from templates, the project needs a Jinja section
in its Babel extraction method `mapping file`_:
.. sourcecode:: ini
Pylons powered application.
The template engine is configured in `config/environment.py`. The configuration
-for Jinja2 looks something like that::
+for Jinja looks something like that::
from jinja2 import Environment, PackageLoader
config['pylons.app_globals'].jinja_env = Environment(
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
+There is a `bundle for TextMate`_ that supports syntax highlighting for Jinja 1
+and Jinja 2 for text based templates as well as HTML. It also contains a few
often used snippets.
.. _bundle for TextMate: https://github.com/mitsuhiko/jinja2-tmbundle
A syntax plugin for `Vim`_ is available `from the jinja repository
<https://github.com/pallets/jinja/blob/master/ext/Vim/jinja.vim>`_. The script
-supports Jinja1 and Jinja2. Once installed, two file types are available
+supports Jinja 1 and Jinja 2. Once installed, two file types are available
(``jinja`` and ``htmljinja``). The first one is for text-based templates and the
second is for HTML templates. For HTML documents, the plugin attempts to
automatically detect Jinja syntax inside of existing HTML documents.
Introduction
============
-This is the documentation for the Jinja2 general purpose templating language.
-Jinja2 is a library for Python that is designed to be flexible, fast and secure.
+This is the documentation for the Jinja general purpose templating language.
+Jinja is a library for Python 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
+Django, you should feel right at home with Jinja. It's both designer and
developer friendly by sticking to Python's principles and adding functionality
useful for templating environments.
Prerequisites
-------------
-Jinja2 works with Python 2.7.x and >= 3.4. If you are using Python
-3.2 you can use an older release of Jinja2 (2.6) as support for Python 3.2
-was dropped in Jinja2 version 2.7. The last release which supported Python 2.6
-and 3.3 was Jinja2 2.10.
+Jinja works with Python 2.7.x and >= 3.5. If you are using Python
+3.2 you can use an older release of Jinja (2.6) as support for Python 3.2
+was dropped in Jinja version 2.7. The last release which supported Python 2.6
+and 3.3 was Jinja 2.10.
If you wish to use the :class:`~jinja2.PackageLoader` class, you will also
need `setuptools`_ or `distribute`_ installed at runtime.
Installation
------------
-You can install the most recent Jinja2 version using `pip`_::
+You can install the most recent Jinja version using `pip`_::
pip install Jinja2
-This will install Jinja2 in your Python installation's site-packages directory.
+This will install Jinja in your Python installation's site-packages directory.
Installing the development version
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
MarkupSafe Dependency
~~~~~~~~~~~~~~~~~~~~~
-As of version 2.7 Jinja2 depends on the `MarkupSafe`_ module. If you install
-Jinja2 via ``pip`` it will be installed automatically for you.
+As of version 2.7 Jinja depends on the `MarkupSafe`_ module. If you install
+Jinja via ``pip`` it will be installed automatically for you.
.. _MarkupSafe: https://markupsafe.palletsprojects.com/
Basic API Usage
---------------
-This section gives you a brief introduction to the Python API for Jinja2
+This section gives you a brief introduction to the Python API for Jinja
templates.
The most basic way to create a template and render it is through
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
+What you can see here is that Jinja is using unicode internally and the
return value is an unicode string. So make sure that your application is
indeed using unicode internally.
Sandbox
=======
-The Jinja2 sandbox can be used to evaluate untrusted code. Access to unsafe
+The Jinja sandbox can be used to evaluate untrusted code. Access to unsafe
attributes and methods is prohibited.
Assuming `env` is a :class:`SandboxedEnvironment` in the default configuration
.. admonition:: Note
- The Jinja2 sandbox alone is no solution for perfect security. Especially
+ The Jinja 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
.. versionadded:: 2.6
-For maximum performance Jinja2 will let operators call directly the type
+For maximum performance Jinja will let operators call directly the type
specific callback methods. This means that it's not possible to have this
intercepted by overriding :meth:`Environment.call`. Furthermore a
conversion from operator to special method is not always directly possible
This can be used to customize specific operators as necessary. In order
to intercept an operator one has to override the
:attr:`SandboxedEnvironment.intercepted_binops` attribute. Once the
-operator that needs to be intercepted is added to that set Jinja2 will
+operator that needs to be intercepted is added to that set Jinja will
generate bytecode that calls the :meth:`SandboxedEnvironment.call_binop`
function. For unary operators the `unary` attributes and methods have to
be used instead.
operator, left, right)
Make sure to always call into the super method, even if you are not
-intercepting the call. Jinja2 might internally call the method to
+intercepting the call. Jinja might internally call the method to
evaluate expressions.
.. highlight:: html+jinja
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
+to Jinja here is a small guide that shows the basic syntactic and semantic
changes between some common, similar text template engines for Python.
-Jinja1
-------
+Jinja 1
+-------
-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
+Jinja 2 is mostly compatible with Jinja 1 in terms of API usage and template
+syntax. The differences between Jinja 1 and 2 are explained in the following
list.
API
~~~
Loaders
- Jinja2 uses a different loader API. Because the internal representation
+ Jinja 2 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
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
+ default environment configuration by using `jinja.from_string`. Jinja 2
provides a :class:`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
+ Jinja 1 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
+ bytestring to Unicode conversion. An application powered by Jinja 2
+ *has to* use unicode internally everywhere or make sure that Jinja 2 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
+ Jinja 1 used custom translators for internationalization. i18n is now
+ available as Jinja 2 extension and uses a simpler, more gettext friendly
interface and has support for babel. For more details see
:ref:`i18n-extension`.
Internal methods
- Jinja1 exposed a few internal methods on the environment object such
+ Jinja 1 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
+ as being an internal method it was possible to override them. Jinja 2
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
+ Jinja 1 was running sandbox mode by default. Few applications actually
+ used that feature so it became optional in Jinja 2. For more details
about the sandboxed execution see :class:`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
+ Jinja 1 had a stacked context as storage for variables passed to the
+ environment. In Jinja 2 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.
Templates
~~~~~~~~~
-Jinja2 has mostly the same syntax as Jinja1. What's different is that
+Jinja 2 has mostly the same syntax as Jinja 1. What's different is that
macros require parentheses around the argument list now.
-Additionally Jinja2 allows dynamic inheritance now and dynamic includes.
+Additionally Jinja 2 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
------
If you have previously worked with Django templates, you should find
-Jinja2 very familiar. In fact, most of the syntax elements look and
+Jinja very familiar. In fact, most of the syntax elements look and
work the same.
-However, Jinja2 provides some more syntax elements covered in the
+However, Jinja 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
Filter Arguments
~~~~~~~~~~~~~~~~
-Jinja2 provides more than one argument for filters. Also the syntax for
+Jinja 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:", " }}
Loops
~~~~~
-For loops work very similarly to Django, but notably the Jinja2 special
+For loops work very similarly to Django, but notably the Jinja 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
+In addition, the Django `empty` argument is called `else` in Jinja. For
example, the Django template::
{% for item in items %}
.. highlight:: html+mako
-If you have used Mako so far and want to switch to Jinja2 you can configure
-Jinja2 to look more like Mako:
+If you have used Mako so far and want to switch to Jinja you can configure
+Jinja to look more like Mako:
.. sourcecode:: python
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
+With an environment configured like that, Jinja should be able to interpret
+a small subset of Mako templates. Jinja 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.
+(which are called macros in Jinja) and template inheritance is different too.
The following Mako template::
<%inherit file="layout.html" />
% endfor
</ul>
-Looks like this in Jinja2 with the above configuration::
+Looks like this in Jinja with the above configuration::
<% extends "layout.html" %>
<% block title %>Page Title<% endblock %>
.. admonition:: Implementation
- For the sake of convenience, ``foo.bar`` in Jinja2 does the following
+ For the sake of convenience, ``foo.bar`` in Jinja does the following
things on the Python layer:
- check for an attribute called `bar` on `foo`
If :ref:`line-statements` are enabled, they strip leading whitespace
automatically up to the beginning of the line.
-By default, Jinja2 also removes trailing newlines. To keep single
+By default, Jinja also removes trailing newlines. To keep single
trailing newlines, configure Jinja to `keep_trailing_newline`.
.. admonition:: Note
Named Block End-Tags
~~~~~~~~~~~~~~~~~~~~
-Jinja2 allows you to put the name of the block after the end tag for better
+Jinja allows you to put the name of the block after the end tag for better
readability::
{% block sidebar %}
you have data that is already safe but not marked, be sure to wrap it in
``Markup`` or use the ``|safe`` filter.
-Jinja2 functions (macros, `super`, `self.BLOCKNAME`) always return template
+Jinja functions (macros, `super`, `self.BLOCKNAME`) always return template
data that is marked as safe.
String literals in templates with automatic escaping are considered unsafe
use recursively. Then, we can call it using `{{ outer_loop(...) }}`
Please note that assignments in loops will be cleared at the end of the
-iteration and cannot outlive the loop scope. Older versions of Jinja2 had
+iteration and cannot outlive the loop scope. Older versions of Jinja had
a bug where in some circumstances it appeared that assignments would work.
This is not supported. See :ref:`assignments` for more information about
how to deal with this.
Filters
~~~~~~~
-Filter sections allow you to apply regular Jinja2 filters on a block of
+Filter sections allow you to apply regular Jinja filters on a block of
template data. Just wrap the code in the special `filter` section::
{% filter upper %}
Import
~~~~~~
-Jinja2 supports putting often used code into macros. These macros can go into
+Jinja supports putting often used code into macros. These macros can go into
different templates and get imported from there. This works similarly 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,
Extensions
----------
-The following sections cover the built-in Jinja2 extensions that may be
+The following sections cover the built-in Jinja extensions that may be
enabled by an application. An application could also provide further
extensions not covered by this documentation; in which case there should
be a separate document explaining said :ref:`extensions
consequences. In particular one variable could refer to another defined
in the same with block's opening statement. This caused issues with the
cleaned up scoping behavior and has since been improved. In particular
-in newer Jinja2 versions the following code always refers to the variable
+in newer Jinja versions the following code always refers to the variable
`a` from outside the `with` block::
{% with a={}, b=a.attribute %}...{% endwith %}
.. highlight:: html+jinja
-This part of the documentation shows some tips and tricks for Jinja2
+This part of the documentation shows some tips and tricks for Jinja
templates.
Null-Master Fallback
--------------------
-Jinja2 supports dynamic inheritance and does not distinguish between parent
+Jinja 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
"""\
- This benchmark compares some python templating engines with Jinja 2 so
- that we get a picture of how fast Jinja 2 is for a semi real world
+ This benchmark compares some python templating engines with Jinja so
+ that we get a picture of how fast Jinja is for a semi real world
template. If a template engine is not installed the test is skipped.\
"""
import sys
<div class="header">
<h1>RealWorld Benchmark</h1>
<blockquote><p>
- A less stupid benchmark for Mako and Jinja2 to get an impression how
+ A less stupid benchmark for Mako and Jinja to get an impression how
code changes affect runtime performance.
</p></blockquote>
</div>
<div class="header">
<h1>RealWorld Benchmark</h1>
<blockquote><p>
- A less stupid benchmark for Mako and Jinja2 to get an impression how
+ A less stupid benchmark for Mako and Jinja to get an impression how
code changes affect runtime performance.
</p></blockquote>
</div>
<div class="header">
<h1>RealWorld Benchmark</h1>
<blockquote><p>
- A less stupid benchmark for Mako and Jinja2 to get an impression how
+ A less stupid benchmark for Mako and Jinja to get an impression how
code changes affect runtime performance.
</p></blockquote>
</div>
<div class="header">
<h1>RealWorld Benchmark</h1>
<blockquote><p>
- A less stupid benchmark for Mako and Jinja2 to get an impression how
+ A less stupid benchmark for Mako and Jinja to get an impression how
code changes affect runtime performance.
</p></blockquote>
</div>
RealWorldish Benchmark
~~~~~~~~~~~~~~~~~~~~~~
- A more real-world benchmark of Jinja2. Like the other benchmark in the
- Jinja2 repository this has no real-world usefulnes (despite the name).
+ A more real-world benchmark of Jinja. Like the other benchmark in the
+ Jinja repository this has no real-world usefulnes (despite the name).
Just go away and ignore it. NOW!
:copyright: (c) 2009 by the Jinja Team.
"
" Changes:
"
-" 2008 May 9: Added support for Jinja2 changes (new keyword rules)
+" 2008 May 9: Added support for Jinja 2 changes (new keyword rules)
" .vimrc variable to disable html highlighting
if !exists('g:jinja_syntax_html')
Django to Jinja
~~~~~~~~~~~~~~~
- Helper module that can convert django templates into Jinja2 templates.
+ Helper module that can convert django templates into Jinja templates.
This file is not intended to be used as stand alone application but to
be used as library. To convert templates you basically create your own
djangojinja2
~~~~~~~~~~~~
- Adds support for Jinja2 to Django.
+ Adds support for Jinja to Django.
Configuration variables:
Key Description
======================= =============================================
`JINJA2_TEMPLATE_DIRS` List of template folders
- `JINJA2_EXTENSIONS` List of Jinja2 extensions to use
- `JINJA2_CACHE_SIZE` The size of the Jinja2 template cache.
+ `JINJA2_EXTENSIONS` List of Jinja extensions to use
+ `JINJA2_CACHE_SIZE` The size of the Jinja template cache.
======================= =============================================
:copyright: (c) 2009 by the Jinja Team.
def get_env():
- """Get the Jinja2 env and initialize it if necessary."""
+ """Get the Jinja env and initialize it if necessary."""
global _jinja_env
if _jinja_env is None:
_jinja_env = create_env()
def create_env():
- """Create a new Jinja2 environment."""
+ """Create a new Jinja environment."""
searchpath = list(settings.JINJA2_TEMPLATE_DIRS)
return Environment(loader=FileSystemLoader(searchpath),
auto_reload=settings.TEMPLATE_DEBUG,
Inline Gettext
~~~~~~~~~~~~~~
- An example extension for Jinja2 that supports inline gettext calls.
+ An example extension for Jinja that supports inline gettext calls.
Requires the i18n extension to be loaded.
:copyright: (c) 2009 by the Jinja Team.
jinja2
~~~~~~
- Jinja2 is a template engine written in pure Python. It provides a
+ Jinja is a template engine written in pure Python. It provides a
Django inspired non-XML syntax but supports inline expressions and
an optional sandboxed environment.
Nutshell
--------
- Here a small example of a Jinja2 template::
+ Here a small example of a Jinja template::
{% extends 'base.html' %}
{% block title %}Memberlist{% endblock %}
bucket.write_bytecode(f)
A more advanced version of a filesystem based bytecode cache is part of
- Jinja2.
+ Jinja.
"""
def load_bytecode(self, bucket):
raise NotImplementedError()
def clear(self):
- """Clears the cache. This method is not used by Jinja2 but should be
+ """Clears the cache. This method is not used by Jinja but should be
implemented to allow applications to clear the bytecode cache used
by a particular environment.
"""
executable source- or bytecode. This is useful for debugging or to
extract information from templates.
- If you are :ref:`developing Jinja2 extensions <writing-extensions>`
+ If you are :ref:`developing Jinja extensions <writing-extensions>`
this gives you a good overview of the node tree generated.
"""
try:
:class:`~jinja2.lexer.Token`\\s, but it doesn't have to return a
:class:`~jinja2.lexer.TokenStream`.
- In the `ext` folder of the Jinja2 source distribution there is a file
+ In the `ext` folder of the Jinja source distribution there is a file
called `inlinegettext.py` which implements a filter that utilizes this
method.
"""
class InternationalizationExtension(Extension):
- """This extension adds gettext support to Jinja2."""
+ """This extension adds gettext support to Jinja."""
tags = {'trans'}
# TODO: the i18n extension is currently reevaluating values in a few
class ExprStmtExtension(Extension):
- """Adds a `do` tag to Jinja2 that works like the print statement just
+ """Adds a `do` tag to Jinja that works like the print statement just
that it doesn't print the return value.
"""
tags = set(['do'])
{{ "foo bar baz qux"|truncate(11, False, '...', 0) }}
-> "foo bar..."
- The default leeway on newer Jinja2 versions is 5 and was 0 before but
+ The default leeway on newer Jinja versions is 5 and was 0 before but
can be reconfigured globally.
"""
if leeway is None:
class Node(with_metaclass(NodeType, object)):
- """Baseclass for all Jinja2 nodes. There are a number of nodes available
+ """Baseclass for all Jinja nodes. There are a number of nodes available
of different types. There are four major types:
- :class:`Stmt`: statements
class Parser(object):
- """This is the central parsing class Jinja2 uses. It's passed to
+ """This is the central parsing class Jinja uses. It's passed to
extensions and can be used to parse expressions or statements.
"""
def parse_assign_target(self, with_tuple=True, name_only=False,
extra_end_rules=None, with_namespace=False):
- """Parse an assignment target. As Jinja2 allows assignments to
+ """Parse an assignment target. As Jinja 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 `with_tuple` to `False`. If only assignments to names are
return value is True
-# NOTE: The existing Jinja2 'number' test matches booleans and floats
+# NOTE: The existing 'number' test matches booleans and floats
def test_integer(value):
"""Return true if the object is an integer.
return isinstance(value, integer_types) and value is not True and value is not False
-# NOTE: The existing Jinja2 'number' test matches booleans and integers
+# NOTE: The existing 'number' test matches booleans and integers
def test_float(value):
"""Return true if the object is a float.
def 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
+ """Jinja keeps internal caches for environments and lexers. These are
+ used so that Jinja doesn't have to recreate environments and lexers all
the time. Normally you don't have to care about that but if you are
measuring memory consumption you may want to clean the caches.
"""
#!/usr/bin/env python
# -*- coding: utf-8 -*-
"""
- Jinja2 Debug Interface
- ~~~~~~~~~~~~~~~~~~~~~~
+ Jinja Debug Interface
+ ~~~~~~~~~~~~~~~~~~~~~
- Helper script for internal Jinja2 debugging. Requires Werkzeug.
+ Helper script for internal Jinja debugging. Requires Werkzeug.
:copyright: Copyright 2010 by Armin Ronacher.
:license: BSD.
projects / thirdparty / jinja.git / commitdiff
