Merge branch 'stable'

PyPI and trusted publishing has built-in attestation support now.

.devcontainer/devcontainer.json

@@ -0,0 +1,17 @@
+{
+  "name": "pallets/jinja",
+  "image": "mcr.microsoft.com/devcontainers/python:3",
+  "customizations": {
+    "vscode": {
+      "settings": {
+        "python.defaultInterpreterPath": "${workspaceFolder}/.venv",
+        "python.terminal.activateEnvInCurrentTerminal": true,
+        "python.terminal.launchArgs": [
+          "-X",
+          "dev"
+        ]
+      }
+    }
+  },
+  "onCreateCommand": ".devcontainer/on-create-command.sh"
+}

.devcontainer/on-create-command.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+set -e
+
+# Install uv if not already installed
+if ! command -v uv &> /dev/null; then
+    echo "Installing uv..."
+    curl -LsSf https://astral.sh/uv/install.sh | sh
+    export PATH="$HOME/.cargo/bin:$PATH"
+fi
+
+# Create venv using uv and install dependencies
+echo "Creating virtual environment and installing dependencies..."
+uv sync
+
+# Install pre-commit hooks
+echo "Installing pre-commit hooks..."
+pre-commit install --install-hooks

.editorconfig

@@ -0,0 +1,13 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+insert_final_newline = true
+trim_trailing_whitespace = true
+end_of_line = lf
+charset = utf-8
+max_line_length = 88
+
+[*.{css,html,js,json,jsx,scss,ts,tsx,yaml,yml}]
+indent_size = 2

.github/ISSUE_TEMPLATE/bug-report.md

@@ -0,0 +1,27 @@
+---
+name: Bug report
+about: Report a bug in Jinja (not other projects which depend on Jinja)
+---
+
+<!--
+This issue tracker is a tool to address bugs in Jinja itself. Please use
+GitHub Discussions or the Pallets Discord for questions about your own code.
+
+Replace this comment with a clear outline of what the bug is.
+-->
+
+<!--
+Describe how to replicate the bug.
+
+Include a minimal reproducible example that demonstrates the bug.
+Include the full traceback if there was an exception.
+-->
+
+<!--
+Describe the expected behavior that should have happened but didn't.
+-->
+
+Environment:
+
+- Python version:
+- Jinja version:

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Questions on Discussions
+    url: https://github.com/pallets/jinja/discussions/
+    about: Ask questions about your own code on the Discussions tab.
+  - name: Questions on Chat
+    url: https://discord.gg/pallets
+    about: Ask questions about your own code on our Discord chat.

.github/ISSUE_TEMPLATE/feature-request.md

@@ -0,0 +1,15 @@
+---
+name: Feature request
+about: Suggest a new feature for Jinja
+---
+
+<!--
+Replace this comment with a description of what the feature should do.
+Include details such as links to relevant specs or previous discussions.
+-->
+
+<!--
+Replace this comment with an example of the problem which this feature
+would resolve. Is this problem solvable without changes to Jinja, such
+as by subclassing or using an extension?
+-->

.github/pull_request_template.md

@@ -0,0 +1,25 @@
+<!--
+Before opening a PR, open a ticket describing the issue or feature the
+PR will address. An issue is not required for fixing typos in
+documentation, or other simple non-code changes.
+
+Replace this comment with a description of the change. Describe how it
+addresses the linked ticket.
+-->
+
+<!--
+Link to relevant issues or previous PRs, one per line. Use "fixes" to
+automatically close an issue.
+
+fixes #<issue number>
+-->
+
+<!--
+Ensure each step in CONTRIBUTING.rst is complete, especially the following:
+
+- Add tests that demonstrate the correct behavior of the change. Tests
+  should fail without the change.
+- Add or update relevant docs, in the docs folder and in code.
+- Add an entry in CHANGES.rst summarizing the change and linking to the issue.
+- Add `.. versionchanged::` entries in any relevant code docs.
+-->

.github/workflows/lock.yaml

@@ -0,0 +1,24 @@
+name: Lock inactive closed issues
+# Lock closed issues that have not received any further activity for two weeks.
+# This does not close open issues, only humans may do that. It is easier to
+# respond to new issues with fresh examples rather than continuing discussions
+# on old issues.
+
+on:
+  schedule:
+    - cron: '0 0 * * *'
+permissions:
+  issues: write
+  pull-requests: write
+  discussions: write
+concurrency:
+  group: lock
+jobs:
+  lock:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: dessant/lock-threads@1bf7ec25051fe7c00bdd17e6a7cf3d7bfb7dc771 # v5.0.1
+        with:
+          issue-inactive-days: 14
+          pr-inactive-days: 14
+          discussion-inactive-days: 14

.github/workflows/pre-commit.yaml

@@ -0,0 +1,25 @@
+name: pre-commit
+on:
+  pull_request:
+  push:
+    branches: [main, stable]
+jobs:
+  main:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: astral-sh/setup-uv@f0ec1fc3b38f5e7cd731bb6ce540c5af426746bb # v6.1.0
+        with:
+          enable-cache: true
+          prune-cache: false
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        id: setup-python
+        with:
+          python-version-file: pyproject.toml
+      - uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684 # v4.2.3
+        with:
+          path: ~/.cache/pre-commit
+          key: pre-commit|${{ hashFiles('pyproject.toml', '.pre-commit-config.yaml') }}
+      - run: uv run --locked --group pre-commit pre-commit run --show-diff-on-failure --color=always --all-files
+      - uses: pre-commit-ci/lite-action@5d6cc0eb514c891a40562a58a8e71576c5c7fb43 # v1.1.0
+        if: ${{ !cancelled() }}

.github/workflows/publish.yaml

@@ -0,0 +1,47 @@
+name: Publish
+on:
+  push:
+    tags: ['*']
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: astral-sh/setup-uv@f0ec1fc3b38f5e7cd731bb6ce540c5af426746bb # v6.1.0
+        with:
+          enable-cache: true
+          prune-cache: false
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version-file: pyproject.toml
+      - run: echo "SOURCE_DATE_EPOCH=$(git log -1 --pretty=%ct)" >> $GITHUB_ENV
+      - run: uv build
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          path: ./dist
+  create-release:
+    needs: [build]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+      - name: create release
+        run: >
+          gh release create --draft --repo ${{ github.repository }}
+          ${{ github.ref_name }} artifact/*
+        env:
+          GH_TOKEN: ${{ github.token }}
+  publish-pypi:
+    needs: [build]
+    environment:
+      name: publish
+      url: https://pypi.org/project/Jinja2/${{ github.ref_name }}
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+      - uses: pypa/gh-action-pypi-publish@76f52bc884231f62b9a034ebfe128415bbaabdfc # v1.12.4
+        with:
+          packages-dir: artifact/

.github/workflows/tests.yaml

@@ -0,0 +1,49 @@
+name: Tests
+on:
+  pull_request:
+    paths-ignore: ['docs/**', 'README.md']
+  push:
+    branches: [main, stable]
+    paths-ignore: ['docs/**', 'README.md']
+jobs:
+  tests:
+    name: ${{ matrix.name || matrix.python }}
+    runs-on: ${{ matrix.os || 'ubuntu-latest' }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - {python: '3.13'}
+          - {name: Windows, python: '3.13', os: windows-latest}
+          - {name: Mac, python: '3.13', os: macos-latest}
+          - {python: '3.12'}
+          - {python: '3.11'}
+          - {python: '3.10'}
+          - {name: PyPy, python: 'pypy-3.11', tox: pypy3.11}
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: astral-sh/setup-uv@f0ec1fc3b38f5e7cd731bb6ce540c5af426746bb # v6.1.0
+        with:
+          enable-cache: true
+          prune-cache: false
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv run --locked tox run -e ${{ matrix.tox || format('py{0}', matrix.python) }}
+  typing:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: astral-sh/setup-uv@f0ec1fc3b38f5e7cd731bb6ce540c5af426746bb # v6.1.0
+        with:
+          enable-cache: true
+          prune-cache: false
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version-file: pyproject.toml
+      - name: cache mypy
+        uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684 # v4.2.3
+        with:
+          path: ./.mypy_cache
+          key: mypy|${{ hashFiles('pyproject.toml') }}
+      - run: uv run --locked tox run -e typing

.gitignore

@@ -0,0 +1,8 @@
+.idea/
+.vscode/
+__pycache__/
+dist/
+.coverage*
+htmlcov/
+.tox/
+docs/_build/

.hgignore

@@ -1,9 +0,0 @@
-^instance$
-^instance/
-^jinja2/.*\.so$
-^docs/_build
-^(build|dist|Jinja2\.egg-info)/
-\.py[co]$
-\.DS_Store$
-^env/
-^py3k/

.hgtags

@@ -1,4 +0,0 @@
-38b9483b8ce7c7e92b6f9d03e75017105c2d7965 2.0rc1
-344f2e5078d202663a08b50cf3a5f44da2a2cb54 2.0
-bac88fe8bc0e50b321a04eea038ed4542c43a62f 2.1
-ac0fc30f7b5ffca59769c5d9ed78f50596868af8 2.1.1

.pre-commit-config.yaml

@@ -0,0 +1,18 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: 76e47323a83cd9795e4ff9a1de1c0d2eef610f17  # frozen: v0.11.11
+    hooks:
+      - id: ruff
+      - id: ruff-format
+  - repo: https://github.com/astral-sh/uv-pre-commit
+    rev: 648bdbfd6bb1a82f132ecc2c666e0d1b2e4b0d94  # frozen: 0.7.8
+    hooks:
+      - id: uv-lock
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: cef0300fd0fc4d2a87a85fa2093c6b283ea36f4b  # frozen: v5.0.0
+    hooks:
+      - id: check-merge-conflict
+      - id: debug-statements
+      - id: fix-byte-order-marker
+      - id: trailing-whitespace
+      - id: end-of-file-fixer

.readthedocs.yaml

@@ -0,0 +1,10 @@
+version: 2
+build:
+  os: ubuntu-24.04
+  tools:
+    python: '3.13'
+  commands:
+    - asdf plugin add uv
+    - asdf install uv latest
+    - asdf global uv latest
+    - uv run --group docs sphinx-build -W -b dirhtml docs $READTHEDOCS_OUTPUT/html

AUTHORS

@@ -1,31 +0,0 @@
-Jinja is written and maintained by the Jinja Team and various
-contributors:
-
-Lead Developer:
-
-- Armin Ronacher <armin.ronacher@active-4.com>
-
-Developers:
-
-- Christoph Hack
-- Georg Brandl
-
-Contributors:
-
-- Bryan McLemore
-- Mickaël Guérin <kael@crocobox.org>
-- Cameron Knight
-- Lawrence Journal-World.
-- David Cramer
-
-Patches and suggestions:
-
-- Ronny Pfannschmidt
-- Axel Böhm
-- Alexey Melchakov
-- Bryan McLemore
-- Clovis Fabricio (nosklo)
-- Cameron Knight
-- Peter van Dijk (Habbie)
-- Stefan Ebner
-- Rene Leonhardt

CHANGES

@@ -1,114 +0,0 @@
-Jinja2 Changelog
-================
-
-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.
-- 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.  The new attribute
-  is called "overlayed".
-
-Version 2.1.1
--------------
-(Bugfix release)
-
-- Fixed a translation error caused by looping over empty recursive loops.
-
-Version 2.1
------------
-(codename Yasuzō, 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.
-
-- fixed a bug with empty statements in macros.
-
-- implemented a bytecode cache system.  (:ref:`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
-  :class:`~jinja2.nodes.Getitem` and :class:`~jinja2.nodes.Getattr`.
-
-  For more information see :ref:`the implementation details <notes-on-subscriptions>`.
-
-- 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 :meth:`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

LICENSE

@@ -1,31 +0,0 @@
-Copyright (c) 2009 by the Jinja Team, see AUTHORS for more details.
-
-Some rights reserved.
-
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are
-met:
-
-    * Redistributions of source code must retain the above copyright
-      notice, this list of conditions and the following disclaimer.
-
-    * Redistributions in binary form must reproduce the above
-      copyright notice, this list of conditions and the following
-      disclaimer in the documentation and/or other materials provided
-      with the distribution.
-
-    * The names of the contributors may not be used to endorse or
-      promote products derived from this software without specific
-      prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
-"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
-LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
-A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
-OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
-LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
-DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
-THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

LICENSE.txt

@@ -0,0 +1,28 @@
+Copyright 2007 Pallets
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+1.  Redistributions of source code must retain the above copyright
+    notice, this list of conditions and the following disclaimer.
+
+2.  Redistributions in binary form must reproduce the above copyright
+    notice, this list of conditions and the following disclaimer in the
+    documentation and/or other materials provided with the distribution.
+
+3.  Neither the name of the copyright holder nor the names of its
+    contributors may be used to endorse or promote products derived from
+    this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

MANIFEST.in

@@ -1,7 +0,0 @@
-include MANIFEST.in Makefile CHANGES LICENSE AUTHORS TODO ez_setup.py
-recursive-include docs *
-recursive-include tests *
-recursive-include ext *
-recursive-include artwork *
-recursive-include examples *
-recursive-exclude docs/_build/doctrees *

Makefile

@@ -1,11 +0,0 @@
-test:
-	cd tests; nosetests -v
-
-2to3:
-	rm -rf py3k
-	mkdir py3k
-	cp -R jinja2 py3k
-	2to3 jinja2 > py3k/convert.patch
-	cd py3k; patch -p0 < convert.patch
-
-.PHONY: test

README.md

@@ -0,0 +1,59 @@
+<div align="center"><img src="https://raw.githubusercontent.com/pallets/jinja/refs/heads/stable/docs/_static/jinja-name.svg" alt="" height="150"></div>
+
+# Jinja
+
+Jinja is a fast, expressive, extensible templating engine. Special
+placeholders in the template allow writing code similar to Python
+syntax. Then the template is passed data to render the final document.
+
+It includes:
+
+-   Template inheritance and inclusion.
+-   Define and import macros within templates.
+-   HTML templates can use autoescaping to prevent XSS from untrusted
+    user input.
+-   A sandboxed environment can safely render untrusted templates.
+-   AsyncIO support for generating templates and calling async
+    functions.
+-   I18N support with Babel.
+-   Templates are compiled to optimized Python code just-in-time and
+    cached, or can be compiled ahead-of-time.
+-   Exceptions point to the correct line in templates to make debugging
+    easier.
+-   Extensible filters, tests, functions, and even syntax.
+
+Jinja's philosophy is that while application logic belongs in Python if
+possible, it shouldn't make the template designer's job difficult by
+restricting functionality too much.
+
+
+## In A Nutshell
+
+```jinja
+{% extends "base.html" %}
+{% block title %}Members{% endblock %}
+{% block content %}
+  <ul>
+  {% for user in users %}
+    <li><a href="{{ user.url }}">{{ user.username }}</a></li>
+  {% endfor %}
+  </ul>
+{% endblock %}
+```
+
+## Donate
+
+The Pallets organization develops and supports Jinja and other popular
+packages. In order to grow the community of contributors and users, and
+allow the maintainers to devote more time to the projects, [please
+donate today][].
+
+[please donate today]: https://palletsprojects.com/donate
+
+## Contributing
+
+See our [detailed contributing documentation][contrib] for many ways to
+contribute, including reporting issues, requesting features, asking or answering
+questions, and making PRs.
+
+[contrib]: https://palletsprojects.com/contributing/

TODO

@@ -1,39 +0,0 @@
-Todo Before Release
-===================
-
-This has to be implemented before the release:
-
-Pull Attributes Onces
----------------------
-
-Imagine the following template::
-
-    {% if foo.bar %}
-        {{ baz(foo.bar) }}
-    {% endif %}
-
-Problem with that is that it compiles to this::
-
-    if environment.subscribe(l_foo, 'bar'):
-        if 0: yield None
-        yield u'\n    %s\n' % (
-            l_baz(environment.subscribe(l_foo, 'bar')),
-        )
-
-As `environment.subscribe` is more expensive then regular attribute lookups
-(it tries getitem/getattr and in sandbox mode also permissions) multiple
-lookups with the same parameters in the same scope should get local aliases.
-The result we have is that one::
-
-    t1 = environment.subscribe(l_foo, 'bar')
-    if t1:
-        if 0: yield None
-        yield u'\n    %s\n' % (
-            l_baz(t1),
-        )
-
-However that should only happen if the attribute is accessed multiple times
-unlike locals and filters/tests which are always pulled.  We're not doing that
-for filters/tests/locals as nested scopes may access it and testing is too
-complicated for the tiny performance improvement but easy for attribute
-lookups, keeping the complexity of the whole thing in mind.

docs/Makefile

@@ -1,75 +1,19 @@
-# Makefile for Sphinx documentation
+# Minimal makefile for Sphinx documentation
 #
 
 # You can set these variables from the command line.
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
-PAPER         =
-
-# Internal variables.
-PAPEROPT_a4     = -D latex_paper_size=a4
-PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d _build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
-
-.PHONY: help clean html web pickle htmlhelp latex changes linkcheck
+SOURCEDIR     = .
+BUILDDIR      = _build
 
+# Put it first so that "make" without argument is like "make help".
 help:
-	@echo "Please use \`make <target>' where <target> is one of"
-	@echo "  html      to make standalone HTML files"
-	@echo "  pickle    to make pickle files"
-	@echo "  json      to make JSON files"
-	@echo "  htmlhelp  to make HTML files and a HTML help project"
-	@echo "  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
-	@echo "  changes   to make an overview over all changed/added/deprecated items"
-	@echo "  linkcheck to check all external links for integrity"
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-clean:
-	-rm -rf _build/*
+.PHONY: help Makefile
 
-html:
-	mkdir -p _build/html _build/doctrees
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) _build/html
-	@echo
-	@echo "Build finished. The HTML pages are in _build/html."
-
-pickle:
-	mkdir -p _build/pickle _build/doctrees
-	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) _build/pickle
-	@echo
-	@echo "Build finished; now you can process the pickle files"
-
-json:
-	mkdir -p _build/json _build/doctrees
-	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) _build/json
-	@echo
-	@echo "Build finished; now you can process the json files"
-
-web: pickle
-
-htmlhelp:
-	mkdir -p _build/htmlhelp _build/doctrees
-	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) _build/htmlhelp
-	@echo
-	@echo "Build finished; now you can run HTML Help Workshop with the" \
-	      ".hhp project file in _build/htmlhelp."
-
-latex:
-	mkdir -p _build/latex _build/doctrees
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) _build/latex
-	@echo
-	@echo "Build finished; the LaTeX files are in _build/latex."
-	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
-	      "run these through (pdf)latex."
-
-changes:
-	mkdir -p _build/changes _build/doctrees
-	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) _build/changes
-	@echo
-	@echo "The overview file is in _build/changes."
-
-linkcheck:
-	mkdir -p _build/linkcheck _build/doctrees
-	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) _build/linkcheck
-	@echo
-	@echo "Link check complete; look for any errors in the above output " \
-	      "or in _build/linkcheck/output.txt."
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_static/jinja-icon.svg

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg width="100%" height="100%" viewBox="0 0 500 500" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xml:space="preserve" xmlns:serif="http://www.serif.com/" style="fill-rule:evenodd;clip-rule:evenodd;stroke-linejoin:round;stroke-miterlimit:2;">
+    <rect id="Icon" x="0" y="0" width="500" height="500" style="fill:none;"/>
+    <clipPath id="_clip1">
+        <rect x="0" y="0" width="500" height="500"/>
+    </clipPath>
+    <g clip-path="url(#_clip1)">
+        <path d="M491.941,72.796l-1.81,-0c-88.724,29.526 -204.909,29.526 -237.199,28.989l-29.877,-0.536c-88.119,-3.222 -133.085,-37.043 -211.849,-72.206c-5.432,-2.416 -11.77,1.61 -11.166,7.247c0.604,19.327 5.734,100.39 66.392,121.596c2.112,0.805 4.526,1.61 6.639,2.147c3.018,0.537 4.225,2.953 4.828,4.563l5.131,15.837c0.905,3.758 3.621,6.979 6.639,6.979l5.13,0c4.527,0 8.148,3.221 8.45,7.248l-0,15.3c-0,1.61 -1.509,2.953 -3.32,2.953l-38.929,-0c-3.622,-0 -6.64,2.684 -6.64,5.905l0,23.89c0,3.221 3.018,5.905 6.64,5.905l38.929,-0c1.811,-0 3.32,1.342 3.32,2.953l-0,6.442c-0,1.61 -1.509,2.952 -3.32,2.952l-38.929,0c-3.622,0.269 -6.338,2.685 -6.338,5.906l0,23.889c0,2.685 2.414,5.637 5.13,5.637l40.439,0c1.811,0 3.32,1.342 3.32,2.953l-0,157.027c-0,8.053 7.544,14.764 16.597,14.764l27.462,-0c9.054,-0 16.598,-6.711 16.598,-14.764l0,-157.027c0,-1.611 1.509,-2.953 3.32,-2.953l169.6,-0.268c1.811,-0 3.32,1.342 3.32,2.952l-0,157.833c-0,8.053 7.544,14.764 16.598,14.764l27.462,-0c9.053,-0 16.598,-6.711 16.598,-14.764l-0,-158.101c-0,-1.611 1.508,-2.953 3.319,-2.953c0,0 42.249,-0.268 42.853,-0.537c1.811,-1.073 3.018,-2.952 3.018,-5.1l-0,-23.621c-0,-3.221 -3.018,-5.905 -6.941,-5.905l-41.948,-0l0,-0.269l-0.301,0l-0,-8.857c-0,-1.611 1.508,-2.953 3.319,-2.953l38.93,-0c3.621,-0 6.639,-2.684 6.639,-5.905l-0,-23.89c-0,-3.221 -3.018,-5.905 -6.639,-5.905l-38.93,-0c-1.811,-0 -3.319,-1.343 -3.319,-2.953l-0,-15.3c-0,-3.758 3.621,-7.248 8.449,-7.248l5.131,0c3.621,0 5.733,-3.489 6.639,-6.979l5.13,-15.837c0.604,-2.147 2.716,-4.026 5.13,-4.831c38.93,-8.59 54.924,-34.09 68.203,-74.085l-0,-0.268c1.508,-10.2 -5.432,-12.079 -7.847,-12.616Zm-150.89,114.08l0,23.352c0,3.221 -2.112,5.637 -4.828,5.637l-54.321,0c-2.716,0 -4.828,-2.416 -4.828,-5.637l-0,-23.352c-0,-2.953 2.112,-5.637 4.828,-5.637l54.321,-0c2.414,0.268 4.828,2.684 4.828,5.637Zm-111.96,-0l-0,23.352c-0,2.953 -2.112,5.637 -4.828,5.637l-54.321,0c-2.716,0 -4.828,-2.416 -4.828,-5.637l-0,-23.352c-0,-2.953 2.112,-5.637 4.828,-5.637l54.321,-0c2.414,0.268 4.828,2.684 4.828,5.637Z" style="fill:#7e0c1b;fill-rule:nonzero;"/>
+    </g>
+</svg>

docs/_static/jinja-logo.svg

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg width="100%" height="100%" viewBox="0 0 500 500" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xml:space="preserve" xmlns:serif="http://www.serif.com/" style="fill-rule:evenodd;clip-rule:evenodd;stroke-linejoin:round;stroke-miterlimit:2;">
+    <rect id="Logo" x="0" y="0" width="500" height="500" style="fill:none;"/>
+    <path id="Box" d="M500,50l0,400c0,27.596 -22.404,50 -50,50l-400,0c-27.596,0 -50,-22.404 -50,-50l0,-400c0,-27.596 22.404,-50 50,-50l400,0c27.596,0 50,22.404 50,50Z" style="fill:url(#_Linear1);"/>
+    <path id="Shadow" d="M500,246.897l0,203.103c0,27.596 -22.404,50 -50,50l-164.98,0l-119.852,-119.852c1.802,1.562 4.252,2.533 6.921,2.533l16.477,0c5.432,0 9.959,-4.026 9.959,-8.858l-0,-94.216c-0,-0.966 0.905,-1.772 1.992,-1.772l101.76,-0.161c1.086,0 1.992,0.806 1.992,1.772l-0,94.7c-0,4.831 4.526,8.858 9.958,8.858l16.478,-0c5.432,-0 9.958,-4.027 9.958,-8.858l0,-94.861c0,-0.967 0.906,-1.772 1.992,-1.772c0,0 25.35,-0.161 25.712,-0.322c1.086,-0.644 1.81,-1.771 1.81,-3.06l0,-14.173c0,-1.932 -1.81,-3.543 -4.164,-3.543l-25.169,0l0,-0.161l-0.181,0l0,-5.315c0,-0.966 0.906,-1.771 1.992,-1.771l23.358,-0c2.173,-0 3.983,-1.611 3.983,-3.543l0,-14.334c0,-1.933 -1.81,-3.543 -3.983,-3.543l-23.358,-0c-1.086,-0 -1.992,-0.806 -1.992,-1.772l0,-9.18c0,-2.255 2.173,-4.349 5.07,-4.349l3.078,0c2.173,0 3.441,-2.093 3.984,-4.187l3.078,-9.502c0.362,-1.289 1.63,-2.416 3.078,-2.899c23.358,-5.154 32.955,-20.454 40.922,-44.451l-0,-0.161c0.422,-2.854 -0.258,-4.622 -1.252,-5.729l101.379,101.379Zm-375.729,-61.204c4.362,3.788 9.511,6.914 15.588,9.039c1.267,0.483 2.716,0.966 3.983,1.288c1.811,0.322 2.535,1.772 2.898,2.738l3.078,9.502c0.543,2.255 2.173,4.187 3.983,4.187l3.078,0c2.716,0 4.889,1.933 5.07,4.349l0,6.575l-37.678,-37.678Zm9.606,62.5c0.716,0.602 1.677,0.975 2.723,0.975l23.358,-0c1.086,-0 1.991,0.805 1.991,1.771l0,3.866c0,0.966 -0.905,1.771 -1.991,1.771l-17.698,0l-8.383,-8.383Zm0.033,28.751c0.543,0.537 1.236,0.891 1.965,0.891l24.264,0c1.086,0 1.991,0.806 1.991,1.772l0,25.557l-28.22,-28.22Zm170.721,-64.819l-0,14.012c-0,1.933 -1.268,3.382 -2.897,3.382l-32.593,0c-1.629,0 -2.897,-1.449 -2.897,-3.382l0,-14.012c0,-1.771 1.268,-3.382 2.897,-3.382l32.593,0c1.448,0.161 2.897,1.611 2.897,3.382Zm-67.176,0l-0,14.012c-0,1.772 -1.268,3.382 -2.897,3.382l-32.593,0c-1.629,0 -2.897,-1.449 -2.897,-3.382l0,-14.012c0,-1.771 1.268,-3.382 2.897,-3.382l32.593,0c1.448,0.161 2.897,1.611 2.897,3.382Z" style="fill:#630b28;"/>
+    <path id="Icon" d="M395.165,143.677l-1.087,0c-53.234,17.716 -122.945,17.716 -142.319,17.394l-17.926,-0.322c-52.872,-1.933 -79.851,-22.225 -127.109,-43.323c-3.26,-1.45 -7.062,0.966 -6.7,4.348c0.362,11.596 3.44,60.234 39.835,72.958c1.267,0.483 2.716,0.966 3.983,1.288c1.811,0.322 2.535,1.772 2.898,2.738l3.078,9.502c0.543,2.255 2.173,4.187 3.983,4.187l3.078,0c2.716,0 4.889,1.933 5.07,4.349l0,9.18c0,0.966 -0.905,1.772 -1.991,1.772l-23.358,-0c-2.173,-0 -3.984,1.61 -3.984,3.543l0,14.334c0,1.932 1.811,3.543 3.984,3.543l23.358,-0c1.086,-0 1.991,0.805 1.991,1.771l0,3.866c0,0.966 -0.905,1.771 -1.991,1.771l-23.358,0c-2.173,0.161 -3.803,1.611 -3.803,3.543l0,14.334c0,1.611 1.449,3.382 3.078,3.382l24.264,0c1.086,0 1.991,0.806 1.991,1.772l0,94.216c0,4.832 4.527,8.858 9.959,8.858l16.477,0c5.432,0 9.959,-4.026 9.959,-8.858l-0,-94.216c-0,-0.966 0.905,-1.772 1.992,-1.772l101.76,-0.161c1.086,0 1.992,0.806 1.992,1.772l-0,94.7c-0,4.831 4.526,8.858 9.958,8.858l16.478,-0c5.432,-0 9.958,-4.027 9.958,-8.858l0,-94.861c0,-0.967 0.906,-1.772 1.992,-1.772c0,0 25.35,-0.161 25.712,-0.322c1.086,-0.644 1.81,-1.771 1.81,-3.06l0,-14.173c0,-1.932 -1.81,-3.543 -4.164,-3.543l-25.169,0l0,-0.161l-0.181,0l0,-5.315c0,-0.966 0.906,-1.771 1.992,-1.771l23.358,-0c2.173,-0 3.983,-1.611 3.983,-3.543l0,-14.334c0,-1.933 -1.81,-3.543 -3.983,-3.543l-23.358,-0c-1.086,-0 -1.992,-0.806 -1.992,-1.772l0,-9.18c0,-2.255 2.173,-4.349 5.07,-4.349l3.078,0c2.173,0 3.441,-2.093 3.984,-4.187l3.078,-9.502c0.362,-1.289 1.63,-2.416 3.078,-2.899c23.358,-5.154 32.955,-20.454 40.922,-44.451l-0,-0.161c0.905,-6.12 -3.26,-7.247 -4.708,-7.57Zm-90.534,68.448l-0,14.012c-0,1.933 -1.268,3.382 -2.897,3.382l-32.593,0c-1.629,0 -2.897,-1.449 -2.897,-3.382l0,-14.012c0,-1.771 1.268,-3.382 2.897,-3.382l32.593,0c1.448,0.161 2.897,1.611 2.897,3.382Zm-67.176,0l-0,14.012c-0,1.772 -1.268,3.382 -2.897,3.382l-32.593,0c-1.629,0 -2.897,-1.449 -2.897,-3.382l0,-14.012c0,-1.771 1.268,-3.382 2.897,-3.382l32.593,0c1.448,0.161 2.897,1.611 2.897,3.382Z" style="fill:#fff;fill-rule:nonzero;"/>
+    <defs>
+        <linearGradient id="_Linear1" x1="0" y1="0" x2="1" y2="0" gradientUnits="userSpaceOnUse" gradientTransform="matrix(3.06162e-14,500,-500,3.06162e-14,267.59,0)"><stop offset="0" style="stop-color:#f6cadc;stop-opacity:1"/><stop offset="1" style="stop-color:#7f0d18;stop-opacity:1"/></linearGradient>
+    </defs>
+</svg>

docs/_static/jinja-name.svg

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg width="100%" height="100%" viewBox="0 0 664 300" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xml:space="preserve" xmlns:serif="http://www.serif.com/" style="fill-rule:evenodd;clip-rule:evenodd;stroke-linejoin:round;stroke-miterlimit:2;">
+    <g>
+        <path id="Name" d="M416,89.625l0,68.7c0,14.3 -2.95,24.375 -8.85,30.225c-5.9,5.85 -14.45,8.775 -25.65,8.775c-7.2,-0 -13.225,-0.95 -18.075,-2.85c-4.85,-1.9 -9.325,-4.9 -13.425,-9l11.7,-12.75c1.7,1.7 4.275,3.125 7.725,4.275c3.45,1.15 7.4,1.725 11.85,1.725c4.45,-0 7.875,-1.075 10.275,-3.225c2.4,-2.15 3.6,-6.175 3.6,-12.075l0,-73.8l20.85,-0Z" style="fill-rule:nonzero;"/>
+        <path d="M446.45,78.075c4.7,-0 7.75,0.725 9.15,2.175c1.4,1.45 2.1,4.5 2.1,9.15c0,4.65 -0.725,7.7 -2.175,9.15c-1.45,1.45 -4.5,2.175 -9.15,2.175c-4.65,-0 -7.7,-0.75 -9.15,-2.25c-1.45,-1.5 -2.175,-4.55 -2.175,-9.15c0,-4.6 0.725,-7.625 2.175,-9.075c1.45,-1.45 4.525,-2.175 9.225,-2.175Zm9.6,118.35l-19.5,-0l0,-82.5l19.5,-0l0,82.5Z" style="fill-rule:nonzero;"/>
+        <path d="M544.25,196.425l-19.5,-0l0,-54.75c0,-4.9 -1,-8.25 -3,-10.05c-2,-1.8 -4.8,-2.7 -8.4,-2.7l-17.55,7.35l0,60.15l-19.5,-0l0,-85.65l14.55,-0l4.5,10.2l24,-11.1c6.7,-0 12.525,2.475 17.475,7.425c4.95,4.95 7.425,12.175 7.425,21.675l0,57.45Z" style="fill-rule:nonzero;"/>
+        <path d="M583.25,113.925l0,85.65c0,6.1 -1.925,11.35 -5.775,15.75c-3.85,4.4 -9.525,6.6 -17.025,6.6l-11.1,-0l0,-16.5l7.5,-0c4.6,-0 6.9,-2.35 6.9,-7.05l0,-84.45l19.5,-0Zm-9.6,-35.85c4.7,-0 7.75,0.725 9.15,2.175c1.4,1.45 2.1,4.5 2.1,9.15c0,4.65 -0.725,7.7 -2.175,9.15c-1.45,1.45 -4.5,2.175 -9.15,2.175c-4.65,-0 -7.7,-0.75 -9.15,-2.25c-1.45,-1.5 -2.175,-4.55 -2.175,-9.15c0,-4.6 0.725,-7.625 2.175,-9.075c1.45,-1.45 4.525,-2.175 9.225,-2.175Z" style="fill-rule:nonzero;"/>
+        <path d="M663.95,196.425l-13.05,-0l-6,-10.35l-20.85,11.25c-11.6,-0 -19.4,-4.2 -23.4,-12.6c-2,-4.1 -3.375,-8.525 -4.125,-13.275c-0.75,-4.75 -1.125,-9.7 -1.125,-14.85c0,-5.15 0.05,-8.95 0.15,-11.4c0.1,-2.45 0.35,-5.3 0.75,-8.55c0.4,-3.25 0.975,-5.975 1.725,-8.175c0.75,-2.2 1.825,-4.475 3.225,-6.825c1.4,-2.35 3.1,-4.225 5.1,-5.625c4.5,-3.1 10.35,-4.65 17.55,-4.65l20.55,-0l19.5,-1.2l0,86.25Zm-19.5,-27.3l0,-40.2l-14.85,-0c-5.5,-0 -9.325,2.1 -11.475,6.3c-2.15,4.2 -3.225,10.475 -3.225,18.825c0,8.35 1.025,14.225 3.075,17.625c2.05,3.4 5.925,5.1 11.625,5.1l14.85,-7.65Z" style="fill-rule:nonzero;"/>
+        <g id="Logo">
+            <path id="Box" d="M300,30l-0,240c-0,16.557 -13.443,30 -30,30l-240,-0c-16.557,-0 -30,-13.443 -30,-30l0,-240c0,-16.557 13.443,-30 30,-30l240,0c16.557,0 30,13.443 30,30Z" style="fill:url(#_Linear1);"/>
+            <path id="Shadow" d="M300,148.138l0,121.862c0,16.557 -13.443,30 -30,30l-98.988,-0l-71.911,-71.911c1.081,0.937 2.551,1.52 4.152,1.52l9.887,-0c3.259,-0 5.975,-2.416 5.975,-5.315l-0,-56.53c-0,-0.58 0.543,-1.063 1.195,-1.063l61.056,-0.096c0.652,-0 1.195,0.483 1.195,1.063l0,56.819c0,2.899 2.716,5.315 5.975,5.315l9.887,0c3.259,0 5.975,-2.416 5.975,-5.315l-0,-56.916c-0,-0.58 0.543,-1.063 1.195,-1.063c0,-0 15.21,-0.097 15.427,-0.193c0.652,-0.387 1.086,-1.063 1.086,-1.836l0,-8.504c0,-1.16 -1.086,-2.126 -2.498,-2.126l-15.101,0l-0,-0.097l-0.109,0l-0,-3.188c-0,-0.58 0.543,-1.063 1.195,-1.063l14.015,-0c1.303,-0 2.39,-0.967 2.39,-2.126l-0,-8.601c-0,-1.159 -1.087,-2.125 -2.39,-2.125l-14.015,-0c-0.652,-0 -1.195,-0.484 -1.195,-1.063l-0,-5.508c-0,-1.353 1.304,-2.61 3.042,-2.61l1.847,0c1.304,0 2.064,-1.256 2.39,-2.512l1.847,-5.701c0.217,-0.773 0.978,-1.45 1.847,-1.74c14.014,-3.092 19.772,-12.272 24.553,-26.67l-0,-0.097c0.253,-1.712 -0.155,-2.773 -0.751,-3.437l60.827,60.827Zm-225.437,-36.722c2.617,2.273 5.706,4.148 9.352,5.423c0.761,0.29 1.63,0.58 2.39,0.773c1.087,0.193 1.521,1.063 1.739,1.643l1.847,5.701c0.326,1.353 1.303,2.512 2.39,2.512l1.847,0c1.629,0 2.933,1.16 3.042,2.61l-0,3.945l-22.607,-22.607Zm5.763,37.5c0.43,0.361 1.007,0.585 1.634,0.585l14.015,-0c0.651,-0 1.195,0.483 1.195,1.063l-0,2.319c-0,0.58 -0.544,1.063 -1.195,1.063l-10.619,-0l-5.03,-5.03Zm0.02,17.251c0.326,0.321 0.742,0.534 1.179,0.534l14.558,0c0.652,0 1.195,0.483 1.195,1.063l0,15.335l-16.932,-16.932Zm102.432,-38.892l0,8.407c0,1.16 -0.76,2.029 -1.738,2.029l-19.555,0c-0.978,0 -1.738,-0.869 -1.738,-2.029l-0,-8.407c-0,-1.063 0.76,-2.029 1.738,-2.029l19.555,-0c0.869,0.097 1.738,0.966 1.738,2.029Zm-40.305,0l-0,8.407c-0,1.063 -0.761,2.029 -1.738,2.029l-19.556,0c-0.978,0 -1.738,-0.869 -1.738,-2.029l-0,-8.407c-0,-1.063 0.76,-2.029 1.738,-2.029l19.556,-0c0.869,0.097 1.738,0.966 1.738,2.029Z" style="fill:#630b28;"/>
+            <path id="Icon" d="M237.099,86.206l-0.652,0c-31.94,10.63 -73.767,10.63 -85.392,10.437l-10.755,-0.194c-31.723,-1.159 -47.911,-13.335 -76.266,-25.994c-1.955,-0.869 -4.237,0.58 -4.02,2.609c0.218,6.958 2.065,36.141 23.901,43.775c0.761,0.29 1.63,0.58 2.39,0.773c1.087,0.193 1.521,1.063 1.739,1.643l1.847,5.701c0.326,1.353 1.303,2.512 2.39,2.512l1.847,0c1.629,0 2.933,1.16 3.042,2.61l-0,5.508c-0,0.579 -0.544,1.063 -1.195,1.063l-14.015,-0c-1.304,-0 -2.39,0.966 -2.39,2.125l-0,8.601c-0,1.159 1.086,2.126 2.39,2.126l14.015,-0c0.651,-0 1.195,0.483 1.195,1.063l-0,2.319c-0,0.58 -0.544,1.063 -1.195,1.063l-14.015,-0c-1.304,0.096 -2.282,0.966 -2.282,2.126l0,8.6c0,0.966 0.87,2.029 1.847,2.029l14.558,0c0.652,0 1.195,0.483 1.195,1.063l0,56.53c0,2.899 2.716,5.315 5.975,5.315l9.887,-0c3.259,-0 5.975,-2.416 5.975,-5.315l-0,-56.53c-0,-0.58 0.543,-1.063 1.195,-1.063l61.056,-0.096c0.652,-0 1.195,0.483 1.195,1.063l0,56.819c0,2.899 2.716,5.315 5.975,5.315l9.887,0c3.259,0 5.975,-2.416 5.975,-5.315l-0,-56.916c-0,-0.58 0.543,-1.063 1.195,-1.063c0,-0 15.21,-0.097 15.427,-0.193c0.652,-0.387 1.086,-1.063 1.086,-1.836l0,-8.504c0,-1.16 -1.086,-2.126 -2.498,-2.126l-15.101,0l-0,-0.097l-0.109,0l-0,-3.188c-0,-0.58 0.543,-1.063 1.195,-1.063l14.015,-0c1.303,-0 2.39,-0.967 2.39,-2.126l-0,-8.601c-0,-1.159 -1.087,-2.125 -2.39,-2.125l-14.015,-0c-0.652,-0 -1.195,-0.484 -1.195,-1.063l-0,-5.508c-0,-1.353 1.304,-2.61 3.042,-2.61l1.847,0c1.304,0 2.064,-1.256 2.39,-2.512l1.847,-5.701c0.217,-0.773 0.978,-1.45 1.847,-1.74c14.014,-3.092 19.772,-12.272 24.553,-26.67l-0,-0.097c0.543,-3.672 -1.956,-4.348 -2.825,-4.542Zm-54.321,41.069l0,8.407c0,1.16 -0.76,2.029 -1.738,2.029l-19.555,0c-0.978,0 -1.738,-0.869 -1.738,-2.029l-0,-8.407c-0,-1.063 0.76,-2.029 1.738,-2.029l19.555,-0c0.869,0.097 1.738,0.966 1.738,2.029Zm-40.305,0l-0,8.407c-0,1.063 -0.761,2.029 -1.738,2.029l-19.556,0c-0.978,0 -1.738,-0.869 -1.738,-2.029l-0,-8.407c-0,-1.063 0.76,-2.029 1.738,-2.029l19.556,-0c0.869,0.097 1.738,0.966 1.738,2.029Z" style="fill:#fff;fill-rule:nonzero;"/>
+        </g>
+    </g>
+    <defs>
+        <linearGradient id="_Linear1" x1="0" y1="0" x2="1" y2="0" gradientUnits="userSpaceOnUse" gradientTransform="matrix(1.83697e-14,300,-300,1.83697e-14,160.554,0)"><stop offset="0" style="stop-color:#f6cadc;stop-opacity:1"/><stop offset="1" style="stop-color:#7f0d18;stop-opacity:1"/></linearGradient>
+    </defs>
+</svg>

docs/_static/jinja.js

@@ -1,26 +0,0 @@
-$(function() {
-
-  var
-    toc = $('#toc').show(),
-    items = $('#toc > ul').hide();
-
-  $('#toc h3')
-    .click(function() {
-      if (items.is(':visible')) {
-        items.animate({
-          height:     'hide',
-          opacity:    'hide'
-        }, 300, function() {
-          toc.removeClass('expandedtoc');
-        });
-      }
-      else {
-        items.animate({
-          height:     'show',
-          opacity:    'show'
-        }, 400);
-        toc.addClass('expandedtoc');
-      }
-    });
-
-});

docs/_static/print.css

@@ -1,5 +0,0 @@
-div.header, div.relnav, #toc { display: none; }
-#contentwrapper { padding: 0; margin: 0; border: none; }
-body { color: black; background-color: white; }
-div.footer { border-top: 1px solid #888; color: #888; margin-top: 1cm; }
-div.footer a { text-decoration: none; }

docs/_static/style.css

@@ -1,390 +0,0 @@
-body {
-    background-color: #222;
-    margin: 0;
-    padding: 0;
-    font-family: 'Georgia', serif;
-    font-size: 15px;
-    color: #eee;
-}
-
-div.footer {
-    border-top: 1px solid #111;
-    padding: 8px;
-    font-size: 11px;
-    text-align: center;
-    letter-spacing: 0.5px;
-}
-
-div.footer a {
-    color: #eee;
-}
-
-div.header {
-    margin: 0 -15px 0 -15px;
-    background: url(headerbg.png) repeat-x;
-    border-top: 6px solid #D20000;
-}
-
-div.relnav {
-    border-bottom: 1px solid #111;
-    background: url(navigation.png);
-    margin: 0 -15px 0 -15px;
-    padding: 2px 20px 0 28px;
-    line-height: 25px;
-    color: #aaa;
-    font-size: 12px;
-    text-align: center;
-}
-
-div.relnav a {
-    color: #eee;
-    font-weight: bold;
-    text-decoration: none;
-}
-
-div.relnav a:hover {
-    text-decoration: underline;
-}
-
-#content {
-    background-color: white;
-    color: #111;
-    border-bottom: 1px solid black;
-    background: url(watermark.png) center 0;
-    padding: 0 15px 0 15px;
-    margin: 0;
-}
-
-h1 {
-    margin: 0;
-    padding: 15px 0 0 0;
-}
-
-h1.heading {
-    margin: 0;
-    padding: 0;
-    height: 80px;
-}
-
-h1.heading:hover {
-    background: #222;
-}
-
-h1.heading a {
-    background: url(jinjabanner.png) no-repeat center 0;
-    display: block;
-    width: 100%;
-    height: 80px;
-}
-
-h1.heading a:focus {
-    -moz-outline: none;
-    outline: none;
-}
-
-h1.heading span {
-    display: none;
-}
-
-#jinjalogo {
-    background-image: url(jinjalogo.png);
-    background-repeat: no-repeat;
-    width: 400px;
-    height: 160px;
-}
-
-#contentwrapper {
-    max-width: 680px;
-    padding: 0 18px 20px 18px;
-    margin: 0 auto 0 auto;
-    border-right: 1px solid #eee;
-    border-left: 1px solid #eee;
-    background: url(watermark_blur.png) center -114px;
-}
-
-#contentwrapper h2,
-#contentwrapper h2 a {
-    color: #222;
-    font-size: 24px;
-    margin: 20px 0 0 0;
-}
-
-#contentwrapper h3,
-#contentwrapper h3 a {
-    color: #b41717;
-    font-size: 20px;
-    margin: 20px 0 0 0;
-}
-
-table.docutils {
-    border-collapse: collapse;
-    border: 2px solid #aaa;
-    margin: 0.5em 1.5em 0.5em 1.5em;
-}
-
-table.docutils td {
-    padding: 2px;
-    border: 1px solid #ddd;
-}
-
-p, li, dd, dt, blockquote {
-    color: #333;
-}
-
-blockquote {
-    margin: 10px 0 10px 20px;
-}
-
-p {
-    line-height: 20px;
-    margin-bottom: 0;
-    margin-top: 10px;
-}
-
-hr {
-    border-top: 1px solid #ccc;
-    border-bottom: 0;
-    border-right: 0;
-    border-left: 0;
-    margin-bottom: 10px;
-    margin-top: 20px;
-}
-
-dl {
-    margin-left: 10px;
-}
-
-li, dt {
-    margin-top: 5px;
-}
-
-dt {
-    font-weight: bold;
-    color: #000;
-}
-
-dd {
-    margin-top: 10px;
-    line-height: 20px;
-}
-
-th {
-    text-align: left;
-    padding: 3px;
-    background-color: #f2f2f2;
-}
-
-a {
-    color: #b41717;
-}
-
-a:hover {
-    color: #444;
-}
-
-pre {
-    background: #ededed url(metal.png);
-    border-top: 1px solid #ccc;
-    border-bottom: 1px solid #ccc;
-    padding: 5px;
-    font-size: 13px;
-    font-family: 'Bitstream Vera Sans Mono', 'Monaco', monospace;
-}
-
-tt {
-    font-size: 13px;
-    font-family: 'Bitstream Vera Sans Mono', 'Monaco', monospace;
-    color: black;
-    padding: 1px 2px 1px 2px;
-    background-color: #fafafa;
-    border-bottom: 1px solid #eee;
-}
-
-a.reference:hover tt {
-    border-bottom-color: #aaa;
-}
-
-cite {
-    /* abusing <cite>, it's generated by ReST for `x` */
-    font-size: 13px;
-    font-family: 'Bitstream Vera Sans Mono', 'Monaco', monospace;
-    font-weight: bold;
-    font-style: normal;
-}
-
-div.admonition {
-    margin: 10px 0 10px 0;
-    padding: 10px 10px 10px 60px;
-    border: 1px solid #ccc;
-}
-
-div.admonition p.admonition-title {
-    background-color: #b41717;
-    color: white;
-    margin: -10px -10px 10px -60px;
-    padding: 4px 10px 4px 10px;
-    font-weight: bold;
-    font-size: 15px;
-}
-
-div.admonition p.admonition-title a {
-    color: white!important;
-}
-
-div.admonition-note {
-    background: url(note.png) no-repeat 10px 40px;
-}
-
-div.admonition-implementation {
-    background: url(implementation.png) no-repeat 10px 40px;
-}
-
-a.headerlink {
-    color: #B4B4B4!important;
-    font-size: 0.8em;
-    padding: 0 4px 0 4px;
-    text-decoration: none!important;
-    visibility: hidden;
-}
-
-h1:hover > a.headerlink,
-h2:hover > a.headerlink,
-h3:hover > a.headerlink,
-h4:hover > a.headerlink,
-h5:hover > a.headerlink,
-h6:hover > a.headerlink,
-dt:hover > a.headerlink,
-dt:hover > a.headerlink {
-    visibility: visible;
-}
-
-a.headerlink:hover {
-    background-color: #B4B4B4;
-    color: #F0F0F0!important;
-}
-
-table.indextable {
-    width: 100%;
-}
-
-table.indextable td {
-    vertical-align: top;
-    width: 50%;
-}
-
-table.indextable dl dd {
-    font-size: 11px;
-}
-
-table.indextable dl dd a {
-    color: #000;
-}
-
-dl.function dt,
-dl.class dt,
-dl.exception dt,
-dl.method dt,
-dl.attribute dt {
-    font-weight: normal;
-}
-
-dt .descname {
-    font-weight: bold;
-    margin-right: 4px;
-}
-
-dt .descname, dt .descclassname {
-    padding: 0;
-    background: transparent;
-    border-bottom: 1px solid #111;
-}
-
-dt .descclassname {
-    margin-left: 2px;
-}
-
-dl dt big {
-    font-size: 100%;
-}
-
-ul.search {
-    margin: 10px 0 0 30px;
-    padding: 0;
-}
-
-ul.search li {
-    margin: 10px 0 0 0;
-    padding: 0;
-}
-
-ul.search div.context {
-    font-size: 12px;
-    padding: 4px 0 0 20px;
-    color: #888;
-}
-
-span.highlight {
-    background-color: #eee;
-    border: 1px solid #ccc;
-}
-
-#toc {
-    margin: 0 -17px 0 -17px;
-    display: none;
-}
-
-#toc h3 {
-    float: right;
-    margin: 5px 5px 0 0;
-    padding: 0;
-    font-size: 12px;
-    color: #777;
-}
-
-#toc h3:hover {
-    color: #333;
-    cursor: pointer;
-}
-
-.expandedtoc {
-    background: #222 url(darkmetal.png);
-    border-bottom: 1px solid #111;
-    outline-bottom: 1px solid #000;
-    padding: 5px;
-}
-
-.expandedtoc h3 {
-    color: #aaa;
-    margin: 0!important;
-}
-
-.expandedtoc h3:hover {
-    color: white!important;
-}
-
-#tod h3:hover {
-    color: white;
-}
-
-#toc a {
-    color: #ddd;
-    text-decoration: none;
-}
-
-#toc a:hover {
-    color: white;
-    text-decoration: underline;
-}
-
-#toc ul {
-    margin: 5px 0 12px 17px;
-    padding: 0 7px 0 7px;
-}
-
-#toc ul ul {
-    margin-bottom: 0;
-}
-
-#toc ul li {
-    margin: 2px 0 0 0;
-}

docs/_templates/genindex.html

@@ -1,36 +0,0 @@
-{% extends "layout.html" %}
-{% set title = 'Index' %}
-{% block body %}
-
-  <h1 id="index">Index</h1>
-
-  {% for key, dummy in genindexentries -%}
-  <a href="#{{ key }}"><strong>{{ key }}</strong></a> {% if not loop.last %}| {% endif %}
-  {%- endfor %}
-  <hr>
-
-  {% for key, entries in genindexentries %}
-    <h2 id="{{ key }}">{{ key }}</h2>
-    <table class="indextable"><tr>
-    {%- for column in entries|slice(2) if column %}
-      <td><dl>
-      {%- for entryname, (links, subitems) in column %}
-        <dt>{% if links %}<a href="{{ links[0] }}">{{ entryname|e }}</a>
-          {% for link in links[1:] %}, <a href="{{ link }}">[Link]</a>{% endfor %}
-          {%- else %}{{ entryname|e }}{% endif %}</dt>
-        {%- if subitems %}
-        <dd><dl>
-          {%- for subentryname, subentrylinks in subitems %}
-          <dt><a href="{{ subentrylinks[0] }}">{{ subentryname|e }}</a>
-          {%- for link in subentrylinks[1:] %}, <a href="{{ link }}">[Link]</a>{% endfor -%}
-          </dt>
-          {%- endfor %}
-        </dl></dd>
-        {%- endif -%}
-      {%- endfor %}
-      </dl></td>
-    {%- endfor %}
-    </tr></table>
-  {% endfor %}
-
-{% endblock %}

docs/_templates/layout.html

@@ -1,77 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
-<html>
-  <head>
-    <title>Jinja2 Documentation</title>
-    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
-    <link rel="stylesheet" href="{{ pathto('_static/style.css', 1) }}" type="text/css">
-    <link rel="stylesheet" href="{{ pathto('_static/print.css', 1) }}" type="text/css" media="print">
-    <link rel="stylesheet" href="{{ pathto('_static/pygments.css', 1) }}" type="text/css">
-    {%- if builder != 'htmlhelp' %}
-    <script type="text/javascript">
-      var DOCUMENTATION_OPTIONS = {
-        URL_ROOT:   '{{ pathto("", 1) }}',
-        VERSION:    '{{ release }}'
-      };
-    </script>
-    <script type="text/javascript" src="{{ pathto('_static/jquery.js', 1) }}"></script>
-    <script type="text/javascript" src="{{ pathto('_static/interface.js', 1) }}"></script>
-    <script type="text/javascript" src="{{ pathto('_static/doctools.js', 1) }}"></script>
-    <script type="text/javascript" src="{{ pathto('_static/jinja.js', 1) }}"></script>
-    {%- endif %}
-    {%- if use_opensearch and builder != 'htmlhelp' %}
-    <link rel="search" type="application/opensearchdescription+xml"
-          title="Search within {{ docstitle }}"
-          href="{{ pathto('_static/opensearch.xml', 1) }}">
-    {%- endif %}
-    {%- if hasdoc('about') %}
-    <link rel="author" title="About these documents" href="{{ pathto('about') }}">
-    {%- endif %}
-    <link rel="contents" title="Global table of contents" href="{{ pathto('contents') }}">
-    <link rel="index" title="Global index" href="{{ pathto('genindex') }}">
-    <link rel="search" title="Search" href="{{ pathto('search') }}">
-    {%- if hasdoc('copyright') %}
-    <link rel="copyright" title="Copyright" href="{{ pathto('copyright') }}">
-    {%- endif %}
-    <link rel="top" title="{{ docstitle }}" href="{{ pathto('index') }}">
-    {%- if parents %}
-    <link rel="up" title="{{ parents[-1].title|striptags }}" href="{{ parents[-1].link|e }}">
-    {%- endif %}
-    {%- if next %}
-    <link rel="next" title="{{ next.title|striptags }}" href="{{ next.link|e }}">
-    {%- endif %}
-    {%- if prev %}
-    <link rel="prev" title="{{ prev.title|striptags }}" href="{{ prev.link|e }}">
-    {%- endif %}
-    {% block extrahead %}{% endblock %}
-  </head>
-  <body>
-    <div id="content">
-      <div class="header">
-        <h1 class="heading"><a href="{{ pathto('index') }}"
-          title="back to the documentation overview"><span>Jinja</span></a></h1>
-      </div>
-      <div class="relnav">
-        {%- if prev %}
-        <a href="{{ prev.link|e }}">&laquo; {{ prev.title }}</a> |
-        {%- endif %}
-        <a href="{{ pathto(current_page_name) if current_page_name else '#' }}">{{ title }}</a>
-        {%- if next %}
-        | <a href="{{ next.link|e }}">{{ next.title }} &raquo;</a>
-        {%- endif %}
-      </div>
-      <div id="contentwrapper">
-        {%- if display_toc %}
-        <div id="toc">
-          <h3>Table Of Contents</h3>
-          {{ toc }}
-        </div>
-        {%- endif %}
-        {% block body %}{% endblock %}
-      </div>
-    </div>
-    <div class="footer">
-      © Copyright 2008 by the <a href="http://pocoo.org/">Pocoo Team</a>,
-      documentation generated by <a href="http://sphinx.pocoo.org/">Sphinx</a>
-    </div>
-  </body>
-</html>

docs/_templates/opensearch.xml

@@ -1,9 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/">
-  <ShortName>{{ project }}</ShortName>
-  <Description>Search {{ docstitle }}</Description>
-  <InputEncoding>utf-8</InputEncoding>
-  <Url type="text/html" method="get"
-       template="{{ use_opensearch }}/{{ pathto('search') }}?q={searchTerms}&amp;check_keywords=yes&amp;area=default"/>
-  <LongName>{{ docstitle }}</LongName>
-</OpenSearchDescription>

docs/_templates/page.html

@@ -1,4 +0,0 @@
-{% extends 'layout.html' %}
-{% block body %}
-  {{ body }}
-{% endblock %}

docs/_templates/search.html

@@ -1,35 +0,0 @@
-{% extends "layout.html" %}
-{% set title = 'Search' %}
-{% block extrahead %}
-    <script type="text/javascript" src="{{ pathto('_static/searchtools.js', 1) }}"></script>
-{% endblock %}
-{% block body %}
-  <h1 id="search-documentation">Search</h1>
-  <p>
-    From here you can search these documents. Enter your search
-    words into the box below and click "search". Note that the search
-    function will automatically search for all of the words. Pages
-    containing less words won't appear in the result list.
-  </p>
-  <form action="" method="get"><p>
-    <input type="text" name="q" value="">
-    <input type="submit" value="search">
-  </p></form>
-  {% if search_performed %}
-    <h2>Search Results</h2>
-    {% if not search_results %}
-      <p>Your search did not match any results.</p>
-    {% endif %}
-  {% endif %}
-  <div id="search-results">
-  {% if search_results %}
-    <ul>
-    {% for href, caption, context in search_results %}
-      <li><a href="{{ pathto(item.href) }}">{{ caption }}</a>
-        <div class="context">{{ context|e }}</div>
-      </li>
-    {% endfor %}
-    </ul>
-  {% endif %}
-  </div>
-{% endblock %}

docs/api.rst

@@ -2,120 +2,87 @@ API
 ===
 
 .. module:: jinja2
-    :synopsis: public Jinja2 API
+    :noindex:
+    :synopsis: public Jinja API
 
-This document describes the API to Jinja2 and not the template language.  It
-will be most useful as reference to those implementing the template interface
-to the application and not those who are creating Jinja2 templates.
+This document describes the API to Jinja and not the template language
+(for that, see :doc:`/templates`). It will be most useful as reference
+to those implementing the template interface to the application and not
+those who are creating Jinja templates.
 
 Basics
 ------
 
-Jinja2 uses a central object called the template :class:`Environment`.
-Instances of this class are used to store the configuration, global objects
+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
 :class:`Template` class, an environment is created automatically for you,
 albeit a shared one.
 
 Most applications will create one :class:`Environment` object on application
-initialization and use that to load templates.  In some cases it's however
+initialization and use that to load templates.  In some cases however, it's
 useful to have multiple environments side by side, if different configurations
 are in use.
 
-The simplest way to configure Jinja2 to load templates for your application
-looks roughly like this::
+The simplest way to configure Jinja to load templates for your
+application is to use :class:`~loaders.PackageLoader`.
 
-    from jinja2 import Environment, PackageLoader
-    env = Environment(loader=PackageLoader('yourapplication', 'templates'))
+.. code-block:: python
 
-This will create a template environment with the default settings and a
-loader that looks up the templates in the `templates` folder inside the
-`yourapplication` python package.  Different loaders are available
-and you can also write your own if you want to load templates from a
-database or other resources.
+    from jinja2 import Environment, PackageLoader, select_autoescape
+    env = Environment(
+        loader=PackageLoader("yourapp"),
+        autoescape=select_autoescape()
+    )
 
-To load a template from this environment you just have to call the
-:meth:`get_template` method which then returns the loaded :class:`Template`::
+This will create a template environment with a loader that looks up
+templates in the ``templates`` folder inside the ``yourapp`` Python
+package (or next to the ``yourapp.py`` Python module). It also enables
+autoescaping for HTML files. This loader only requires that ``yourapp``
+is importable, it figures out the absolute path to the folder for you.
 
-    template = env.get_template('mytemplate.html')
+Different loaders are available to load templates in other ways or from
+other locations. They're listed in the `Loaders`_ section below. You can
+also write your own if you want to load templates from a source that's
+more specialized to your project.
 
-To render it with some variables, just call the :meth:`render` method::
+To load a template from this environment, call the :meth:`get_template`
+method, which returns the loaded :class:`Template`.
 
-    print template.render(the='variables', go='here')
+.. code-block:: python
 
-Using a template loader rather then passing strings to :class:`Template`
+    template = env.get_template("mytemplate.html")
+
+To render it with some variables, call the :meth:`render` method.
+
+.. code-block:: python
+
+    print(template.render(the="variables", go="here"))
+
+Using a template loader rather than passing strings to :class:`Template`
 or :meth:`Environment.from_string` has multiple advantages.  Besides being
 a lot easier to use it also enables template inheritance.
 
+.. admonition:: Notes on Autoescaping
 
-Unicode
--------
+   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.
 
-Jinja2 is using unicode internally which means that you have to pass unicode
-objects to the render function or bytestrings that only consist of ASCII
-characters.  Additionally newlines are normalized to one end of line
-sequence which is per default UNIX style (``\n``).
-
-Python 2.x supports two ways of representing string objects.  One is the
-`str` type and the other is the `unicode` type, both of which extend a type
-called `basestring`.  Unfortunately the default is `str` which should not
-be used to store text based information unless only ASCII characters are
-used.  With Python 2.6 it is possible to make `unicode` the default on a per
-module level and with Python 3 it will be the default.
-
-To explicitly use a unicode string you have to prefix the string literal
-with a `u`: ``u'Hänsel und Gretel sagen Hallo'``.  That way Python will
-store the string as unicode by decoding the string with the character
-encoding from the current Python module.  If no encoding is specified this
-defaults to 'ASCII' which means that you can't use any non ASCII identifier.
-
-To set a better module encoding add the following comment to the first or
-second line of the Python module using the unicode literal::
-
-    # -*- coding: utf-8 -*-
-
-We recommend utf-8 as Encoding for Python modules and templates as it's
-possible to represent every Unicode character in utf-8 and because it's
-backwards compatible to ASCII.  For Jinja2 the default encoding of templates
-is assumed to be utf-8.
-
-It is not possible to use Jinja2 to process non unicode data.  The reason
-for this is that Jinja2 uses Unicode already on the language level.  For
-example Jinja2 treats the non-breaking space as valid whitespace inside
-expressions which requires knowledge of the encoding or operating on an
-unicode string.
-
-For more details about unicode in Python have a look at the excellent
-`Unicode documentation`_.
-
-Another important thing is how Jinja2 is handling string literals in
-templates.  A naive implementation would be using unicode strings for
-all string literals but it turned out in the past that this is problematic
-as some libraries are typechecking against `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
-for everything else `unicode`:
-
->>> m = Template(u"{% set a, b = 'foo', 'föö' %}").module
->>> m.a
-'foo'
->>> m.b
-u'f\xf6\xf6'
-
-
-.. _Unicode documentation: http://docs.python.org/dev/howto/unicode.html
 
 High Level API
 --------------
 
 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])
-    :members: from_string, get_template, join_path, extend, compile_expression
+    :members: from_string, get_template, select_template,
+              get_or_select_template, join_path, extend, compile_expression,
+              compile_templates, list_templates, add_extension
 
     .. attribute:: shared
 
@@ -147,10 +114,29 @@ useful if you want to dig deeper into Jinja2 or :ref:`develop extensions
 
     .. attribute:: globals
 
-        A dict of global variables.  These variables are always available
-        in a template.  As long as no template was loaded it's safe
-        to modify this dict.  For more details see :ref:`global-namespace`.
-        For valid object names have a look at :ref:`identifier-naming`.
+        A dict of variables that are available in every template loaded
+        by the environment. As long as no template was loaded it's safe
+        to modify this. For more details see :ref:`global-namespace`.
+        For valid object names see :ref:`identifier-naming`.
+
+    .. attribute:: policies
+
+        A dictionary with :ref:`policies`.  These can be reconfigured to
+        change the runtime behavior or certain template features.  Usually
+        these are security related.
+
+    .. attribute:: code_generator_class
+
+       The class used for code generation.  This should not be changed
+       in most cases, unless you need to modify the Python code a
+       template compiles to.
+
+    .. attribute:: context_class
+
+       The context used for templates.  This should not be changed
+       in most cases, unless you need to modify internals of how
+       template variables are handled.  For details, see
+       :class:`~jinja2.runtime.Context`.
 
     .. automethod:: overlay([options])
 
@@ -165,7 +151,7 @@ useful if you want to dig deeper into Jinja2 or :ref:`develop extensions
         provided as `exc` is raised if something with the generated undefined
         object is done that the undefined object does not allow.  The default
         exception is :exc:`UndefinedError`.  If a `hint` is provided the
-        `name` may be ommited.
+        `name` may be omitted.
 
         The most common way to create an undefined object is by providing
         a name only::
@@ -182,10 +168,10 @@ useful if you want to dig deeper into Jinja2 or :ref:`develop extensions
         For a more complex example you can provide a hint.  For example
         the :func:`first` filter creates an undefined object that way::
 
-            return environment.undefined('no first item, sequence was empty')            
+            return environment.undefined('no first item, sequence was empty')
 
         If it the `name` or `obj` is known (for example because an attribute
-        was accessed) it shold be passed to the undefined object, even if
+        was accessed) it should be passed to the undefined object, even if
         a custom `hint` is provided.  This gives undefined objects the
         possibility to enhance the error message.
 
@@ -194,9 +180,20 @@ useful if you want to dig deeper into Jinja2 or :ref:`develop extensions
 
     .. attribute:: globals
 
-        The dict with the globals of that template.  It's unsafe to modify
-        this dict as it may be shared with other templates or the environment
-        that loaded the template.
+        A dict of variables that are available every time the template
+        is rendered, without needing to pass them during render. This
+        should not be modified, as depending on how the template was
+        loaded it may be shared with the environment and other
+        templates.
+
+        Defaults to :attr:`Environment.globals` unless extra values are
+        passed to :meth:`Environment.get_template`.
+
+        Globals are only intended for data that is common to every
+        render of the template. Specific data should be passed to
+        :meth:`render`.
+
+        See :ref:`global-namespace`.
 
     .. attribute:: name
 
@@ -214,27 +211,69 @@ useful if you want to dig deeper into Jinja2 or :ref:`develop extensions
 
     .. automethod:: stream([context])
 
+    .. automethod:: render_async([context])
+
+    .. automethod:: generate_async([context])
+
 
 .. autoclass:: jinja2.environment.TemplateStream()
     :members: disable_buffering, enable_buffering, dump
 
 
+Autoescaping
+------------
+
+.. versionchanged:: 2.4
+
+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
+autoescaping.  This makes it possible to enable and disable autoescaping
+on a per-template basis (HTML versus text for instance).
+
+.. autofunction:: jinja2.select_autoescape
+
+Here a recommended setup that enables autoescaping for templates ending
+in ``'.html'``, ``'.htm'`` and ``'.xml'`` and disabling it by default
+for all other extensions.  You can use the :func:`~jinja2.select_autoescape`
+function for this::
+
+    from jinja2 import Environment, PackageLoader, select_autoescape
+    env = Environment(autoescape=select_autoescape(['html', 'htm', 'xml']),
+                      loader=PackageLoader('mypackage'))
+
+The :func:`~jinja.select_autoescape` function returns a function that
+works roughly like this::
+
+    def autoescape(template_name):
+        if template_name is None:
+            return False
+        if template_name.endswith(('.html', '.htm', '.xml'))
+
+When implementing a guessing autoescape function, make sure you also
+accept `None` as valid template name.  This will be passed when generating
+templates from strings.  You should always configure autoescaping as
+defaults in the future might change.
+
+Inside the templates the behaviour can be temporarily changed by using
+the `autoescape` block (see :ref:`autoescape-overrides`).
+
+
 .. _identifier-naming:
 
 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 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
 filters and tests by topic.  For example it's perfectly valid to add a
-function into the filter dict and call it `to.unicode`.  The regular
+function into the filter dict and call it `to.str`.  The regular
 expression for filter and test identifiers is
-``[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)*```.
+``[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)*``.
 
 
 Undefined Types
@@ -247,15 +286,15 @@ unable to look up a name or access an attribute one of those objects is
 created and returned.  Some operations on undefined values are then allowed,
 others fail.
 
-The closest to regular Python behavior is the `StrictUndefined` which
+The closest to regular Python behavior is the :class:`StrictUndefined` which
 disallows all operations beside testing if it's an undefined object.
 
 .. autoclass:: jinja2.Undefined()
 
     .. attribute:: _undefined_hint
 
-        Either `None` or an unicode string with the error message for
-        the undefined object.
+        Either `None` or a string with the error message for the
+        undefined object.
 
     .. attribute:: _undefined_obj
 
@@ -278,42 +317,54 @@ disallows all operations beside testing if it's an undefined object.
         :attr:`_undefined_exception` with an error message generated
         from the undefined hints stored on the undefined object.
 
+.. autoclass:: jinja2.ChainableUndefined()
+
 .. autoclass:: jinja2.DebugUndefined()
 
 .. autoclass:: jinja2.StrictUndefined()
 
+There is also a factory function that can decorate undefined objects to
+implement logging on failures:
+
+.. autofunction:: jinja2.make_logging_undefined
+
 Undefined objects are created by calling :attr:`undefined`.
 
 .. admonition:: Implementation
 
-    :class:`Undefined` objects are implemented by overriding the special
-    `__underscore__` methods.  For example the default :class:`Undefined`
-    class implements `__unicode__` in a way that it returns an empty
-    string, however `__int__` and others still fail with an exception.  To
-    allow conversion to int by returning ``0`` you can implement your own::
+    :class:`Undefined` is implemented by overriding the special
+    ``__underscore__`` methods. For example the default
+    :class:`Undefined` class implements ``__str__`` to returns an empty
+    string, while ``__int__`` and others fail with an exception. To
+    allow conversion to int by returning ``0`` you can implement your
+    own subclass.
+
+    .. code-block:: python
 
         class NullUndefined(Undefined):
             def __int__(self):
                 return 0
+
             def __float__(self):
                 return 0.0
 
-    To disallow a method, just override it and raise
-    :attr:`~Undefined._undefined_exception`.  Because this is a very common
-    idom in undefined objects there is the helper method
-    :meth:`~Undefined._fail_with_undefined_error` that does the error raising
-    automatically.  Here a class that works like the regular :class:`Undefined`
-    but chokes on iteration::
+    To disallow a method, override it and raise
+    :attr:`~Undefined._undefined_exception`.  Because this is very
+    common there is the helper method
+    :meth:`~Undefined._fail_with_undefined_error` that raises the error
+    with the correct information. Here's a class that works like the
+    regular :class:`Undefined` but fails on iteration::
 
         class NonIterableUndefined(Undefined):
-            __iter__ = Undefined._fail_with_undefined_error
+            def __iter__(self):
+                self._fail_with_undefined_error()
 
 
 The Context
 -----------
 
 .. autoclass:: jinja2.runtime.Context()
-    :members: resolve, get_exported, get_all
+    :members: get, resolve, resolve_or_missing, get_exported, get_all
 
     .. attribute:: parent
 
@@ -352,19 +403,26 @@ The Context
         blocks registered.  The last item in each list is the current active
         block (latest in the inheritance chain).
 
+    .. attribute:: eval_ctx
+
+        The current :ref:`eval-context`.
+
     .. automethod:: jinja2.runtime.Context.call(callable, \*args, \**kwargs)
 
 
-.. admonition:: Implementation
+The context is immutable, it prevents modifications, and if it is
+modified somehow despite that those changes may not show up. For
+performance, Jinja does not use the context as data storage for, only as
+a primary data source. Variables that the template does not define are
+looked up in the context, but variables the template does define are
+stored locally.
 
-    Context is immutable for the same reason Python's frame locals are
-    immutable inside functions.  Both Jinja2 and Python are not using the
-    context / frame locals as data storage for variables but only as primary
-    data source.
+Instead of modifying the context directly, a function should return
+a value that can be assigned to a variable within the template itself.
 
-    When a template accesses a variable the template does not define, Jinja2
-    looks up the variable in the context, after that the variable is treated
-    as if it was defined in the template.
+.. code-block:: jinja
+
+    {% set comments = get_latest_comments() %}
 
 
 .. _loaders:
@@ -382,7 +440,7 @@ own loader, subclass :class:`BaseLoader` and override `get_source`.
 .. 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
 
@@ -396,6 +454,8 @@ Here a list of the builtin loaders Jinja2 provides:
 
 .. autoclass:: jinja2.ChoiceLoader
 
+.. autoclass:: jinja2.ModuleLoader
+
 
 .. _bytecode-cache:
 
@@ -410,7 +470,7 @@ This is especially useful if you have a web application that is initialized on
 the first request and Jinja compiles many templates at once which slows down
 the application.
 
-To use a bytecode cache, instanciate it and pass it to the :class:`Environment`.
+To use a bytecode cache, instantiate it and pass it to the :class:`Environment`.
 
 .. autoclass:: jinja2.BytecodeCache
     :members: load_bytecode, dump_bytecode, clear
@@ -439,42 +499,108 @@ Builtin bytecode caches:
 .. autoclass:: jinja2.MemcachedBytecodeCache
 
 
+Async Support
+-------------
+
+.. versionadded:: 2.9
+
+Jinja supports the Python ``async`` and ``await`` syntax. For the
+template designer, this support (when enabled) is entirely transparent,
+templates continue to look exactly the same. However, developers should
+be aware of the implementation as it affects what types of APIs you can
+use.
+
+By default, async support is disabled. Enabling it will cause the
+environment to compile different code behind the scenes in order to
+handle async and sync code in an asyncio event loop. This has the
+following implications:
+
+-   The compiled code uses ``await`` for functions and attributes, and
+    uses ``async for`` loops. In order to support using both async and
+    sync functions in this context, a small wrapper is placed around
+    all calls and access, which adds overhead compared to purely async
+    code.
+-   Sync methods and filters become wrappers around their corresponding
+    async implementations where needed. For example, ``render`` invokes
+    ``async_render``, and ``|map`` supports async iterables.
+
+Awaitable objects can be returned from functions in templates and any
+function call in a template will automatically await the result. The
+``await`` you would normally add in Python is implied. For example, you
+can provide a method that asynchronously loads data from a database, and
+from the template designer's point of view it can be called like any
+other function.
+
+
+.. _policies:
+
+Policies
+--------
+
+Starting with Jinja 2.9 policies can be configured on the environment
+which can slightly influence how filters and other template constructs
+behave.  They can be configured with the
+:attr:`~jinja2.Environment.policies` attribute.
+
+Example::
+
+    env.policies['urlize.rel'] = 'nofollow noopener'
+
+``truncate.leeway``:
+    Configures the leeway default for the `truncate` filter.  Leeway as
+    introduced in 2.9 but to restore compatibility with older templates
+    it can be configured to `0` to get the old behavior back.  The default
+    is `5`.
+
+``urlize.rel``:
+    A string that defines the items for the `rel` attribute of generated
+    links with the `urlize` filter.  These items are always added.  The
+    default is `noopener`.
+
+``urlize.target``:
+    The default target that is issued for links from the `urlize` filter
+    if no other target is defined by the call explicitly.
+
+``urlize.extra_schemes``:
+    Recognize URLs that start with these schemes in addition to the
+    default ``http://``, ``https://``, and ``mailto:``.
+
+``json.dumps_function``:
+    If this is set to a value other than `None` then the `tojson` filter
+    will dump with this function instead of the default one.  Note that
+    this function should accept arbitrary extra arguments which might be
+    passed in the future from the filter.  Currently the only argument
+    that might be passed is `indent`.  The default dump function is
+    ``json.dumps``.
+
+``json.dumps_kwargs``:
+    Keyword arguments to be passed to the dump function.  The default is
+    ``{'sort_keys': True}``.
+
+.. _ext-i18n-trimmed:
+
+``ext.i18n.trimmed``:
+    If this is set to `True`, ``{% trans %}`` blocks of the
+    :ref:`i18n-extension` will always unify linebreaks and surrounding
+    whitespace as if the `trimmed` modifier was used.
+
+
 Utilities
 ---------
 
 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
+.. autofunction:: jinja2.pass_context
 
-.. autofunction:: jinja2.contextfilter
+.. autofunction:: jinja2.pass_eval_context
 
-.. autofunction:: jinja2.environmentfunction
-
-.. autofunction:: jinja2.contextfunction
-
-.. function:: escape(s)
-
-    Convert the characters ``&``, ``<``, ``>``, ``'``, and ``"`` in string `s`
-    to HTML-safe sequences.  Use this if you need to display text that might
-    contain such characters in HTML.  This function will not escaped objects
-    that do have an HTML representation such as already escaped data.
-
-    The return value is a :class:`Markup` string.
+.. autofunction:: jinja2.pass_environment
 
 .. autofunction:: jinja2.clear_caches
 
 .. autofunction:: jinja2.is_undefined
 
-.. autoclass:: jinja2.Markup([string])
-    :members: escape, unescape, striptags
-
-.. admonition:: Note
-
-    The Jinja2 :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.
-
 
 Exceptions
 ----------
@@ -485,28 +611,28 @@ Exceptions
 
 .. autoexception:: jinja2.TemplateNotFound
 
+.. autoexception:: jinja2.TemplatesNotFound
+
 .. autoexception:: jinja2.TemplateSyntaxError
 
     .. attribute:: message
 
-        The error message as utf-8 bytestring.
+        The error message.
 
     .. attribute:: lineno
 
-        The line number where the error occurred
+        The line number where the error occurred.
 
     .. attribute:: name
 
-        The load name for the template as unicode string.
+        The load name for the template.
 
     .. attribute:: filename
 
-        The filename that loaded the template as bytestring in the encoding
-        of the file system (most likely utf-8 or mbcs on Windows systems).
+        The filename that loaded the template in the encoding of the
+        file system (most likely utf-8, or mbcs on Windows systems).
 
-    The reason why the filename and error message are bytestrings and not
-    unicode strings is that Python 2.x is not using unicode for exceptions
-    and tracebacks as well as the compiler.  This will change with Python 3.
+.. autoexception:: jinja2.TemplateRuntimeError
 
 .. autoexception:: jinja2.TemplateAssertionError
 
@@ -516,53 +642,65 @@ Exceptions
 Custom Filters
 --------------
 
-Custom filters are just regular Python functions that take the left side of
-the filter as first argument and the the arguments passed to the filter as
-extra arguments or keyword arguments.
+Filters are Python functions that take the value to the left of the
+filter as the first argument and produce a new value. Arguments passed
+to the filter are passed after the value.
 
-For example in the filter ``{{ 42|myfilter(23) }}`` the function would be
-called with ``myfilter(42, 23)``.  Here for example a simple filter that can
-be applied to datetime objects to format them::
+For example, the filter ``{{ 42|myfilter(23) }}`` is called behind the
+scenes as ``myfilter(42, 23)``.
 
-    def datetimeformat(value, format='%H:%M / %d-%m-%Y'):
+Jinja comes with some :ref:`built-in filters <builtin-filters>`. To use
+a custom filter, write a function that takes at least a ``value``
+argument, then register it in :attr:`Environment.filters`.
+
+Here's a filter that formats datetime objects:
+
+.. code-block:: python
+
+    def datetime_format(value, format="%H:%M %d-%m-%y"):
         return value.strftime(format)
 
-You can register it on the template environment by updating the
-:attr:`~Environment.filters` dict on the environment::
+    environment.filters["datetime_format"] = datetime_format
 
-    environment.filters['datetimeformat'] = datetimeformat
-
-Inside the template it can then be used as follows:
+Now it can be used in templates:
 
 .. sourcecode:: jinja
 
-    written on: {{ article.pub_date|datetimeformat }}
-    publication date: {{ article.pub_date|datetimeformat('%d-%m-%Y') }}
+    {{ article.pub_date|datetime_format }}
+    {{ article.pub_date|datetime_format("%B %Y") }}
 
-Filters can also be passed the current template context or environment.  This
-is useful if a filter wants to return an undefined value or check the current
-:attr:`~Environment.autoescape` setting.  For this purpose two decorators
-exist: :func:`environmentfilter` and :func:`contextfilter`.
+Some decorators are available to tell Jinja to pass extra information to
+the filter. The object is passed as the first argument, making the value
+being filtered the second argument.
 
-Here a small example filter that breaks a text into HTML line breaks and
-paragraphs and marks the return value as safe HTML string if autoescaping is
-enabled::
+-   :func:`pass_environment` passes the :class:`Environment`.
+-   :func:`pass_eval_context` passes the :ref:`eval-context`.
+-   :func:`pass_context` passes the current
+    :class:`~jinja2.runtime.Context`.
+
+Here's a filter that converts line breaks into HTML ``<br>`` and ``<p>``
+tags. It uses the eval context to check if autoescape is currently
+enabled before escaping the input and marking the output safe.
+
+.. code-block:: python
 
     import re
-    from jinja2 import environmentfilter, Markup, escape
+    from jinja2 import pass_eval_context
+    from markupsafe import Markup, escape
 
-    _paragraph_re = re.compile(r'(?:\r\n|\r|\n){2,}')
+    @pass_eval_context
+    def nl2br(eval_ctx, value):
+        br = "<br>\n"
 
-    @environmentfilter
-    def nl2br(environment, value):
-        result = u'\n\n'.join(u'<p>%s</p>' % p.replace('\n', '<br>\n')
-                              for p in _paragraph_re.split(escape(value)))
-        if environment.autoescape:
-            result = Markup(result)
-        return result
+        if eval_ctx.autoescape:
+            value = escape(value)
+            br = Markup(br)
 
-Context filters work the same just that the first argument is the current
-active :class:`Context` rather then the environment.
+        result = "\n\n".join(
+            f"<p>{br.join(p.splitlines())}</p>"
+            for p in re.split(r"(?:\r\n|\r(?!\n)|\n){2,}", value)
+        )
+        return Markup(result) if eval_ctx.autoescape else result
 
 
 .. _writing-tests:
@@ -570,52 +708,152 @@ active :class:`Context` rather then the environment.
 Custom Tests
 ------------
 
-Tests work like filters just that there is no way for a test to get access
-to the environment or context and that they can't be chained.  The return
-value of a test should be `True` or `False`.  The purpose of a test is to
-give the template designers the possibility to perform type and conformability
-checks.
+Test are Python functions that take the value to the left of the test as
+the first argument, and return ``True`` or ``False``. Arguments passed
+to the test are passed after the value.
 
-Here a simple test that checks if a variable is a prime number::
+For example, the test ``{{ 42 is even }}`` is called behind the scenes
+as ``is_even(42)``.
+
+Jinja comes with some :ref:`built-in tests <builtin-tests>`. To use a
+custom tests, write a function that takes at least a ``value`` argument,
+then register it in :attr:`Environment.tests`.
+
+Here's a test that checks if a value is a prime number:
+
+.. code-block:: python
 
     import math
 
     def is_prime(n):
         if n == 2:
             return True
-        for i in xrange(2, int(math.ceil(math.sqrt(n))) + 1):
+
+        for i in range(2, int(math.ceil(math.sqrt(n))) + 1):
             if n % i == 0:
                 return False
+
         return True
-        
 
-You can register it on the template environment by updating the
-:attr:`~Environment.tests` dict on the environment::
+    environment.tests["prime"] = is_prime
 
-    environment.tests['prime'] = is_prime
-
-A template designer can then use the test like this:
+Now it can be used in templates:
 
 .. sourcecode:: jinja
 
-    {% if 42 is prime %}
-        42 is a prime number
+    {% if value is prime %}
+        {{ value }} is a prime number
     {% else %}
-        42 is not a prime number
+        {{ value }} is not a prime number
     {% endif %}
 
+Some decorators are available to tell Jinja to pass extra information to
+the test. The object is passed as the first argument, making the value
+being tested the second argument.
+
+-   :func:`pass_environment` passes the :class:`Environment`.
+-   :func:`pass_eval_context` passes the :ref:`eval-context`.
+-   :func:`pass_context` passes the current
+    :class:`~jinja2.runtime.Context`.
+
+
+.. _eval-context:
+
+Evaluation Context
+------------------
+
+The evaluation context (short eval context or eval ctx) makes it
+possible to activate and deactivate compiled features at runtime.
+
+Currently it is only used to enable and disable automatic escaping, but
+it can be used by extensions as well.
+
+The ``autoescape`` setting should be checked on the evaluation context,
+not the environment. The evaluation context will have the computed value
+for the current template.
+
+Instead of ``pass_environment``:
+
+.. code-block:: python
+
+    @pass_environment
+    def filter(env, value):
+        result = do_something(value)
+
+        if env.autoescape:
+            result = Markup(result)
+
+        return result
+
+Use ``pass_eval_context`` if you only need the setting:
+
+.. code-block:: python
+
+    @pass_eval_context
+    def filter(eval_ctx, value):
+        result = do_something(value)
+
+        if eval_ctx.autoescape:
+            result = Markup(result)
+
+        return result
+
+Or use ``pass_context`` if you need other context behavior as well:
+
+.. code-block:: python
+
+    @pass_context
+    def filter(context, value):
+        result = do_something(value)
+
+        if context.eval_ctx.autoescape:
+            result = Markup(result)
+
+        return result
+
+The evaluation context must not be modified at runtime.  Modifications
+must only happen with a :class:`nodes.EvalContextModifier` and
+:class:`nodes.ScopedEvalContextModifier` from an extension, not on the
+eval context object itself.
+
+.. autoclass:: jinja2.nodes.EvalContext
+
+   .. attribute:: autoescape
+
+      `True` or `False` depending on if autoescaping is active or not.
+
+   .. attribute:: volatile
+
+      `True` if the compiler cannot evaluate some expressions at compile
+      time.  At runtime this should always be `False`.
+
 
 .. _global-namespace:
 
 The Global Namespace
 --------------------
 
-Variables stored in the :attr:`Environment.globals` dict are special as they
-are available for imported templates too, even if they are imported without
-context.  This is the place where you can put variables and functions
-that should be available all the time.  Additionally :attr:`Template.globals`
-exist that are variables available to a specific template that are available
-to all :meth:`~Template.render` calls.
+The global namespace stores variables and functions that should be
+available without needing to pass them to :meth:`Template.render`. They
+are also available to templates that are imported or included without
+context. Most applications should only use :attr:`Environment.globals`.
+
+:attr:`Environment.globals` are intended for data that is common to all
+templates loaded by that environment. :attr:`Template.globals` are
+intended for data that is common to all renders of that template, and
+default to :attr:`Environment.globals` unless they're given in
+:meth:`Environment.get_template`, etc. Data that is specific to a
+render should be passed as context to :meth:`Template.render`.
+
+Only one set of globals is used during any specific rendering. If
+templates A and B both have template globals, and B extends A, then
+only B's globals are used for both when using ``b.render()``.
+
+Environment globals should not be changed after loading any templates,
+and template globals should not be changed at any time after loading the
+template. Changing globals after loading a template will result in
+unexpected behavior as they may be shared between the environment and
+other templates.
 
 
 .. _low-level-api:
@@ -642,7 +880,7 @@ don't recommend using any of those.
     that has to be created by :meth:`new_context` of the same template or
     a compatible template.  This render function is generated by the
     compiler from the template code and returns a generator that yields
-    unicode strings.
+    strings.
 
     If an exception in the template code happens the template engine will
     not rewrite the exception but pass through the original one.  As a
@@ -661,9 +899,9 @@ don't recommend using any of those.
 
 .. 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

docs/changelog.rst

@@ -1,3 +0,0 @@
-.. module:: jinja2
-
-.. include:: ../CHANGES

docs/changes.rst

@@ -0,0 +1,4 @@
+Changes
+=======
+
+.. include:: ../CHANGES.rst

docs/conf.py

@@ -1,141 +1,55 @@
-# -*- coding: utf-8 -*-
-#
-# Jinja2 documentation build configuration file, created by
-# sphinx-quickstart on Sun Apr 27 21:42:41 2008.
-#
-# This file is execfile()d with the current directory set to its containing dir.
-#
-# The contents of this file are pickled, so don't put values in the namespace
-# that aren't pickleable (module imports are okay, they're removed automatically).
-#
-# All configuration values have a default value; values that are commented out
-# serve to show the default value.
+from pallets_sphinx_themes import get_version
+from pallets_sphinx_themes import ProjectLink
 
-import sys, os
+# Project --------------------------------------------------------------
 
-# If your extensions are in another directory, add it here. If the directory
-# is relative to the documentation root, use os.path.abspath to make it
-# absolute, like shown here.
-sys.path.append(os.path.dirname(os.path.abspath(__file__)))
+project = "Jinja"
+copyright = "2007 Pallets"
+author = "Pallets"
+release, version = get_version("Jinja2")
 
-# General configuration
-# ---------------------
+# General --------------------------------------------------------------
 
-# Add any Sphinx extension module names here, as strings. They can be extensions
-# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'jinjaext']
-
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
-
-# The suffix of source filenames.
-source_suffix = '.rst'
-
-# The master toctree document.
-master_doc = 'index'
-
-# General substitutions.
-project = 'Jinja2'
-copyright = '2008, Armin Ronacher'
-
-# The default replacements for |version| and |release|, also used in various
-# other places throughout the built documents.
-#
-# The short X.Y version.
-version = '2.0'
-# The full version, including alpha/beta/rc tags.
-release = '2.0'
-
-# There are two options for replacing |today|: either, you set today to some
-# non-false value, then it is used:
-#today = ''
-# Else, today_fmt is used as the format for a strftime call.
-today_fmt = '%B %d, %Y'
-
-# List of documents that shouldn't be included in the build.
-#unused_docs = []
-
-# If true, '()' will be appended to :func: etc. cross-reference text.
-#add_function_parentheses = True
-
-# If true, the current module name will be prepended to all description
-# unit titles (such as .. function::).
-#add_module_names = True
-
-# If true, sectionauthor and moduleauthor directives will be shown in the
-# output. They are ignored by default.
-#show_authors = False
-
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'jinjaext.JinjaStyle'
-
-
-# Options for HTML output
-# -----------------------
-
-# The style sheet to use for HTML and HTML Help pages. A file of that name
-# must exist either in Sphinx' static/ path, or in one of the custom paths
-# given in html_static_path.
-html_style = 'style.css'
-
-# The name for this set of Sphinx documents.  If None, it defaults to
-# "<project> v<release> documentation".
-#html_title = None
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
-
-# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
-# using the given strftime format.
-html_last_updated_fmt = '%b %d, %Y'
-
-# If true, SmartyPants will be used to convert quotes and dashes to
-# typographically correct entities.
-#html_use_smartypants = True
-
-# no modindex
-html_use_modindex = False
-
-# If true, the reST sources are included in the HTML build as _sources/<name>.
-#html_copy_source = True
-
-# If true, an OpenSearch description file will be output, and all pages will
-# contain a <link> tag referring to it.
-#html_use_opensearch = False
-
-# Output file base name for HTML help builder.
-htmlhelp_basename = 'Jinja2doc'
-
-
-# Options for LaTeX output
-# ------------------------
-
-# The paper size ('letter' or 'a4').
-latex_paper_size = 'a4'
-
-# The font size ('10pt', '11pt' or '12pt').
-#latex_font_size = '10pt'
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title, author, document class [howto/manual]).
-latex_documents = [
-  ('index', 'Jinja2.tex', 'Jinja2 Documentation', 'Armin Ronacher', 'manual', 'toctree_only'),
+default_role = "code"
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.extlinks",
+    "sphinx.ext.intersphinx",
+    "sphinxcontrib.log_cabinet",
+    "pallets_sphinx_themes",
 ]
+autodoc_member_order = "bysource"
+autodoc_typehints = "description"
+autodoc_preserve_defaults = True
+extlinks = {
+    "issue": ("https://github.com/pallets/jinja/issues/%s", "#%s"),
+    "pr": ("https://github.com/pallets/jinja/pull/%s", "#%s"),
+    "ghsa": ("https://github.com/pallets/jinja/security/advisories/GHSA-%s", "GHSA-%s"),
+}
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3/", None),
+}
 
-# Additional stuff for the LaTeX preamble.
-latex_preamble = '''
-\usepackage{palatino}
-\definecolor{TitleColor}{rgb}{0.7,0,0}
-\definecolor{InnerLinkColor}{rgb}{0.7,0,0}
-\definecolor{OuterLinkColor}{rgb}{0.8,0,0}
-\definecolor{VerbatimColor}{rgb}{0.985,0.985,0.985}
-\definecolor{VerbatimBorderColor}{rgb}{0.8,0.8,0.8}
-'''
+# HTML -----------------------------------------------------------------
 
-# Documents to append as an appendix to all manuals.
-#latex_appendices = []
-
-# If false, no module index is generated.
-latex_use_modindex = False
+html_theme = "jinja"
+html_theme_options = {"index_sidebar_logo": False}
+html_context = {
+    "project_links": [
+        ProjectLink("Donate", "https://palletsprojects.com/donate"),
+        ProjectLink("PyPI Releases", "https://pypi.org/project/Jinja2/"),
+        ProjectLink("Source Code", "https://github.com/pallets/jinja/"),
+        ProjectLink("Issue Tracker", "https://github.com/pallets/jinja/issues/"),
+        ProjectLink("Chat", "https://discord.gg/pallets"),
+    ]
+}
+html_sidebars = {
+    "index": ["project.html", "localtoc.html", "searchbox.html", "ethicalads.html"],
+    "**": ["localtoc.html", "relations.html", "searchbox.html", "ethicalads.html"],
+}
+singlehtml_sidebars = {"index": ["project.html", "localtoc.html", "ethicalads.html"]}
+html_static_path = ["_static"]
+html_favicon = "_static/jinja-icon.svg"
+html_logo = "_static/jinja-logo.svg"
+html_title = f"Jinja Documentation ({version})"
+html_show_sourcelink = False

docs/examples/cache_extension.py

@@ -4,42 +4,40 @@ from jinja2.ext import Extension
 
 class FragmentCacheExtension(Extension):
     # a set of names that trigger the extension.
-    tags = set(['cache'])
+    tags = {"cache"}
 
     def __init__(self, environment):
-        super(FragmentCacheExtension, self).__init__(environment)
+        super().__init__(environment)
 
         # add the defaults to the environment
-        environment.extend(
-            fragment_cache_prefix='',
-            fragment_cache=None
-        )
+        environment.extend(fragment_cache_prefix="", fragment_cache=None)
 
     def parse(self, parser):
         # the first token is the token that started the tag.  In our case
         # we only listen to ``'cache'`` so this will be a name token with
         # `cache` as value.  We get the line number so that we can give
         # that line number to the nodes we create by hand.
-        lineno = parser.stream.next().lineno
+        lineno = next(parser.stream).lineno
 
         # now we parse a single expression that is used as cache key.
         args = [parser.parse_expression()]
 
         # if there is a comma, the user provided a timeout.  If not use
         # None as second parameter.
-        if parser.stream.skip_if('comma'):
+        if parser.stream.skip_if("comma"):
             args.append(parser.parse_expression())
         else:
             args.append(nodes.Const(None))
 
         # now we parse the body of the cache block up to `endcache` and
         # drop the needle (which would always be `endcache` in that case)
-        body = parser.parse_statements(['name:endcache'], drop_needle=True)
+        body = parser.parse_statements(["name:endcache"], drop_needle=True)
 
         # now return a `CallBlock` node that calls our _cache_support
         # helper method on this extension.
-        return nodes.CallBlock(self.call_method('_cache_support', args),
-                               [], [], body).set_lineno(lineno)
+        return nodes.CallBlock(
+            self.call_method("_cache_support", args), [], [], body
+        ).set_lineno(lineno)
 
     def _cache_support(self, name, timeout, caller):
         """Helper callback."""

docs/examples/inline_gettext_extension.py

@@ -0,0 +1,71 @@
+import re
+
+from jinja2.exceptions import TemplateSyntaxError
+from jinja2.ext import Extension
+from jinja2.lexer import count_newlines
+from jinja2.lexer import Token
+
+_outside_re = re.compile(r"\\?(gettext|_)\(")
+_inside_re = re.compile(r"\\?[()]")
+
+
+class InlineGettext(Extension):
+    """This extension implements support for inline gettext blocks::
+
+        <h1>_(Welcome)</h1>
+        <p>_(This is a paragraph)</p>
+
+    Requires the i18n extension to be loaded and configured.
+    """
+
+    def filter_stream(self, stream):
+        paren_stack = 0
+
+        for token in stream:
+            if token.type != "data":
+                yield token
+                continue
+
+            pos = 0
+            lineno = token.lineno
+
+            while True:
+                if not paren_stack:
+                    match = _outside_re.search(token.value, pos)
+                else:
+                    match = _inside_re.search(token.value, pos)
+                if match is None:
+                    break
+                new_pos = match.start()
+                if new_pos > pos:
+                    preval = token.value[pos:new_pos]
+                    yield Token(lineno, "data", preval)
+                    lineno += count_newlines(preval)
+                gtok = match.group()
+                if gtok[0] == "\\":
+                    yield Token(lineno, "data", gtok[1:])
+                elif not paren_stack:
+                    yield Token(lineno, "block_begin", None)
+                    yield Token(lineno, "name", "trans")
+                    yield Token(lineno, "block_end", None)
+                    paren_stack = 1
+                else:
+                    if gtok == "(" or paren_stack > 1:
+                        yield Token(lineno, "data", gtok)
+                    paren_stack += -1 if gtok == ")" else 1
+                    if not paren_stack:
+                        yield Token(lineno, "block_begin", None)
+                        yield Token(lineno, "name", "endtrans")
+                        yield Token(lineno, "block_end", None)
+                pos = match.end()
+
+            if pos < len(token.value):
+                yield Token(lineno, "data", token.value[pos:])
+
+        if paren_stack:
+            raise TemplateSyntaxError(
+                "unclosed gettext expression",
+                token.lineno,
+                stream.name,
+                stream.filename,
+            )

docs/extensions.rst

@@ -3,59 +3,94 @@
 Extensions
 ==========
 
-Jinja2 supports extensions that can add extra filters, tests, globals or even
-extend the parser.  The main motivation of extensions is it to move often used
+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
-environment is created additional extensions cannot be added.  To add an
+Extensions are added to the Jinja environment at creation time.  To add an
 extension pass a list of extension classes or import paths to the
-`environment` parameter of the :class:`Environment` constructor.  The following
-example creates a Jinja2 environment with the i18n extension loaded::
+``extensions`` parameter of the :class:`~jinja2.Environment` constructor.  The following
+example creates a Jinja environment with the i18n extension loaded::
 
     jinja_env = Environment(extensions=['jinja2.ext.i18n'])
 
+To add extensions after creation time, use the :meth:`~jinja2.Environment.add_extension` method::
+
+    jinja_env.add_extension('jinja2.ext.debug')
+
 
 .. _i18n-extension:
 
 i18n Extension
 --------------
 
-**Import name:** `jinja2.ext.i18n`
+**Import name:** ``jinja2.ext.i18n``
 
-Jinja2 currently comes with one extension, the i18n extension.  It can be
-used in combination with `gettext`_ or `babel`_.  If the i18n extension is
-enabled Jinja2 provides a `trans` statement that marks the wrapped string as
-translatable and calls `gettext`.
+The i18n extension can be used in combination with `gettext`_ or
+`Babel`_.  When it's enabled, Jinja provides a ``trans`` statement that
+marks a block as translatable and calls ``gettext``.
 
-After enabling dummy `_` function that forwards calls to `gettext` is added
-to the environment globals.  An internationalized application then has to
-provide at least an `gettext` and optoinally a `ngettext` function into the
-namespace.  Either globally or for each rendering.
+After enabling, an application has to provide functions for ``gettext``,
+``ngettext``, and optionally ``pgettext`` and ``npgettext``, either
+globally or when rendering. A ``_()`` function is added as an alias to
+the ``gettext`` function.
 
-After enabling of the extension the environment provides the following
+A convenient way to provide these functions is to call one of the below
+methods depending on the translation system in use. If you do not require
+actual translation, use ``Environment.install_null_translations`` to
+install no-op functions.
+
+Environment Methods
+~~~~~~~~~~~~~~~~~~~
+
+After enabling the extension, the environment provides the following
 additional methods:
 
-.. method:: jinja2.Environment.install_gettext_translations(translations)
+.. method:: jinja2.Environment.install_gettext_translations(translations, newstyle=False)
 
-    Installs a translation globally for that environment.  The tranlations
-    object provided must implement at least `ugettext` and `ungettext`.
-    The `gettext.NullTranslations` and `gettext.GNUTranslations` classes
-    as well as `Babel`_\s `Translations` class are supported.
+    Installs a translation globally for the environment. The
+    ``translations`` object must implement ``gettext``, ``ngettext``,
+    and optionally ``pgettext`` and ``npgettext``.
+    :class:`gettext.NullTranslations`, :class:`gettext.GNUTranslations`,
+    and `Babel`_\s ``Translations`` are supported.
 
-.. method:: jinja2.Environment.install_null_translations()
+    .. versionchanged:: 3.0
+        Added ``pgettext`` and ``npgettext``.
 
-    Install dummy gettext functions.  This is useful if you want to prepare
-    the application for internationalization but don't want to implement the
-    full internationalization system yet.
+    .. versionchanged:: 2.5
+        Added new-style gettext support.
+
+.. method:: jinja2.Environment.install_null_translations(newstyle=False)
+
+    Install no-op gettext functions. This is useful if you want to
+    prepare the application for internationalization but don't want to
+    implement the full system yet.
+
+    .. versionchanged:: 2.5 Added new-style gettext support.
+
+.. method:: jinja2.Environment.install_gettext_callables(gettext, ngettext, newstyle=False, pgettext=None, npgettext=None)
+
+    Install the given ``gettext``, ``ngettext``, ``pgettext``, and
+    ``npgettext`` callables into the environment. They should behave
+    exactly like :func:`gettext.gettext`, :func:`gettext.ngettext`,
+    :func:`gettext.pgettext` and :func:`gettext.npgettext`.
+
+    If ``newstyle`` is activated, the callables are wrapped to work like
+    newstyle callables.  See :ref:`newstyle-gettext` for more information.
+
+    .. versionchanged:: 3.0
+        Added ``pgettext`` and ``npgettext``.
+
+    .. versionadded:: 2.5
+        Added new-style gettext support.
 
 .. method:: jinja2.Environment.uninstall_gettext_translations()
 
-    Uninstall the translations again.
+    Uninstall the environment's globally installed translation.
 
 .. method:: jinja2.Environment.extract_translations(source)
 
@@ -64,40 +99,115 @@ additional methods:
     For every string found this function yields a ``(lineno, function,
     message)`` tuple, where:
 
-    * `lineno` is the number of the line on which the string was found,
-    * `function` is the name of the `gettext` function used (if the
-      string was extracted from embedded Python code), and
-    *  `message` is the string itself (a `unicode` object, or a tuple
-       of `unicode` objects for functions with multiple string arguments).
+    -   ``lineno`` is the number of the line on which the string was
+        found.
+    -   ``function`` is the name of the ``gettext`` function used (if
+        the string was extracted from embedded Python code).
+    -   ``message`` is the string itself, or a tuple of strings for
+        functions with multiple arguments.
 
-    If `Babel`_ is installed :ref:`the babel integration <babel-integration>`
-    can be used to extract strings for babel.
+    If `Babel`_ is installed, see :ref:`babel-integration` to extract
+    the strings.
 
-For a web application that is available in multiple languages but gives all
-the users the same language (for example a multilingual forum software
-installed for a French community) may load the translations once and add the
-translation methods to the environment at environment generation time::
+For a web application that is available in multiple languages but gives
+all the users the same language (for example, multilingual forum
+software installed for a French community), the translation may be
+installed when the environment is created.
+
+.. code-block:: python
 
     translations = get_gettext_translations()
-    env = Environment(extensions=['jinja2.ext.i18n'])
+    env = Environment(extensions=["jinja2.ext.i18n"])
     env.install_gettext_translations(translations)
 
-The `get_gettext_translations` function would return the translator for the
-current configuration.  (For example by using `gettext.find`)
+The ``get_gettext_translations`` function would return the translator
+for the current configuration, for example by using ``gettext.find``.
 
-The usage of the `i18n` extension for template designers is covered as part
-:ref:`of the template documentation <i18n-in-templates>`.
+The usage of the ``i18n`` extension for template designers is covered in
+:ref:`the template documentation <i18n-in-templates>`.
 
-.. _gettext: http://docs.python.org/dev/library/gettext
-.. _Babel: http://babel.edgewall.org/
+.. _gettext: https://docs.python.org/3/library/gettext.html
+.. _Babel: https://babel.pocoo.org/
+
+
+Whitespace Trimming
+~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 2.10
+
+Within ``{% trans %}`` blocks, it can be useful to trim line breaks and
+whitespace so that the block of text looks like a simple string with
+single spaces in the translation file.
+
+Linebreaks and surrounding whitespace can be automatically trimmed by
+enabling the ``ext.i18n.trimmed`` :ref:`policy <ext-i18n-trimmed>`.
+
+
+.. _newstyle-gettext:
+
+New Style Gettext
+~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 2.5
+
+New style gettext calls are less to type, less error prone, and support
+autoescaping better.
+
+You can use "new style" gettext calls by setting
+``env.newstyle_gettext = True`` or passing ``newstyle=True`` to
+``env.install_translations``. They are fully supported by the Babel
+extraction tool, but might not work as expected with other extraction
+tools.
+
+With standard ``gettext`` calls, string formatting is a separate step
+done with the ``|format`` filter. This requires duplicating work for
+``ngettext`` calls.
+
+.. sourcecode:: jinja
+
+    {{ gettext("Hello, World!") }}
+    {{ gettext("Hello, %(name)s!")|format(name=name) }}
+    {{ ngettext(
+           "%(num)d apple", "%(num)d apples", apples|count
+       )|format(num=apples|count) }}
+    {{ pgettext("greeting", "Hello, World!") }}
+    {{ npgettext(
+           "fruit", "%(num)d apple", "%(num)d apples", apples|count
+       )|format(num=apples|count) }}
+
+New style ``gettext`` make formatting part of the call, and behind the
+scenes enforce more consistency.
+
+.. sourcecode:: jinja
+
+    {{ gettext("Hello, World!") }}
+    {{ gettext("Hello, %(name)s!", name=name) }}
+    {{ ngettext("%(num)d apple", "%(num)d apples", apples|count) }}
+    {{ pgettext("greeting", "Hello, World!") }}
+    {{ npgettext("fruit", "%(num)d apple", "%(num)d apples", apples|count) }}
+
+The advantages of newstyle gettext are:
+
+-   There's no separate formatting step, you don't have to remember to
+    use the ``|format`` filter.
+-   Only named placeholders are allowed. This solves a common problem
+    translators face because positional placeholders can't switch
+    positions meaningfully. Named placeholders always carry semantic
+    information about what value goes where.
+-   String formatting is used even if no placeholders are used, which
+    makes all strings use a consistent format. Remember to escape any
+    raw percent signs as ``%%``, such as ``100%%``.
+-   The translated string is marked safe, formatting performs escaping
+    as needed. Mark a parameter as ``|safe`` if it has already been
+    escaped.
 
 
 Expression Statement
 --------------------
 
-**Import name:** `jinja2.ext.do`
+**Import name:** ``jinja2.ext.do``
 
-The "do" aka expression-statement extension adds a simple `do` tag to the
+The "do" aka expression-statement extension adds a simple ``do`` tag to the
 template engine that works like a variable expression but ignores the
 return value.
 
@@ -106,12 +216,47 @@ return value.
 Loop Controls
 -------------
 
-**Import name:** `jinja2.ext.loopcontrols`
+**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
+This extension adds support for ``break`` and ``continue`` in loops.  After
+enabling, Jinja provides those two keywords which work exactly like in
 Python.
 
+.. _with-extension:
+
+With Statement
+--------------
+
+**Import name:** ``jinja2.ext.with_``
+
+.. versionchanged:: 2.9
+
+    This extension is now built-in and no longer does anything.
+
+.. _autoescape-extension:
+
+Autoescape Extension
+--------------------
+
+**Import name:** ``jinja2.ext.autoescape``
+
+.. versionchanged:: 2.9
+
+    This extension was removed and is now built-in. Enabling the
+    extension no longer does anything.
+
+
+.. _debug-extension:
+
+Debug Extension
+---------------
+
+**Import name:** ``jinja2.ext.debug``
+
+Adds a ``{% debug %}`` tag to dump the current context as well as the
+available filters and tests. This is useful to see what's available to
+use in the template without setting up a debugger.
+
 
 .. _writing-extensions:
 
@@ -120,31 +265,35 @@ Writing Extensions
 
 .. module:: jinja2.ext
 
-By writing extensions you can add custom tags to Jinja2.  This is a non trival
+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.
+useful. Another one would be fragment caching.
 
 When writing extensions you have to keep in mind that you are working with the
-Jinja2 template compiler which does not validate the node tree you are possing
+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
 how to use them.
 
-Example Extension
-~~~~~~~~~~~~~~~~~
 
-The following example implements a `cache` tag for Jinja2 by using the
-`Werkzeug`_ caching contrib module:
+Example Extensions
+------------------
 
-.. literalinclude:: cache_extension.py
+Cache
+~~~~~
+
+The following example implements a ``cache`` tag for Jinja by using the
+`cachelib`_ library:
+
+.. literalinclude:: examples/cache_extension.py
     :language: python
 
 And here is how you use it in an environment::
 
     from jinja2 import Environment
-    from werkzeug.contrib.cache import SimpleCache
+    from cachelib import SimpleCache
 
     env = Environment(extensions=[FragmentCacheExtension])
     env.fragment_cache = SimpleCache()
@@ -160,10 +309,32 @@ following example caches a sidebar for 300 seconds:
     </div>
     {% endcache %}
 
-.. _Werkzeug: http://werkzeug.pocoo.org/
+.. _cachelib: https://github.com/pallets/cachelib
+
+
+Inline ``gettext``
+~~~~~~~~~~~~~~~~~~
+
+The following example demonstrates using :meth:`Extension.filter_stream`
+to parse calls to the ``_()`` gettext function inline with static data
+without needing Jinja blocks.
+
+.. code-block:: html
+
+        <h1>_(Welcome)</h1>
+        <p>_(This is a paragraph)</p>
+
+It requires the i18n extension to be loaded and configured.
+
+.. literalinclude:: examples/inline_gettext_extension.py
+    :language: python
+
 
 Extension API
-~~~~~~~~~~~~~
+-------------
+
+Extension
+~~~~~~~~~
 
 Extensions always have to extend the :class:`jinja2.ext.Extension` class:
 
@@ -180,8 +351,9 @@ Extensions always have to extend the :class:`jinja2.ext.Extension` class:
         If the extension implements custom tags this is a set of tag names
         the extension is listening for.
 
-Parser API
-~~~~~~~~~~
+
+Parser
+~~~~~~
 
 The parser passed to :meth:`Extension.parse` provides ways to parse
 expressions of different types.  The following methods may be used by
@@ -196,7 +368,7 @@ extensions:
         The filename of the template the parser processes.  This is **not**
         the load name of the template.  For the load name see :attr:`name`.
         For templates that were not loaded form the file system this is
-        `None`.
+        ``None``.
 
     .. attribute:: name
 
@@ -207,7 +379,7 @@ extensions:
         The current :class:`~jinja2.lexer.TokenStream`
 
 .. autoclass:: jinja2.lexer.TokenStream
-   :members: push, look, eos, skip, next, next_if, skip_if, expect
+   :members: push, look, eos, skip, __next__, next_if, skip_if, expect
 
    .. attribute:: current
 
@@ -223,7 +395,7 @@ extensions:
     .. attribute:: type
 
         The type of the token.  This string is interned so you may compare
-        it with arbitrary strings using the `is` operator.
+        it with arbitrary strings using the ``is`` operator.
 
     .. attribute:: value
 
@@ -234,6 +406,7 @@ characters in strings:
 
 .. autofunction:: jinja2.lexer.count_newlines
 
+
 AST
 ~~~
 
@@ -243,12 +416,12 @@ code objects.  Extensions that provide custom statements can return nodes to
 execute custom Python code.
 
 The list below describes all nodes that are currently available.  The AST may
-change between Jinja2 versions but will stay backwards compatible.
+change between Jinja versions but will stay backwards compatible.
 
 For more information have a look at the repr of :meth:`jinja2.Environment.parse`.
 
 .. module:: jinja2.nodes
 
-.. jinjanodes::
+.. jinja:nodes:: jinja2.nodes.Node
 
 .. autoexception:: Impossible

docs/faq.rst

@@ -1,155 +1,77 @@
 Frequently Asked Questions
 ==========================
 
-This page answers some of the often asked questions about Jinja.
-
-.. highlight:: html+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 capital city of Uganda.
+"Jinja" is a Japanese `Shinto shrine`_, or temple, and temple and
+template share a similar English pronunciation. It is not named after
+the `city in Uganda`_.
 
-How fast is it?
----------------
+.. _Shinto shrine: https://en.wikipedia.org/wiki/Shinto_shrine
+.. _city in Uganda: https://en.wikipedia.org/wiki/Jinja%2C_Uganda
 
-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.
 
-.. _Mako: http://www.makotemplates.org/
+How fast is Jinja?
+------------------
 
-How Compatible is Jinja2 with Django?
--------------------------------------
+Jinja is relatively fast among template engines because it compiles and
+caches template code to Python code, so that the template does not need
+to be parsed and interpreted each time. Rendering a template becomes as
+close to executing a Python function as possible.
 
-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.
+Jinja also makes extensive use of caching. Templates are cached by name
+after loading, so future uses of the template avoid loading. The
+template loading itself uses a bytecode cache to avoid repeated
+compiling. The caches can be external to persist across restarts.
+Templates can also be precompiled and loaded as fast Python imports.
 
-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::
+We dislike benchmarks because they don't reflect real use. Performance
+depends on many factors. Different engines have different default
+configurations and tradeoffs that make it unclear how to set up a useful
+comparison. Often, database access, API calls, and data processing have
+a much larger effect on performance than the template engine.
 
-    {% load comments %}
-    {% get_latest_comments 10 as latest_comments %}
-    {% for comment in latest_comments %}
-        ...
-    {% endfor %}
 
-You will most likely provide an object with attributes to retrieve
-comments from the database::
-
-    {% for comment in models.comments.latest(10) %}
-        ...
-    {% endfor %}
-
-Or directly provide the model for quick testing::
-
-    {% for comment in 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?
------------------------------------------------------
+Isn't it a bad idea to put logic in 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.
+possible. With less logic, the template is easier to understand, has
+fewer potential side effects, and is faster to compile and render. But a
+template without any logic means processing must be done in code before
+rendering. A template engine that does that is shipped with Python,
+called :class:`string.Template`, and while it's definitely fast it's not
+convenient.
 
-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.
+Jinja's features such as blocks, statements, filters, and function calls
+make it much easier to write expressive templates, with very few
+restrictions. Jinja doesn't allow arbitrary Python code in templates, or
+every feature available in the Python language. This keeps the engine
+easier to maintain, and keeps templates more readable.
 
-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.
+Some amount of logic is required in templates to keep everyone happy.
+Too much logic in the template can make it complex to reason about and
+maintain. It's up to you to decide how your application will work and
+balance how much logic you want to put in the template.
 
-Why is Autoescaping not the Default?
-------------------------------------
 
-There are multiple reasons why automatic escaping is not the default mode
-and also not the recommended one.  While automatic escaping of variables
-means that you will less likely have an XSS problem it also causes a huge
-amount of extra processing in the template engine which can cause serious
-performance problems.  As Python doesn't provide a way to mark strings as
-unsafe Jinja has to hack around that limitation by providing a custom
-string class (the :class:`Markup` string) that safely interacts with safe
-and unsafe strings.
+Why is HTML escaping not the default?
+-------------------------------------
 
-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.
+Jinja provides a feature that can be enabled to escape HTML syntax in
+rendered templates. However, it is disabled by default.
 
-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.
+Jinja is a general purpose template engine, it is not only used for HTML
+documents. You can generate plain text, LaTeX, emails, CSS, JavaScript,
+configuration files, etc. HTML escaping wouldn't make sense for any of
+these document types.
 
-Why is the Context immutable?
------------------------------
+While automatic escaping means that you are less likely have an XSS
+problem, it also requires significant extra processing during compiling
+and rendering, which can reduce performance. Jinja uses `MarkupSafe`_ for
+escaping, which provides optimized C code for speed, but it still
+introduces overhead to track escaping across methods and formatting.
 
-When writing a :func:`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() %}
-
-I don't have the _speedups Module.  Is Jinja slower now?
---------------------------------------------------------
-
-To achieve a good performance with automatic escaping enabled, the escaping
-function is also implemented in pure C and used if Jinja2 was installed with
-the speedups module.  This happens automatically if a C compiler is available
-on the system during installation.
-
-My tracebacks look weird.  What's happening?
---------------------------------------------
-
-If the speedups 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 speedups extension.
-
-Why is there no Python 2.3 support?
------------------------------------
-
-Python 2.3 is missing a lot of features that are used heavily in Jinja2.  This
-decision was made as with the upcoming Python 2.6 and 3.0 versions it becomes
-harder to maintain the code for older Python versions.  If you really need
-Python 2.3 support you either have to use `Jinja 1`_ or other templating
-engines that still support 2.3.
-
-.. _Jinja 1: http://jinja.pocoo.org/1/
+.. _MarkupSafe: https://markupsafe.palletsprojects.com/

docs/index.rst

@@ -1,27 +1,29 @@
-Jinja2 Documentation
-====================
+.. rst-class:: hide-header
 
-This is the documentation for the Jinja2 general purpose templating language.
-Jinja2 is a library for Python 2.4 and onwards that is designed to be flexible,
-fast and secure.
+Jinja
+=====
+
+.. image:: _static/jinja-name.svg
+    :align: center
+    :height: 200px
+
+Jinja is a fast, expressive, extensible templating engine. Special
+placeholders in the template allow writing code similar to Python
+syntax. Then the template is passed data to render the final document.
 
 .. toctree::
-   :maxdepth: 2
+    :maxdepth: 2
+    :caption: Contents:
 
-   intro
-   api
-   sandbox
-   templates
-   extensions
-   integration
-   switching
-   tricks
-
-   faq
-   changelog
-
-If you can't find the information you're looking for, have a look at the
-index of try to find it using the search function:
-
-* :ref:`genindex`
-* :ref:`search`
+    intro
+    api
+    sandbox
+    nativetypes
+    templates
+    extensions
+    integration
+    switching
+    tricks
+    faq
+    license
+    changes

docs/integration.rst

@@ -1,32 +1,50 @@
 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.
+
+Flask
+-----
+
+The `Flask`_ web application framework, also maintained by Pallets, uses
+Jinja templates by default. Flask sets up a Jinja environment and
+template loader for you, and provides functions to easily render
+templates from view functions.
+
+.. _Flask: https://flask.palletsprojects.com
+
+
+Django
+------
+
+Django supports using Jinja as its template engine, see
+https://docs.djangoproject.com/en/stable/topics/templates/#support-for-template-engines.
+
 
 .. _babel-integration:
 
-Babel Integration
------------------
+Babel
+-----
 
-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 part of the :ref:`i18n-extension` extension.
+Jinja provides support for extracting gettext messages from templates
+via a `Babel`_ extractor entry point called
+``jinja2.ext.babel_extract``. The support is implemented as part of the
+:ref:`i18n-extension` extension.
 
-Gettext messages extracted from both `trans` tags and code expressions.
+Gettext messages are 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`_:
+To extract gettext messages from templates, the project needs a Jinja
+section in its Babel extraction method `mapping file`_:
 
 .. sourcecode:: ini
 
     [jinja2: **/templates/**.html]
     encoding = utf-8
 
-The syntax related options of the :class:`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:
+The syntax related options of the :class:`Environment` are also
+available as configuration values in the mapping file. For example, to
+tell the extractor that templates use ``%`` as
+``line_statement_prefix`` you can use this code:
 
 .. sourcecode:: ini
 
@@ -34,55 +52,43 @@ that templates use ``%`` as `line_statement_prefix` you can use this code:
     encoding = utf-8
     line_statement_prefix = %
 
-:ref:`jinja-extensions` may also be defined by passing a comma separated list
-of import paths as `extensions` value.  The i18n extension is added
-automatically.
+:ref:`jinja-extensions` may also be defined by passing a comma separated
+list of import paths as the ``extensions`` value. The i18n extension is
+added automatically.
+
+Template syntax errors are ignored by default. The assumption is that
+tests will catch syntax errors in templates. If you don't want to ignore
+errors, add ``silent = false`` to the settings.
+
+.. _Babel: https://babel.readthedocs.io/
+.. _mapping file: https://babel.readthedocs.io/en/latest/messages.html#extraction-method-mapping-and-configuration
 
-.. _mapping file: http://babel.edgewall.org/wiki/Documentation/messages.html#extraction-method-mapping-and-configuration
 
 Pylons
 ------
 
-With `Pylons`_ 0.9.7 onwards it's incredible easy to integrate Jinja into a
-Pylons powered application.
+It's easy to integrate Jinja into a `Pylons`_ application.
 
-The template engine is configured in `config/environment.py`.  The configuration
-for Jinja2 looks something like that::
+The template engine is configured in ``config/environment.py``. The
+configuration for Jinja looks something like this:
+
+.. code-block:: python
 
     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.
+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`::
+Additionally it's a good idea to set the Pylons ``c`` object to strict
+mode. By default attribute access on missing attributes on the ``c``
+object returns an empty string and not an undefined object. To change
+this add this to ``config/environment.py``:
+
+.. code-block:: python
 
     config['pylons.strict_c'] = True
 
-.. _Pylons: http://www.pylonshq.com/
-
-TextMate
---------
-
-Inside the `ext` folder of Jinja2 there is a bundle for TextMate that supports
-syntax highlighting for Jinja1 and Jinja2 for text based templates as well as
-HTML.  It also contains a few often used snippets.
-
-Vim
----
-
-A syntax plugin for `Vim`_ exists in the Vim-scripts directory as well as the
-ext folder of Jinja2.  `The script <http://www.vim.org/scripts/script.php?script_id=1856>`_
-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.
-
-.. _Babel: http://babel.edgewall.org/
-.. _Vim: http://www.vim.org/
+.. _Pylons: https://pylonsproject.org/

docs/intro.rst

@@ -1,156 +1,63 @@
 Introduction
 ============
 
-This is the documentation for the Jinja2 general purpose templating language.
-Jinja2 is a library for Python 2.4 and onwards that is designed to be flexible,
-fast and secure.
+Jinja is a fast, expressive, extensible templating engine. Special
+placeholders in the template allow writing code similar to Python
+syntax. Then the template is passed data to render the final document.
 
-If you have any exposure to other text-based template languages, such as Smarty or
-Django, you should feel right at home with Jinja2.  It's both designer and
-developer friendly by sticking to Python's principles and adding functionality
-useful for templating environments.
+It includes:
 
-The key-features are...
+-   Template inheritance and inclusion.
+-   Define and import macros within templates.
+-   HTML templates can use autoescaping to prevent XSS from untrusted
+    user input.
+-   A sandboxed environment can safely render untrusted templates.
+-   Async support for generating templates that automatically handle
+    sync and async functions without extra syntax.
+-   I18N support with Babel.
+-   Templates are compiled to optimized Python code just-in-time and
+    cached, or can be compiled ahead-of-time.
+-   Exceptions point to the correct line in templates to make debugging
+    easier.
+-   Extensible filters, tests, functions, and even syntax.
 
--   ... **configurable syntax**.  If you are generating LaTeX or other formats
-    with Jinja2 you can change the delimiters to something that integrates better
-    into the LaTeX markup.
-
--   ... **fast**.  While performance is not the primarily target of Jinja2 it's
-    surprisingly fast.  The overhead compared to regular Python code was reduced
-    to the very minimum.
-
--   ... **easy to debug**.  Jinja2 integrates directly into the python traceback
-    system which allows you to debug Jinja2 templates with regular python
-    debugging helpers.
-
--   ... **secure**.  It's possible to evaluate untrusted template code if the
-    optional sandbox is enabled.  This allows Jinja2 to be used as templating
-    language for applications where users may modify the template design.
-
-
-Prerequisites
--------------
-
-Jinja2 needs at least **Python 2.4** to run.  Additionally a working C-compiler
-that can create python extensions should be installed for the debugger.  If no
-C-compiler is available and you are using Python 2.4 the `ctypes`_ module
-should be installed.
-
-If you don't have a working C compiler and you are trying to install the source
-release with the speedups you will get a compiler error.  This however can be
-circumvented by passing the ``--without-speedups`` command line argument to the
-setup script::
-
-    $ python setup.py install --with-speedups
-
-(As of Jinja 2.2, the speedups are disabled by default and can be enabled
-with ``--with-speedups``.  See :ref:`enable-speedups`)
-
-.. _ctypes: http://python.net/crew/theller/ctypes/
+Jinja's philosophy is that while application logic belongs in Python if
+possible, it shouldn't make the template designer's job difficult by
+restricting functionality too much.
 
 
 Installation
 ------------
 
-You have multiple ways to install Jinja2.  If you are unsure what to do, go
-with the Python egg or tarball.
+We recommend using the latest version of Python. Jinja supports Python
+3.10 and newer. We also recommend using a `virtual environment`_ in order
+to isolate your project dependencies from other projects and the system.
 
-As a Python egg (via easy_install)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. _virtual environment: https://packaging.python.org/tutorials/installing-packages/#creating-virtual-environments
 
-You can install the most recent Jinja2 version using `easy_install`_ or `pip`_::
+Install the most recent Jinja version using pip:
 
-    easy_install Jinja2
-    pip install Jinja2
+.. code-block:: text
 
-This will install a Jinja2 egg in your Python installation's site-packages
-directory.
-
-(If you are installing from the windows command line omit the `sudo` and make
-sure to run the command as user with administrator rights)
-
-From the tarball release
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-1.  Download the most recent tarball from the `download page`_
-2.  Unpack the tarball
-3.  ``sudo python setup.py install``
-
-Note that the last command will automatically download and install
-`setuptools`_ if you don't already have it installed. This requires a working
-internet connection.
-
-This will install Jinja2 into your Python installation's site-packages directory.
-
-Installing the development version
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-1.  Install `mercurial`_
-2.  ``hg clone http://dev.pocoo.org/hg/jinja2-main jinja2``
-3.  ``cd jinja2``
-4.  ``ln -s jinja2 /usr/lib/python2.X/site-packages``
-
-As an alternative to steps 4 you can also do ``python setup.py develop``
-which will install the package via setuptools in development mode.  This also
-has the advantage that the C extensions are compiled.
-
-Alternative you can use `easy_install`_ to install the current development
-snapshot::
-
-    sudo easy_install Jinja2==dev
-
-Or the new `pip`_ command::
-
-    sudo pip install Jinja2==dev
-
-.. _download page: http://pypi.python.org/pypi/Jinja2
-.. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools
-.. _easy_install: http://peak.telecommunity.com/DevCenter/EasyInstall
-.. _pip: http://pypi.python.org/pypi/pip
-.. _mercurial: http://www.selenic.com/mercurial/
-
-.. _enable-speedups:
-
-Enaable the speedups Module
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-By default Jinja2 will not compile the speedups module.  Enabling this
-will fail if you don't have the Python headers or a working compiler.  This
-is often the case if you are installing Jinja2 from a windows machine.
-
-You can enable the speedups extension when installing using the
-``--with-speedups`` flag::
-
-    sudo python setup.py install --with-speedups
-
-You can also pass this parameter to `pip`::
-
-    $ pip install --install-option='--with-speedups' Jinja2
+    $ pip install Jinja2
 
 
-Basic API Usage
----------------
+Dependencies
+~~~~~~~~~~~~
 
-This section gives you a brief introduction to the Python API for Jinja2
-templates.
+These will be installed automatically when installing Jinja.
 
-The most basic way to create a template and render it is through
-:class:`~jinja2.Template`.  This however is not the recommended way to
-work with it if your templates are not loaded from strings but the file
-system or another data source:
+-   `MarkupSafe`_ escapes untrusted input when rendering templates to
+    avoid injection attacks.
 
->>> from jinja2 import Template
->>> template = Template('Hello {{ name }}!')
->>> template.render(name='John Doe')
-u'Hello John Doe!'
+.. _MarkupSafe: https://markupsafe.palletsprojects.com/
 
-By creating an instance of :class:`~jinja2.Template` you get back a new template
-object that provides a method called :meth:`~jinja2.Template.render` which when
-called with a dict or keyword arguments expands the template.  The dict
-or keywords arguments passed to the template are the so-called "context"
-of the template.
 
-What you can see here is that Jinja2 is using unicode internally and the
-return value is an unicode string.  So make sure that your application is
-indeed using unicode internally.
+Optional Dependencies
+~~~~~~~~~~~~~~~~~~~~~
+
+These distributions will not be installed automatically.
+
+-   `Babel`_ provides translation support in templates.
+
+.. _Babel: https://babel.pocoo.org/

docs/jinjaext.py

@@ -1,192 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-    Jinja Documentation Extensions
-    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-    Support for automatically documenting filters and tests.
-
-    :copyright: Copyright 2008 by Armin Ronacher.
-    :license: BSD.
-"""
-import os
-import re
-import inspect
-import jinja2
-from itertools import islice
-from types import BuiltinFunctionType
-from docutils import nodes
-from docutils.statemachine import ViewList
-from sphinx.ext.autodoc import prepare_docstring
-from sphinx.application import TemplateBridge
-from pygments.style import Style
-from pygments.token import Keyword, Name, Comment, String, Error, \
-     Number, Operator, Generic
-from jinja2 import Environment, FileSystemLoader
-
-
-def parse_rst(state, content_offset, doc):
-    node = nodes.section()
-    # hack around title style bookkeeping
-    surrounding_title_styles = state.memo.title_styles
-    surrounding_section_level = state.memo.section_level
-    state.memo.title_styles = []
-    state.memo.section_level = 0
-    state.nested_parse(doc, content_offset, node, match_titles=1)
-    state.memo.title_styles = surrounding_title_styles
-    state.memo.section_level = surrounding_section_level
-    return node.children
-
-
-class JinjaStyle(Style):
-    title = 'Jinja Style'
-    default_style = ""
-    styles = {
-        Comment:                    'italic #aaaaaa',
-        Comment.Preproc:            'noitalic #B11414',
-        Comment.Special:            'italic #505050',
-
-        Keyword:                    'bold #B80000',
-        Keyword.Type:               '#808080',
-
-        Operator.Word:              'bold #B80000',
-
-        Name.Builtin:               '#333333',
-        Name.Function:              '#333333',
-        Name.Class:                 'bold #333333',
-        Name.Namespace:             'bold #333333',
-        Name.Entity:                'bold #363636',
-        Name.Attribute:             '#686868',
-        Name.Tag:                   'bold #686868',
-        Name.Decorator:             '#686868',
-
-        String:                     '#AA891C',
-        Number:                     '#444444',
-
-        Generic.Heading:            'bold #000080',
-        Generic.Subheading:         'bold #800080',
-        Generic.Deleted:            '#aa0000',
-        Generic.Inserted:           '#00aa00',
-        Generic.Error:              '#aa0000',
-        Generic.Emph:               'italic',
-        Generic.Strong:             'bold',
-        Generic.Prompt:             '#555555',
-        Generic.Output:             '#888888',
-        Generic.Traceback:          '#aa0000',
-
-        Error:                      '#F00 bg:#FAA'
-    }
-
-
-_sig_re = re.compile(r'^[a-zA-Z_][a-zA-Z0-9_]*(\(.*?\))')
-
-
-def format_function(name, aliases, func):
-    lines = inspect.getdoc(func).splitlines()
-    signature = '()'
-    if isinstance(func, BuiltinFunctionType):
-        match = _sig_re.match(lines[0])
-        if match is not None:
-            del lines[:1 + bool(lines and not lines[0])]
-            signature = match.group(1)
-    else:
-        try:
-            argspec = inspect.getargspec(func)
-            if getattr(func, 'environmentfilter', False) or \
-               getattr(func, 'contextfilter', False):
-                del argspec[0][0]
-            signature = inspect.formatargspec(*argspec)
-        except:
-            pass
-    result = ['.. function:: %s%s' % (name, signature), '']
-    result.extend('    ' + line for line in lines)
-    if aliases:
-        result.extend(('', '    :aliases: %s' % ', '.join(
-                      '``%s``' % x for x in sorted(aliases))))
-    return result
-
-
-def dump_functions(mapping):
-    def directive(dirname, arguments, options, content, lineno,
-                      content_offset, block_text, state, state_machine):
-        reverse_mapping = {}
-        for name, func in mapping.iteritems():
-            reverse_mapping.setdefault(func, []).append(name)
-        filters = []
-        for func, names in reverse_mapping.iteritems():
-            aliases = sorted(names, key=lambda x: len(x))
-            name = aliases.pop()
-            filters.append((name, aliases, func))
-        filters.sort()
-
-        result = ViewList()
-        for name, aliases, func in filters:
-            for item in format_function(name, aliases, func):
-                result.append(item, '<jinjaext>')
-
-        node = nodes.paragraph()
-        state.nested_parse(result, content_offset, node)
-        return node.children
-    return directive
-
-
-from jinja2.defaults import DEFAULT_FILTERS, DEFAULT_TESTS
-jinja_filters = dump_functions(DEFAULT_FILTERS)
-jinja_tests = dump_functions(DEFAULT_TESTS)
-
-
-def jinja_nodes(dirname, arguments, options, content, lineno,
-                content_offset, block_text, state, state_machine):
-    from jinja2.nodes import Node
-    doc = ViewList()
-    def walk(node, indent):
-        p = ' ' * indent
-        sig = ', '.join(node.fields)
-        doc.append(p + '.. autoclass:: %s(%s)' % (node.__name__, sig), '')
-        if node.abstract:
-            members = []
-            for key, name in node.__dict__.iteritems():
-                if not key.startswith('_') and \
-                   not hasattr(node.__base__, key) and callable(name):
-                    members.append(key)
-            if members:
-                members.sort()
-                doc.append('%s :members: %s' % (p, ', '.join(members)), '')
-        if node.__base__ != object:
-            doc.append('', '')
-            doc.append('%s :Node type: :class:`%s`' %
-                       (p, node.__base__.__name__), '')
-        doc.append('', '')
-        children = node.__subclasses__()
-        children.sort(key=lambda x: x.__name__.lower())
-        for child in children:
-            walk(child, indent)
-    walk(Node, 0)
-    return parse_rst(state, content_offset, doc)
-
-
-def inject_toc(app, doctree, docname):
-    titleiter = iter(doctree.traverse(nodes.title))
-    try:
-        # skip first title, we are not interested in that one
-        titleiter.next()
-        title = titleiter.next()
-        # and check if there is at least another title
-        titleiter.next()
-    except StopIteration:
-        return
-    tocnode = nodes.section('')
-    tocnode['classes'].append('toc')
-    toctitle = nodes.section('')
-    toctitle['classes'].append('toctitle')
-    toctitle.append(nodes.title(text='Table Of Contents'))
-    tocnode.append(toctitle)
-    tocnode += doctree.document.settings.env.get_toc_for(docname)[0][1]
-    title.parent.insert(title.parent.children.index(title), tocnode)
-
-
-def setup(app):
-    app.add_directive('jinjafilters', jinja_filters, 0, (0, 0, 0))
-    app.add_directive('jinjatests', jinja_tests, 0, (0, 0, 0))
-    app.add_directive('jinjanodes', jinja_nodes, 0, (0, 0, 0))
-    # uncomment for inline toc.  links are broken unfortunately
-    ##app.connect('doctree-resolved', inject_toc)

docs/license.rst

@@ -0,0 +1,5 @@
+BSD-3-Clause License
+====================
+
+.. literalinclude:: ../LICENSE.txt
+    :language: text

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+
+:end
+popd

docs/nativetypes.rst

@@ -0,0 +1,75 @@
+.. module:: jinja2.nativetypes
+
+.. _nativetypes:
+
+Native Python Types
+===================
+
+The default :class:`~jinja2.Environment` renders templates to strings. With
+:class:`NativeEnvironment`, rendering a template produces a native Python type.
+This is useful if you are using Jinja outside the context of creating text
+files. For example, your code may have an intermediate step where users may use
+templates to define values that will then be passed to a traditional string
+environment.
+
+Examples
+--------
+
+Adding two values results in an integer, not a string with a number:
+
+>>> env = NativeEnvironment()
+>>> t = env.from_string('{{ x + y }}')
+>>> result = t.render(x=4, y=2)
+>>> print(result)
+6
+>>> print(type(result))
+int
+
+Rendering list syntax produces a list:
+
+>>> t = env.from_string('[{% for item in data %}{{ item + 1 }},{% endfor %}]')
+>>> result = t.render(data=range(5))
+>>> print(result)
+[1, 2, 3, 4, 5]
+>>> print(type(result))
+list
+
+Rendering something that doesn't look like a Python literal produces a string:
+
+>>> t = env.from_string('{{ x }} * {{ y }}')
+>>> result = t.render(x=4, y=2)
+>>> print(result)
+4 * 2
+>>> print(type(result))
+str
+
+Rendering a Python object produces that object as long as it is the only node:
+
+>>> class Foo:
+...     def __init__(self, value):
+...         self.value = value
+...
+>>> result = env.from_string('{{ x }}').render(x=Foo(15))
+>>> print(type(result).__name__)
+Foo
+>>> print(result.value)
+15
+
+Sandboxed Native Environment
+----------------------------
+
+You can combine :class:`.SandboxedEnvironment` and :class:`NativeEnvironment` to
+get both behaviors.
+
+.. code-block:: python
+
+    class SandboxedNativeEnvironment(SandboxedEnvironment, NativeEnvironment):
+        pass
+
+API
+---
+
+.. autoclass:: NativeEnvironment([options])
+
+.. autoclass:: NativeTemplate([options])
+    :members: render

docs/sandbox.rst

@@ -1,24 +1,66 @@
 Sandbox
 =======
 
-The Jinja2 sandbox can be used to evaluate untrusted code.  Access to unsafe
-attributes and methods is prohibited.
+The Jinja sandbox can be used to render untrusted templates. Access to
+attributes, method calls, operators, mutating data structures, and
+string formatting can be intercepted and prohibited.
 
-Assuming `env` is a :class:`SandboxedEnvironment` in the default configuration
-the following piece of code shows how it works:
+.. code-block:: pycon
 
->>> env.from_string("{{ func.func_code }}").render(func=lambda:None)
-u''
->>> env.from_string("{{ func.func_code.do_something }}").render(func=lambda:None)
-Traceback (most recent call last):
-  ...
-SecurityError: access to attribute 'func_code' of 'function' object is unsafe.
+    >>> from jinja2.sandbox import SandboxedEnvironment
+    >>> env = SandboxedEnvironment()
+    >>> func = lambda: "Hello, Sandbox!"
+    >>> env.from_string("{{ func() }}").render(func=func)
+    'Hello, Sandbox!'
+    >>> env.from_string("{{ func.__code__.co_code }}").render(func=func)
+    Traceback (most recent call last):
+      ...
+    SecurityError: access to attribute '__code__' of 'function' object is unsafe.
 
+A sandboxed environment can be useful, for example, to allow users of an
+internal reporting system to create custom emails. You would document
+what data is available in the templates, then the user would write a
+template using that information. Your code would generate the report
+data and pass it to the user's sandboxed template to render.
+
+
+Security Considerations
+-----------------------
+
+The sandbox alone is not a solution for perfect security. Keep these
+things in mind when using the sandbox.
+
+Templates can still raise errors when compiled or rendered. Your code
+should attempt to catch errors instead of crashing.
+
+It is possible to construct a relatively small template that renders to
+a very large amount of output, which could correspond to a high use of
+CPU or memory. You should run your application with limits on resources
+such as CPU and memory to mitigate this.
+
+Jinja only renders text, it does not understand, for example, JavaScript
+code. Depending on how the rendered template will be used, you may need
+to do other postprocessing to restrict the output.
+
+Pass only the data that is relevant to the template. Avoid passing
+global data, or objects with methods that have side effects. By default
+the sandbox prevents private and internal attribute access. You can
+override :meth:`~SandboxedEnvironment.is_safe_attribute` to further
+restrict attributes access. Decorate methods with :func:`unsafe` to
+prevent calling them from templates when passing objects as data. Use
+:class:`ImmutableSandboxedEnvironment` to prevent modifying lists and
+dictionaries.
+
+
+API
+---
 
 .. module:: jinja2.sandbox
 
 .. autoclass:: SandboxedEnvironment([options])
-    :members: is_safe_attribute, is_safe_callable
+    :members: is_safe_attribute, is_safe_callable, default_binop_table,
+              default_unop_table, intercepted_binops, intercepted_unops,
+              call_binop, call_unop
 
 .. autoclass:: ImmutableSandboxedEnvironment([options])
 
@@ -30,17 +72,40 @@ SecurityError: access to attribute 'func_code' of 'function' object is unsafe.
 
 .. autofunction:: modifies_known_mutable
 
-.. admonition:: Note
 
-    The Jinja2 sandbox alone is no solution for perfect security.  Especially
-    for web applications you have to keep in mind that users may create
-    templates with arbitrary HTML in so it's crucial to ensure that (if you
-    are running multiple users on the same server) they can't harm each other
-    via JavaScript insertions and much more.
+Operator Intercepting
+---------------------
 
-    Also the sandbox is only as good as the configuration.  We stronly
-    recommend only passing non-shared resources to the template and use
-    some sort of whitelisting for attributes.
+For performance, Jinja outputs operators directly when compiling. This
+means it's not possible to intercept operator behavior by overriding
+:meth:`SandboxEnvironment.call <Environment.call>` by default, because
+operator special methods are handled by the Python interpreter, and
+might not correspond with exactly one method depending on the operator's
+use.
 
-    Also keep in mind that templates may raise runtime or compile time errors,
-    so make sure to catch them.
+The sandbox can instruct the compiler to output a function to intercept
+certain operators instead. Override
+:attr:`SandboxedEnvironment.intercepted_binops` and
+:attr:`SandboxedEnvironment.intercepted_unops` with the operator symbols
+you want to intercept. The compiler will replace the symbols with calls
+to :meth:`SandboxedEnvironment.call_binop` and
+:meth:`SandboxedEnvironment.call_unop` instead. The default
+implementation of those methods will use
+:attr:`SandboxedEnvironment.binop_table` and
+:attr:`SandboxedEnvironment.unop_table` to translate operator symbols
+into :mod:`operator` functions.
+
+For example, the power (``**``) operator can be disabled:
+
+.. code-block:: python
+
+    from jinja2.sandbox import SandboxedEnvironment
+
+    class MyEnvironment(SandboxedEnvironment):
+        intercepted_binops = frozenset(["**"])
+
+        def call_binop(self, context, operator, left, right):
+            if operator == "**":
+                return self.undefined("The power (**) operator is unavailable.")
+
+            return super().call_binop(self, context, operator, left, right)

docs/switching.rst

@@ -1,172 +1,73 @@
-Switching from other Template Engines
+Switching From Other Template Engines
 =====================================
 
-.. highlight:: html+jinja
-
-If you have used a different template engine in the past and want to swtich
-to Jinja2 here is a small guide that shows the basic syntatic and semantic
-changes between some common, similar text template engines for Python.
-
-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 :ref:`loader API <loaders>`.
-
-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 :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
-    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 support for babel.  For more details see
-    :ref:`i18n-extension`.
-
-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 :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
-    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
-:ref:`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 :ref:`accessing-the-parent-loop` for more details.
+This is a brief guide on some of the differences between Jinja syntax
+and other template languages. See :doc:`/templates` for a comprehensive
+guide to Jinja syntax and features.
 
 
 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.
+Jinja very familiar. Many of the syntax elements look and work the same.
+However, Jinja provides some more syntax elements, and some work a bit
+differently.
 
-However, Jinja2 provides some more syntax elements covered in the
-documentation and some work a bit different.
+This section covers the template changes. The API, including extension
+support, is fundamentally different so it won't be covered here.
+
+Django supports using Jinja as its template engine, see
+https://docs.djangoproject.com/en/stable/topics/templates/#support-for-template-engines.
 
-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.  With Jinja2 you have to specify that
-you want to call an object.  Thus this Django code::
+In Django, methods are called implicitly, without parentheses.
+
+.. code-block:: django
 
     {% for page in user.get_created_pages %}
         ...
     {% endfor %}
-    
-will look like this in Jinja::
+
+In Jinja, using parentheses is required for calls, like in Python. This
+allows you to pass variables to the method, which is not possible
+in Django. This syntax is also used for calling macros.
+
+.. code-block:: jinja
 
     {% for page in user.get_created_pages() %}
         ...
     {% endfor %}
 
-This allows you to pass variables to the function which is also used for macros
-which is not possible in Django.
-
-Conditions
-~~~~~~~~~~
-
-In Django you can use the following constructs to check for equality::
-
-    {% ifequal foo "bar" %}
-        ...
-    {% else %}
-        ...
-    {% endifequal %}
-
-In Jinja2 you can use the normal if statement in combination with operators::
-
-    {% if foo == 'bar' %}
-        ...
-    {% else %}
-        ...
-    {% endif %}
-
-You can also have multiple elif branches in your template::
-
-    {% if something %}
-        ...
-    {% elif otherthing %}
-        ...
-    {% elif foothing %}
-        ...
-    {% else %}
-        ...
-    {% endif %}
 
 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::
+In Django, one literal value can be passed to a filter after a colon.
+
+.. code-block:: django
 
     {{ items|join:", " }}
 
-looks like this in Jinja2::
+In Jinja, filters can take any number of positional and keyword
+arguments in parentheses, like function calls. Arguments can also be
+variables instead of literal values.
 
-    {{ items|join(', ') }}
+.. code-block:: jinja
+
+    {{ items|join(", ") }}
 
-In fact it's 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::
+In addition to filters, Jinja also has "tests" used with the ``is``
+operator. This operator is not the same as the Python operator.
+
+.. code-block:: jinja
 
     {% if user.user_id is odd %}
         {{ user.username|e }} is odd
@@ -177,49 +78,85 @@ operator.  Here are some examples::
 Loops
 ~~~~~
 
-For loops work very similar to Django, the only incompatibility is that in
-Jinja2 the special variable for the loop context is called `loop` and not
-`forloop` like in Django.
+In Django, the special variable for the loop context is called
+``forloop``, and the ``empty`` is used for no loop items.
+
+.. code-block:: django
+
+    {% for item in items %}
+        {{ forloop.counter }}. {{ item }}
+    {% empty %}
+        No items!
+    {% endfor %}
+
+In Jinja, the special variable for the loop context is called ``loop``,
+and the ``else`` block is used for no loop items.
+
+.. code-block:: jinja
+
+    {% for item in items %}
+        {{ loop.index }}. {{ item }}
+    {% else %}
+        No items!
+    {% endfor %}
+
 
 Cycle
 ~~~~~
 
-The ``{% cycle %}`` tag does not exist in Jinja because of it's implicit
-nature.  However you can achieve mostly the same by using the `cycle`
-method on a loop object.
+In Django, the ``{% cycle %}`` can be used in a for loop to alternate
+between values per loop.
 
-The following Django template::
+.. code-block:: django
 
     {% for user in users %}
         <li class="{% cycle 'odd' 'even' %}">{{ user }}</li>
     {% endfor %}
 
-Would look like this in Jinja::
+In Jinja, the ``loop`` context has a ``cycle`` method.
+
+.. code-block:: jinja
 
     {% for user in users %}
         <li class="{{ loop.cycle('odd', 'even') }}">{{ user }}</li>
     {% endfor %}
 
-There is no equivalent of ``{% cycle ... as variable %}``.
+A cycler can also be assigned to a variable and used outside or across
+loops with the ``cycle()`` global function.
 
 
 Mako
 ----
 
-.. highlight:: html+mako
+You can configure Jinja to look more like Mako:
 
-If you have used Mako so far and want to switch to Jinja2 you can configure
-Jinja2 to look more like Mako:
+.. code-block:: python
 
-.. sourcecode:: python
+    env = Environment(
+        block_start_string="<%",
+        block_end_string="%>",
+        variable_start_string="${",
+        variable_end_string="}",
+        comment_start_string="<%doc>",
+        commend_end_string="</%doc>",
+        line_statement_prefix="%",
+        line_comment_prefix="##",
+    )
 
-    env = Environment('<%', '%>', '${', '}', '%')
+With an environment configured like that, Jinja should be able to
+interpret a small subset of Mako templates without any changes.
 
-Once the environment is configure like that Jinja2 should be able to interpret
-a small subset of Mako templates.  Jinja2 does not support embedded Python code
-so you would have to move that out of the template.  The syntax for defs (in
-Jinja2 defs are called macros) and template inheritance is different too.  The
-following Mako template::
+Jinja does not support embedded Python code, so you would have to move
+that out of the template. You could either process the data with the
+same code before rendering, or add a global function or filter to the
+Jinja environment.
+
+The syntax for defs (which are called macros in Jinja) and template
+inheritance is different too.
+
+The following Mako template:
+
+.. code-block:: mako
 
     <%inherit file="layout.html" />
     <%def name="title()">Page Title</%def>
@@ -229,7 +166,9 @@ following Mako template::
     % endfor
     </ul>
 
-Looks like this in Jinja2 with the above configuration::
+Looks like this in Jinja with the above configuration:
+
+.. code-block:: jinja
 
     <% extends "layout.html" %>
     <% block title %>Page Title<% endblock %>

docs/tricks.rst

@@ -3,30 +3,30 @@ Tips and Tricks
 
 .. 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:
+.. _null-default-fallback:
 
-Null-Master Fallback
---------------------
+Null-Default 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 igored, it can be used
+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 put the `extends` tag into an `if` tag to
+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
+to false, which it does by 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">
+    {% if not standalone %}{% extends 'default.html' %}{% endif -%}
+    <!DOCTYPE html>
     <title>{% block title %}The Page Title{% endblock %}</title>
     <link rel="stylesheet" href="style.css" type="text/css">
     {% block body %}
@@ -46,7 +46,7 @@ list you can use the `cycle` method on the `loop` object::
     {% endfor %}
     </ul>
 
-`cycle` can take an unlimited amount of strings.  Each time this
+`cycle` can take an unlimited number of strings.  Each time this
 tag is encountered the next item from the list is rendered.
 
 
@@ -63,7 +63,7 @@ child template::
     {% set active_page = "index" %}
 
 The layout template can then access `active_page`.  Additionally it makes
-sense to defined a default for that variable::
+sense to define a default for that variable::
 
     {% set navigation_bar = [
         ('/', 'index', 'Index'),
@@ -74,8 +74,8 @@ sense to defined a default for that variable::
     ...
     <ul id="navigation">
     {% for href, id, caption in navigation_bar %}
-      <li{% if id == active_page %} class="active"{% endif
-      %}><a href="{{ href|e }}">{{ caption|e }}</a>/li>
+      <li{% if id == active_page %} class="active"{% endif %}>
+      <a href="{{ href|e }}">{{ caption|e }}</a></li>
     {% endfor %}
     </ul>
     ...
@@ -93,7 +93,7 @@ desired to have access to an outer loop it's possible to alias it::
       <tr>
       {% set rowloop = loop %}
       {% for cell in row %}
-        <td id="cell-{{ rowloop.index }}-{{ loop.index }}>{{ cell }}</td>
+        <td id="cell-{{ rowloop.index }}-{{ loop.index }}">{{ cell }}</td>
       {% endfor %}
       </tr>
     {% endfor %}

examples/basic/cycle.py

@@ -1,13 +1,16 @@
 from jinja2 import Environment
 
-
-env = Environment(line_statement_prefix="#", variable_start_string="${", variable_end_string="}")
-
-
-print env.from_string("""\
+env = Environment(
+    line_statement_prefix="#", variable_start_string="${", variable_end_string="}"
+)
+print(
+    env.from_string(
+        """\
 <ul>
 # for item in range(10)
     <li class="${loop.cycle('odd', 'even')}">${item}</li>
 # endfor
 </ul>\
-""").render()
+"""
+    ).render()
+)

examples/basic/debugger.py

@@ -1,7 +1,6 @@
 from jinja2 import Environment
 from jinja2.loaders import FileSystemLoader
 
-env = Environment(loader=FileSystemLoader('templates'))
-
-tmpl = env.get_template('broken.html')
-print tmpl.render(seq=[3, 2, 4, 5, 3, 2, 0, 2, 1])
+env = Environment(loader=FileSystemLoader("templates"))
+tmpl = env.get_template("broken.html")
+print(tmpl.render(seq=[3, 2, 4, 5, 3, 2, 0, 2, 1]))

examples/basic/inheritance.py

@@ -1,12 +1,13 @@
 from jinja2 import Environment
 from jinja2.loaders import DictLoader
 
-
-env = Environment(loader=DictLoader({
-'a': '''[A[{% block body %}{% endblock %}]]''',
-'b': '''{% extends 'a' %}{% block body %}[B]{% endblock %}''',
-'c': '''{% extends 'b' %}{% block body %}###{{ super() }}###{% endblock %}'''
-}))
-
-
-print env.get_template('c').render()
+env = Environment(
+    loader=DictLoader(
+        {
+            "a": "[A[{% block body %}{% endblock %}]]",
+            "b": "{% extends 'a' %}{% block body %}[B]{% endblock %}",
+            "c": "{% extends 'b' %}{% block body %}###{{ super() }}###{% endblock %}",
+        }
+    )
+)
+print(env.get_template("c").render())

examples/basic/test.py

@@ -1,27 +1,29 @@
 from jinja2 import Environment
 from jinja2.loaders import DictLoader
 
-env = Environment(loader=DictLoader({
-'child.html': u'''\
-{% extends master_layout or 'master.html' %}
-{% include helpers = 'helpers.html' %}
+env = Environment(
+    loader=DictLoader(
+        {
+            "child.html": """\
+{% extends default_layout or 'default.html' %}
+{% import 'helpers.html' as helpers %}
 {% macro get_the_answer() %}42{% endmacro %}
-{% title = 'Hello World' %}
+{% set title = 'Hello World' %}
 {% block body %}
     {{ get_the_answer() }}
     {{ helpers.conspirate() }}
 {% endblock %}
-''',
-'master.html': u'''\
+""",
+            "default.html": """\
 <!doctype html>
 <title>{{ title }}</title>
 {% block body %}{% endblock %}
-''',
-'helpers.html': u'''\
+""",
+            "helpers.html": """\
 {% macro conspirate() %}23{% endmacro %}
-'''
-}))
-
-
+""",
+        }
+    )
+)
 tmpl = env.get_template("child.html")
-print tmpl.render()
+print(tmpl.render())

examples/basic/test_filter_and_linestatements.py

@@ -1,8 +1,10 @@
 from jinja2 import Environment
 
-
-env = Environment(line_statement_prefix='%', variable_start_string="${", variable_end_string="}")
-tmpl = env.from_string("""\
+env = Environment(
+    line_statement_prefix="%", variable_start_string="${", variable_end_string="}"
+)
+tmpl = env.from_string(
+    """\
 % macro foo()
     ${caller(42)}
 % endmacro
@@ -20,6 +22,6 @@ tmpl = env.from_string("""\
       -  ${item}
     % endfor
 % endfilter
-""")
-
-print tmpl.render(seq=range(10))
+"""
+)
+print(tmpl.render(seq=range(10)))

examples/basic/test_loop_filter.py

@@ -1,12 +1,13 @@
 from jinja2 import Environment
 
-tmpl = Environment().from_string("""\
+tmpl = Environment().from_string(
+    """\
 <ul>
 {%- for item in [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] if item % 2 == 0 %}
     <li>{{ loop.index }} / {{ loop.length }}: {{ item }}</li>
 {%- endfor %}
 </ul>
 if condition: {{ 1 if foo else 0 }}
-""")
-
-print tmpl.render(foo=True)
+"""
+)
+print(tmpl.render(foo=True))

examples/basic/translate.py

@@ -1,6 +1,18 @@
 from jinja2 import Environment
 
-print Environment(extensions=['jinja2.i18n.TransExtension']).from_string("""\
+env = Environment(extensions=["jinja2.ext.i18n"])
+env.globals["gettext"] = {"Hello %(user)s!": "Hallo %(user)s!"}.__getitem__
+env.globals["ngettext"] = lambda s, p, n: {
+    "%(count)s user": "%(count)d Benutzer",
+    "%(count)s users": "%(count)d Benutzer",
+}[s if n == 1 else p]
+print(
+    env.from_string(
+        """\
 {% trans %}Hello {{ user }}!{% endtrans %}
-{% trans count=users|count %}{{ count }} user{% pluralize %}{{ count }} users{% endtrans %}
-""").render(user="someone")
+{% trans count=users|count -%}
+{{ count }} user{% pluralize %}{{ count }} users
+{% endtrans %}
+"""
+    ).render(user="someone", users=[1, 2, 3])
+)

examples/bench.py

@@ -1,361 +0,0 @@
-"""\
-    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
-    template.  If a template engine is not installed the test is skipped.\
-"""
-import sys
-import cgi
-from timeit import Timer
-from jinja2 import Environment as JinjaEnvironment
-
-context = {
-    'page_title': 'mitsuhiko\'s benchmark',
-    'table': [dict(a=1,b=2,c=3,d=4,e=5,f=6,g=7,h=8,i=9,j=10) for x in range(1000)]
-}
-
-jinja_template = JinjaEnvironment(
-    line_statement_prefix='%',
-    variable_start_string="${",
-    variable_end_string="}"
-).from_string("""\
-<!doctype html>
-<html>
-  <head>
-    <title>${page_title|e}</title>
-  </head>
-  <body>
-    <div class="header">
-      <h1>${page_title|e}</h1>
-    </div>
-    <ul class="navigation">
-    % for href, caption in [
-        ('index.html', 'Index'),
-        ('downloads.html', 'Downloads'),
-        ('products.html', 'Products')
-      ]
-      <li><a href="${href|e}">${caption|e}</a></li>
-    % endfor
-    </ul>
-    <div class="table">
-      <table>
-      % for row in table
-        <tr>
-        % for cell in row
-          <td>${cell}</td>
-        % endfor
-        </tr>
-      % endfor
-      </table>
-    </div>
-  </body>
-</html>\
-""")
-
-def test_jinja():
-    jinja_template.render(context)
-
-try:
-    from tornado.template import Template
-except ImportError:
-    test_tornado = None
-else:
-    tornado_template = Template("""\
-<!doctype html>
-<html>
-  <head>
-    <title>{{ page_title }}</title>
-  </head>
-  <body>
-    <div class="header">
-      <h1>{{ page_title }}</h1>
-    </div>
-    <ul class="navigation">
-    {% for href, caption in [ \
-        ('index.html', 'Index'), \
-        ('downloads.html', 'Downloads'), \
-        ('products.html', 'Products') \
-      ] %}
-      <li><a href="{{ href }}">{{ caption }}</a></li>
-    {% end %}
-    </ul>
-    <div class="table">
-      <table>
-      {% for row in table %}
-        <tr>
-        {% for cell in row %}
-          <td>{{ cell }}</td>
-        {% end %}
-        </tr>
-      {% end %}
-      </table>
-    </div>
-  </body>
-</html>\
-""")
-
-    def test_tornado():
-        tornado_template.generate(**context)
-
-try:
-    from django.conf import settings
-    settings.configure()
-    from django.template import Template as DjangoTemplate, Context as DjangoContext
-except ImportError:
-    test_django = None
-else:
-    django_template = """\
-<!doctype html>
-<html>
-  <head>
-    <title>{{ page_title }}</title>
-  </head>
-  <body>
-    <div class="header">
-      <h1>{{ page_title }}</h1>
-    </div>
-    <ul class="navigation">
-    {% for href, caption in navigation %}
-      <li><a href="{{ href }}">{{ caption }}</a></li>
-    {% endfor %}
-    </ul>
-    <div class="table">
-      <table>
-      {% for row in table %}
-        <tr>
-        {% for cell in row %}
-          <td>{{ cell }}</td>
-        {% endfor %}
-        </tr>
-      {% endfor %}
-      </table>
-    </div>
-  </body>
-</html>\
-"""
-
-    def test_django():
-        c = DjangoContext(context)
-        c['navigation'] = [('index.html', 'Index'), ('downloads.html', 'Downloads'),
-                           ('products.html', 'Products')]
-        # recompile template each rendering because that's what django
-        # is doing in normal situations too.  Django is not thread safe
-        # so we can't cache it in regular apps either.
-        DjangoTemplate(django_template).render(c)
-
-try:
-    from mako.template import Template as MakoTemplate
-except ImportError:
-    test_mako = None
-else:
-    mako_template = MakoTemplate("""\
-<!doctype html>
-<html>
-  <head>
-    <title>${page_title|h}</title>
-  </head>
-  <body>
-    <div class="header">
-      <h1>${page_title|h}</h1>
-    </div>
-    <ul class="navigation">
-    % for href, caption in [('index.html', 'Index'), ('downloads.html', 'Downloads'), ('products.html', 'Products')]:
-      <li><a href="${href|h}">${caption|h}</a></li>
-    % endfor
-    </ul>
-    <div class="table">
-      <table>
-      % for row in table:
-        <tr>
-        % for cell in row:
-          <td>${cell}</td>
-        % endfor
-        </tr>
-      % endfor
-      </table>
-    </div>
-  </body>
-</html>\
-""")
-
-    def test_mako():
-        mako_template.render(**context)
-
-try:
-    from genshi.template import MarkupTemplate as GenshiTemplate
-except ImportError:
-    test_genshi = None
-else:
-    genshi_template = GenshiTemplate("""\
-<html xmlns="http://www.w3.org/1999/xhtml" xmlns:py="http://genshi.edgewall.org/">
-  <head>
-    <title>${page_title}</title>
-  </head>
-  <body>
-    <div class="header">
-      <h1>${page_title}</h1>
-    </div>
-    <ul class="navigation">
-      <li py:for="href, caption in [
-        ('index.html', 'Index'),
-        ('downloads.html', 'Downloads'),
-        ('products.html', 'Products')]"><a href="${href}">${caption}</a></li>
-    </ul>
-    <div class="table">
-      <table>
-        <tr py:for="row in table">
-          <td py:for="cell in row">${cell}</td>
-        </tr>
-      </table>
-    </div>
-  </body>
-</html>\
-""")
-
-    def test_genshi():
-        genshi_template.generate(**context).render('html', strip_whitespace=False)
-
-try:
-    from Cheetah.Template import Template as CheetahTemplate
-except ImportError:
-    test_cheetah = None
-else:
-    cheetah_template = CheetahTemplate("""\
-#import cgi
-<!doctype html>
-<html>
-  <head>
-    <title>$cgi.escape($page_title)</title>
-  </head>
-  <body>
-    <div class="header">
-      <h1>$cgi.escape($page_title)</h1>
-    </div>
-    <ul class="navigation">
-    #for $href, $caption in [('index.html', 'Index'), ('downloads.html', 'Downloads'), ('products.html', 'Products')]:
-      <li><a href="$cgi.escape($href)">$cgi.escape($caption)</a></li>
-    #end for
-    </ul>
-    <div class="table">
-      <table>
-      #for $row in $table:
-        <tr>
-        #for $cell in $row:
-          <td>$cell</td>
-        #end for
-        </tr>
-      #end for
-      </table>
-    </div>
-  </body>
-</html>\
-""", searchList=[dict(context)])
-
-    def test_cheetah():
-        unicode(cheetah_template)
-
-try:
-    import tenjin
-except ImportError:
-    test_tenjin = None
-else:
-    tenjin_template = tenjin.Template()
-    tenjin_template.convert("""\
-<!doctype html>
-<html>
-  <head>
-    <title>${page_title}</title>
-  </head>
-  <body>
-    <div class="header">
-      <h1>${page_title}</h1>
-    </div>
-    <ul class="navigation">
-<?py for href, caption in [('index.html', 'Index'), ('downloads.html', 'Downloads'), ('products.html', 'Products')]: ?>
-      <li><a href="${href}">${caption}</a></li>
-<?py #end ?>
-    </ul>
-    <div class="table">
-      <table>
-<?py for row in table: ?>
-        <tr>
-<?py     for cell in row: ?>
-          <td>#{cell}</td>
-<?py #end ?>
-        </tr>
-<?py #end ?>
-      </table>
-    </div>
-  </body>
-</html>\
-""")
-
-    def test_tenjin():
-        from tenjin.helpers import escape, to_str
-        tenjin_template.render(context, locals())
-
-try:
-    from spitfire.compiler import util as SpitfireTemplate
-    from spitfire.compiler.analyzer import o2_options as spitfire_optimizer
-except ImportError:
-    test_spitfire = None
-else:
-    spitfire_template = SpitfireTemplate.load_template("""\
-<!doctype html>
-<html>
-  <head>
-    <title>$cgi.escape($page_title)</title>
-  </head>
-  <body>
-    <div class="header">
-      <h1>$cgi.escape($page_title)</h1>
-    </div>
-    <ul class="navigation">
-    #for $href, $caption in [('index.html', 'Index'), ('downloads.html', 'Downloads'), ('products.html', 'Products')]
-      <li><a href="$cgi.escape($href)">$cgi.escape($caption)</a></li>
-    #end for
-    </ul>
-    <div class="table">
-      <table>
-      #for $row in $table
-        <tr>
-        #for $cell in $row
-          <td>$cell</td>
-        #end for
-        </tr>
-      #end for
-      </table>
-    </div>
-  </body>
-</html>\
-""", 'spitfire_tmpl', spitfire_optimizer, {'enable_filters': False})
-    spitfire_context = dict(context, **{'cgi': cgi})
-
-    def test_spitfire():
-        spitfire_template(search_list=[spitfire_context]).main()
-
-sys.stdout.write('\r' + '\n'.join((
-    '=' * 80,
-    'Template Engine BigTable Benchmark'.center(80),
-    '=' * 80,
-    __doc__,
-    '-' * 80
-)) + '\n')
-
-
-for test in 'jinja', 'mako', 'tornado', 'tenjin', 'spitfire', 'django', 'genshi', 'cheetah':
-    if locals()['test_' + test] is None:
-        sys.stdout.write('    %-20s*not installed*\n' % test)
-        continue
-    t = Timer(setup='from __main__ import test_%s as bench' % test,
-              stmt='bench()')
-    sys.stdout.write(' >> %-20s<running>' % test)
-    sys.stdout.flush()
-    sys.stdout.write('\r    %-20s%.4f seconds\n' % (test, t.timeit(number=50) / 50))
-sys.stdout.write('-' * 80 + '\n')
-sys.stdout.write('''\
-    WARNING: The results of this benchmark are useless to compare the
-    performance of template engines and should not be taken seriously in any
-    way.  It's testing the performance of simple loops and has no real-world
-    usefulnes.  It only used to check if changes on the Jinja code affect
-    performance in a good or bad way and how it roughly compares to others.
-''' + '=' * 80 + '\n')

examples/profile.py

@@ -1,49 +0,0 @@
-try:
-    from cProfile import Profile
-except ImportError:
-    from profile import Profile
-from pstats import Stats
-from jinja2 import Environment as JinjaEnvironment
-
-context = {
-    'page_title': 'mitsuhiko\'s benchmark',
-    'table': [dict(a=1,b=2,c=3,d=4,e=5,f=6,g=7,h=8,i=9,j=10) for x in range(1000)]
-}
-
-source = """\
-<!doctype html>
-<html>
-  <head>
-    <title>${page_title|e}</title>
-  </head>
-  <body>
-    <div class="header">
-      <h1>${page_title|e}</h1>
-    </div>
-    <div class="table">
-      <table>
-      % for row in table
-        <tr>
-        % for cell in row
-          <td>${cell}</td>
-        % endfor
-        </tr>
-      % endfor
-      </table>
-    </div>
-  </body>
-</html>\
-"""
-jinja_template = JinjaEnvironment(
-    line_statement_prefix='%',
-    variable_start_string="${",
-    variable_end_string="}"
-).from_string(source)
-print jinja_template.environment.compile(source, raw=True)
-
-
-p = Profile()
-p.runcall(lambda: jinja_template.render(context))
-stats = Stats(p)
-stats.sort_stats('time', 'calls')
-stats.print_stats()

examples/rwbench/django/_form.html

@@ -1 +0,0 @@
-<form action="{{ action }}" method="{{ method }}">{{ body }}</form>

examples/rwbench/django/_input_field.html

@@ -1 +0,0 @@
-<input type="{{ type }}" value="{{ value }}" name="{{ name }}">

examples/rwbench/django/_textarea.html

@@ -1 +0,0 @@
-<textarea name="{{ name }}" rows="{{ rows }}" cols="{{ cols }}">{{ value }}</textarea>

examples/rwbench/django/index.html

@@ -1,29 +0,0 @@
-{% extends "layout.html" %}
-{% block page_title %}Index Page{% endblock %}
-{% block body %}
-  {% for article in articles %}
-  {% if article.published %}
-  <div class="article">
-    <h2><a href="{{ article.href }}">{{ article.title }}</a></h2>
-    <p class="meta">written by <a href="{{ article.user.href }}">{{ article.user.username }}</a> on {{ article.pub_date|dateformat }}</p>
-    <div class="text">{{ article.body|safe }}</div>
-  </div>
-  {% endif %}
-  {% endfor %}
-  {% form %}
-    <dl>
-      <dt>Name</dt>
-      <dd>{% input_field 'name' %}</dd>
-      <dt>E-Mail</dt>
-      <dd>{% input_field 'email' %}</dd>
-      <dt>URL</dt>
-      <dd>{% input_field 'url' %}</dd>
-      <dt>Comment</dt>
-      <dd>{% textarea 'comment' %}</dd>
-      <dt>Captcha</dt>
-      <dd>{% input_field 'captcha' %}</dd>
-    </dl>
-    {% input_field '' 'submit' 'Submit' %}
-    {% input_field 'cancel' 'submit' 'Cancel' %}
-  {% endform %}
-{% endblock %}

examples/rwbench/django/layout.html

@@ -1,29 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
-<html>
-<head>
-  <title>{% block page_title %}{% endblock %} | RealWorld Benchmark</title>
-  <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
-</head>
-<body>
-  <div class="contents">
-    <div class="header">
-      <h1>RealWorld Benchmark</h1>
-      <blockquote><p>
-        A less stupid benchmark for Mako and Jinja2 to get an impression how
-        code changes affect runtime performance.
-      </p></blockquote>
-    </div>
-    <ul class="navigation">
-    {% for href, caption in page_navigation %}
-      <li><a href="{{ href }}">{{ caption }}</a></li>
-    {% endfor %}
-    </ul>
-    <div class="body">
-      {% block body %}{% endblock %}
-    </div>
-    <div class="footer">
-      &copy; Copyright 2008 by I don't know who.
-    </div>
-  </div>
-</body>
-</html>

examples/rwbench/djangoext.py

@@ -1,128 +0,0 @@
-# -*- coding: utf-8 -*-
-from rwbench import ROOT
-from os.path import join
-from django.conf import settings
-settings.configure(TEMPLATE_DIRS=(join(ROOT, 'django'),))
-from django.template import loader as django_loader, Context as DjangoContext, \
-     Node, NodeList, Variable, TokenParser
-from django import template as django_template_module
-from django.template import Library
-
-
-# for django extensions.  We monkey patch our extensions in so that
-# we don't have to initialize a more complex django setup.
-django_extensions = django_template_module.Library()
-django_template_module.builtins.append(django_extensions)
-
-
-from rwbench import dateformat
-django_extensions.filter(dateformat)
-
-
-def var_or_none(x):
-    if x is not None:
-        return Variable(x)
-
-
-# and more django extensions
-@django_extensions.tag
-def input_field(parser, token):
-    p = TokenParser(token.contents)
-    args = [p.value()]
-    while p.more():
-        args.append(p.value())
-    return InputFieldNode(*args)
-
-
-@django_extensions.tag
-def textarea(parser, token):
-    p = TokenParser(token.contents)
-    args = [p.value()]
-    while p.more():
-        args.append(p.value())
-    return TextareaNode(*args)
-
-
-@django_extensions.tag
-def form(parser, token):
-    p = TokenParser(token.contents)
-    args = []
-    while p.more():
-        args.append(p.value())
-    body = parser.parse(('endform',))
-    parser.delete_first_token()
-    return FormNode(body, *args)
-
-
-class InputFieldNode(Node):
-
-    def __init__(self, name, type=None, value=None):
-        self.name = var_or_none(name)
-        self.type = var_or_none(type)
-        self.value = var_or_none(value)
-
-    def render(self, context):
-        name = self.name.resolve(context)
-        type = 'text'
-        value = ''
-        if self.type is not None:
-            type = self.type.resolve(context)
-        if self.value is not None:
-            value = self.value.resolve(context)
-        tmpl = django_loader.get_template('_input_field.html')
-        return tmpl.render(DjangoContext({
-            'name':     name,
-            'type':     type,
-            'value':    value
-        }))
-
-
-class TextareaNode(Node):
-
-    def __init__(self, name, rows=None, cols=None, value=None):
-        self.name = var_or_none(name)
-        self.rows = var_or_none(rows)
-        self.cols = var_or_none(cols)
-        self.value = var_or_none(value)
-
-    def render(self, context):
-        name = self.name.resolve(context)
-        rows = 10
-        cols = 40
-        value = ''
-        if self.rows is not None:
-            rows = int(self.rows.resolve(context))
-        if self.cols is not None:
-            cols = int(self.cols.resolve(context))
-        if self.value is not None:
-            value = self.value.resolve(context)
-        tmpl = django_loader.get_template('_textarea.html')
-        return tmpl.render(DjangoContext({
-            'name':     name,
-            'rows':     rows,
-            'cols':     cols,
-            'value':    value
-        }))
-
-
-class FormNode(Node):
-
-    def __init__(self, body, action=None, method=None):
-        self.body = body
-        self.action = action
-        self.method = method
-
-    def render(self, context):
-        body = self.body.render(context)
-        action = ''
-        method = 'post'
-        if self.action is not None:
-            action = self.action.resolve(context)
-        if self.method is not None:
-            method = self.method.resolve(context)
-        tmpl = django_loader.get_template('_form.html')
-        return tmpl.render(DjangoContext({
-            'body':     body,
-            'action':   action,
-            'method':   method
-        }))

examples/rwbench/genshi/helpers.html

@@ -1,12 +0,0 @@
-<div xmlns="http://www.w3.org/1999/xhtml" xmlns:py="http://genshi.edgewall.org/"
-     py:strip="">
-
-  <py:def function="input_field(name='', value='', type='text')">
-    <input type="$type" value="$value" name="$name" />
-  </py:def>
-
-  <py:def function="textarea(name, value='', rows=10, cols=40)">
-    <textarea name="$name" rows="$rows" cols="cols">$value</textarea>
-  </py:def>
-
-</div>

examples/rwbench/genshi/index.html

@@ -1,41 +0,0 @@
-<?python
-  from rwbench import dateformat
-?>
-<html xmlns="http://www.w3.org/1999/xhtml" xmlns:xi="http://www.w3.org/2001/XInclude"
-      xmlns:py="http://genshi.edgewall.org/">
-  <xi:include href="layout.html" />
-  <xi:include href="helpers.html" />
-  <head><title>Index Page</title></head>
-  <body>
-    <div class="article" py:for="article in articles">
-      <py:if test="article.published">
-        <h2><a href="${article.href}">${article.title}</a></h2>
-        <p class="meta">written by <a href="${article.user.href}"
-          >${article.user.username}</a> on ${dateformat(article.pub_date)}</p>
-        <div class="text">${Markup(article.body)}</div>
-      </py:if>
-    </div>
-    <!--
-      For a fair and balanced comparison we would have to use a def here
-      that wraps the form data but I don't know what would be the best
-      Genshi equivalent for that.  Quite frankly I doubt that this makes
-      sense in Genshi anyways.
-    -->
-    <form action="" method="post">
-      <dl>
-        <dt>Name</dt>
-        <dd>${input_field('name')}</dd>
-        <dt>E-Mail</dt>
-        <dd>${input_field('email')}</dd>
-        <dt>URL</dt>
-        <dd>${input_field('url')}</dd>
-        <dt>Comment</dt>
-        <dd>${textarea('comment')}</dd>
-        <dt>Captcha</dt>
-        <dd>${input_field('captcha')}</dd>
-      </dl>
-      ${input_field(type='submit', value='Submit')}
-      ${input_field(name='cancel', type='submit', value='Cancel')}
-    </form>
-  </body>
-</html>

examples/rwbench/genshi/layout.html

@@ -1,30 +0,0 @@
-<html xmlns="http://www.w3.org/1999/xhtml" xmlns:py="http://genshi.edgewall.org/" >
-  <py:match path="head" once="true">
-    <head>
-      <title>${select('title/text()')} | RealWorld Benchmark</title>
-      <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-    </head>
-  </py:match>
-  <py:match path="body" once="true">
-    <body>
-      <div class="contents">
-        <div class="header">
-          <h1>RealWorld Benchmark</h1>
-          <blockquote><p>
-            A less stupid benchmark for Mako and Jinja2 to get an impression how
-            code changes affect runtime performance.
-          </p></blockquote>
-        </div>
-        <ul class="navigation">
-          <li py:for="href, caption in page_navigation"><a href="$href">$caption</a></li>
-        </ul>
-        <div class="body">
-          ${select('*|text()')}
-        </div>
-        <div class="footer">
-          &copy; Copyright 2008 by I don't know who.
-        </div>
-      </div>
-    </body>
-  </py:match>
-</html>

examples/rwbench/jinja/helpers.html

@@ -1,12 +0,0 @@
-{% macro input_field(name, value='', type='text') -%}
-  <input type="{{ type }}" value="{{ value|e }}" name="{{ name }}">
-{%- endmacro %}
-
-{% macro textarea(name, value='', rows=10, cols=40) -%}
-  <textarea name="{{ name }}" rows="{{ rows }}" cols="{{ cols }}">{{
-    value|e }}</textarea>
-{%- endmacro %}
-
-{% macro form(action='', method='post') -%}
-  <form action="{{ action|e }}" method="{{ method }}">{{ caller() }}</form>
-{%- endmacro %}

examples/rwbench/jinja/index.html

@@ -1,29 +0,0 @@
-{% extends "layout.html" %}
-{% from "helpers.html" import input_field, textarea, form %}
-{% block page_title %}Index Page{% endblock %}
-{% block body %}
-  {%- for article in articles if article.published %}
-  <div class="article">
-    <h2><a href="{{ article.href|e }}">{{ article.title|e }}</a></h2>
-    <p class="meta">written by <a href="{{ article.user.href|e
-      }}">{{ article.user.username|e }}</a> on {{ article.pub_date|dateformat }}</p>
-    <div class="text">{{ article.body }}</div>
-  </div>
-  {%- endfor %}
-  {%- call form() %}
-    <dl>
-      <dt>Name</dt>
-      <dd>{{ input_field('name') }}</dd>
-      <dt>E-Mail</dt>
-      <dd>{{ input_field('email') }}</dd>
-      <dt>URL</dt>
-      <dd>{{ input_field('url') }}</dd>
-      <dt>Comment</dt>
-      <dd>{{ textarea('comment') }}</dd>
-      <dt>Captcha</dt>
-      <dd>{{ input_field('captcha') }}</dd>
-    </dl>
-    {{ input_field(type='submit', value='Submit') }}
-    {{ input_field('cancel', type='submit', value='Cancel') }}
-  {%- endcall %}
-{% endblock %}

examples/rwbench/jinja/layout.html

@@ -1,29 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
-<html>
-<head>
-  <title>{% block page_title %}{% endblock %} | RealWorld Benchmark</title>
-  <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
-</head>
-<body>
-  <div class="contents">
-    <div class="header">
-      <h1>RealWorld Benchmark</h1>
-      <blockquote><p>
-        A less stupid benchmark for Mako and Jinja2 to get an impression how
-        code changes affect runtime performance.
-      </p></blockquote>
-    </div>
-    <ul class="navigation">
-    {%- for href, caption in page_navigation %}
-      <li><a href="{{ href|e }}">{{ caption }}</a></li>
-    {%- endfor %}
-    </ul>
-    <div class="body">
-      {% block body %}{% endblock %}
-    </div>
-    <div class="footer">
-      &copy; Copyright 2008 by I don't know who.
-    </div>
-  </div>
-</body>
-</html>

examples/rwbench/mako/helpers.html

@@ -1,11 +0,0 @@
-<%def name="input_field(name='', value='', type='text')">
-  <input type="${type}" value="${value|h}" name="${name}">
-</%def>
-
-<%def name="textarea(name, value='', rows=10, cols=40)">
-  <textarea name="${name}" rows="${rows}" cols="${cols}">${value|h}</textarea>
-</%def>
-
-<%def name="form(action='', method='post')">
-  <form action="${action|h}" method="${method}">${caller.body()}</form>
-</%def>

examples/rwbench/mako/index.html

@@ -1,31 +0,0 @@
-<%!
-  from rwbench import dateformat
-%>
-<%inherit file="layout.html" />
-<%namespace file="helpers.html" import="input_field, textarea, form" />
-<%def name="page_title()">Index Page</%def>
-% for article in articles:
-  <% if not article.published: continue %>
-<div class="article">
-  <h2><a href="${article.href|h}">${article.title|h}</a></h2>
-  <p class="meta">written by <a href="${article.user.href|h
-    }">${article.user.username|h}</a> on ${dateformat(article.pub_date)}</p>
-  <div class="text">${article.body}</div>
-</div>
-% endfor
-<%call expr="form()">
-  <dl>
-    <dt>Name</dt>
-    <dd>${input_field('name')}</dd>
-    <dt>E-Mail</dt>
-    <dd>${input_field('email')}</dd>
-    <dt>URL</dt>
-    <dd>${input_field('url')}</dd>
-    <dt>Comment</dt>
-    <dd>${textarea('comment')}</dd>
-    <dt>Captcha</dt>
-    <dd>${input_field('captcha')}</dd>
-  </dl>
-  ${input_field(type='submit', value='Submit')}
-  ${input_field(name='cancel', type='submit', value='Cancel')}
-</%call>

examples/rwbench/mako/layout.html

@@ -1,30 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
-<html>
-<head>
-  <title>${self.page_title()} | RealWorld Benchmark</title>
-  <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
-</head>
-<body>
-  <div class="contents">
-    <div class="header">
-      <h1>RealWorld Benchmark</h1>
-      <blockquote><p>
-        A less stupid benchmark for Mako and Jinja2 to get an impression how
-        code changes affect runtime performance.
-      </p></blockquote>
-    </div>
-    <ul class="navigation">
-    % for href, caption in page_navigation:
-      <li><a href="${href|h}">${caption}</a></li>
-    % endfor
-    </ul>
-    <div class="body">
-      ${self.body()}
-    </div>
-    <div class="footer">
-      &copy; Copyright 2008 by I don't know who.
-    </div>
-  </div>
-</body>
-</html>
-<%def name="page_title()"></%def>

examples/rwbench/rwbench.py

@@ -1,99 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-    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).
-    Just go away and ignore it.  NOW!
-
-    :copyright: (c) 2009 by the Jinja Team.
-    :license: BSD.
-"""
-import sys
-from os.path import join, dirname, abspath
-ROOT = abspath(dirname(__file__))
-
-from random import choice, randrange
-from datetime import datetime
-from timeit import Timer
-from jinja2 import Environment, FileSystemLoader
-from jinja2.utils import generate_lorem_ipsum
-from mako.lookup import TemplateLookup
-from genshi.template import TemplateLoader as GenshiTemplateLoader
-
-
-def dateformat(x):
-    return x.strftime('%Y-%m-%d')
-
-
-jinja_env = Environment(loader=FileSystemLoader(join(ROOT, 'jinja')))
-jinja_env.filters['dateformat'] = dateformat
-mako_lookup = TemplateLookup(directories=[join(ROOT, 'mako')])
-genshi_loader = GenshiTemplateLoader([join(ROOT, 'genshi')])
-
-class Article(object):
-
-    def __init__(self, id):
-        self.id = id
-        self.href = '/article/%d' % self.id
-        self.title = generate_lorem_ipsum(1, False, 5, 10)
-        self.user = choice(users)
-        self.body = generate_lorem_ipsum()
-        self.pub_date = datetime.utcfromtimestamp(randrange(10 ** 9, 2 * 10 ** 9))
-        self.published = True
-
-
-class User(object):
-
-    def __init__(self, username):
-        self.href = '/user/%s' % username
-        self.username = username
-
-
-users = map(User, [u'John Doe', u'Jane Doe', u'Peter Somewhat'])
-articles = map(Article, range(20))
-navigation = [
-    ('index',           'Index'),
-    ('about',           'About'),
-    ('foo?bar=1',       'Foo with Bar'),
-    ('foo?bar=2&s=x',   'Foo with X'),
-    ('blah',            'Blub Blah'),
-    ('hehe',            'Haha'),
-] * 5
-
-context = dict(users=users, articles=articles, page_navigation=navigation)
-
-
-jinja_template = jinja_env.get_template('index.html')
-mako_template = mako_lookup.get_template('index.html')
-genshi_template = genshi_loader.load('index.html')
-
-
-def test_jinja():
-    jinja_template.render(context)
-
-def test_mako():
-    mako_template.render_unicode(**context)
-
-
-from djangoext import django_loader, DjangoContext
-def test_django():
-    # not cached because django is not thread safe and does
-    # not cache by itself so it would be unfair to cache it here.
-    django_template = django_loader.get_template('index.html')
-    django_template.render(DjangoContext(context))
-
-
-def test_genshi():
-    genshi_template.generate(**context).render('html', doctype='html')
-
-
-if __name__ == '__main__':
-    sys.stdout.write('Realworldish Benchmark:\n')
-    for test in 'jinja', 'mako', 'django', 'genshi':
-        t = Timer(setup='from __main__ import test_%s as bench' % test,
-                  stmt='bench()')
-        sys.stdout.write(' >> %-20s<running>' % test)
-        sys.stdout.flush()
-        sys.stdout.write('\r    %-20s%.4f seconds\n' % (test, t.timeit(number=200) / 200))

ext/Vim/htmljinja.vim

@@ -1,27 +0,0 @@
-" Vim syntax file
-" Language:	Jinja HTML template
-" Maintainer:	Armin Ronacher <armin.ronacher@active-4.com>
-" Last Change:	2007 Apr 8
-
-" For version 5.x: Clear all syntax items
-" For version 6.x: Quit when a syntax file was already loaded
-if version < 600
-  syntax clear
-elseif exists("b:current_syntax")
-  finish
-endif
-
-if !exists("main_syntax")
-  let main_syntax = 'html'
-endif
-
-if version < 600
-  so <sfile>:p:h/jinja.vim
-  so <sfile>:p:h/html.vim
-else
-  runtime! syntax/jinja.vim
-  runtime! syntax/html.vim
-  unlet b:current_syntax
-endif
-
-let b:current_syntax = "htmljinja"

ext/Vim/jinja.vim

@@ -1,113 +0,0 @@
-" Vim syntax file
-" Language:	Jinja template
-" Maintainer:	Armin Ronacher <armin.ronacher@active-4.com>
-" Last Change:	2008 May 9
-" Version:      1.1
-"
-" Known Bugs:
-"   because of odd limitations dicts and the modulo operator
-"   appear wrong in the template.
-"
-" Changes:
-"
-"     2008 May 9:     Added support for Jinja2 changes (new keyword rules)
-
-" For version 5.x: Clear all syntax items
-" For version 6.x: Quit when a syntax file was already loaded
-if version < 600
-  syntax clear
-elseif exists("b:current_syntax")
-  finish
-endif
-
-syntax case match
-
-" Jinja template built-in tags and parameters (without filter, macro, is and raw, they
-" have special threatment)
-syn keyword jinjaStatement containedin=jinjaVarBlock,jinjaTagBlock,jinjaNested contained and if else in not or recursive as import
-
-syn keyword jinjaStatement containedin=jinjaVarBlock,jinjaTagBlock,jinjaNested contained is filter skipwhite nextgroup=jinjaFilter
-syn keyword jinjaStatement containedin=jinjaTagBlock contained macro skipwhite nextgroup=jinjaFunction
-syn keyword jinjaStatement containedin=jinjaTagBlock contained block skipwhite nextgroup=jinjaBlockName
-
-" Variable Names
-syn match jinjaVariable containedin=jinjaVarBlock,jinjaTagBlock,jinjaNested contained skipwhite /[a-zA-Z_][a-zA-Z0-9_]*/
-syn keyword jinjaSpecial containedin=jinjaVarBlock,jinjaTagBlock,jinjaNested contained false true none False True None loop super caller varargs kwargs
-
-" Filters
-syn match jinjaOperator "|" containedin=jinjaVarBlock,jinjaTagBlock,jinjaNested contained nextgroup=jinjaFilter
-syn match jinjaFilter contained skipwhite /[a-zA-Z_][a-zA-Z0-9_]*/
-syn match jinjaFunction contained skipwhite /[a-zA-Z_][a-zA-Z0-9_]*/
-syn match jinjaBlockName contained skipwhite /[a-zA-Z_][a-zA-Z0-9_]*/
-
-" Jinja template constants
-syn region jinjaString containedin=jinjaVarBlock,jinjaTagBlock,jinjaNested contained start=/"/ skip=/\\"/ end=/"/
-syn region jinjaString containedin=jinjaVarBlock,jinjaTagBlock,jinjaNested contained start=/'/ skip=/\\'/ end=/'/
-syn match jinjaNumber containedin=jinjaVarBlock,jinjaTagBlock,jinjaNested contained /[0-9]\+\(\.[0-9]\+\)\?/
-
-" Operators
-syn match jinjaOperator containedin=jinjaVarBlock,jinjaTagBlock,jinjaNested contained /[+\-*\/<>=!,:]/
-syn match jinjaPunctuation containedin=jinjaVarBlock,jinjaTagBlock,jinjaNested contained /[()\[\]]/
-syn match jinjaOperator containedin=jinjaVarBlock,jinjaTagBlock,jinjaNested contained /\./ nextgroup=jinjaAttribute
-syn match jinjaAttribute contained /[a-zA-Z_][a-zA-Z0-9_]*/
-
-" Jinja template tag and variable blocks
-syn region jinjaNested matchgroup=jinjaOperator start="(" end=")" transparent display containedin=jinjaVarBlock,jinjaTagBlock,jinjaNested contained
-syn region jinjaNested matchgroup=jinjaOperator start="\[" end="\]" transparent display containedin=jinjaVarBlock,jinjaTagBlock,jinjaNested contained
-syn region jinjaNested matchgroup=jinjaOperator start="{" end="}" transparent display containedin=jinjaVarBlock,jinjaTagBlock,jinjaNested contained
-syn region jinjaTagBlock matchgroup=jinjaTagDelim start=/{%-\?/ end=/-\?%}/ skipwhite containedin=ALLBUT,jinjaTagBlock,jinjaVarBlock,jinjaRaw,jinjaString,jinjaNested,jinjaComment
-
-syn region jinjaVarBlock matchgroup=jinjaVarDelim start=/{{-\?/ end=/-\?}}/ containedin=ALLBUT,jinjaTagBlock,jinjaVarBlock,jinjaRaw,jinjaString,jinjaNested,jinjaComment
-
-" Jinja template 'raw' tag
-syn region jinjaRaw matchgroup=jinjaRawDelim start="{%\s*raw\s*%}" end="{%\s*endraw\s*%}" containedin=ALLBUT,jinjaTagBlock,jinjaVarBlock,jinjaString,jinjaComment
-
-" Jinja comments
-syn region jinjaComment matchgroup=jinjaCommentDelim start="{#" end="#}" containedin=ALLBUT,jinjaTagBlock,jinjaVarBlock,jinjaString
-
-" Block start keywords.  A bit tricker.  We only highlight at the start of a
-" tag block and only if the name is not followed by a comma or equals sign
-" which usually means that we have to deal with an assignment.
-syn match jinjaStatement containedin=jinjaTagBlock contained skipwhite /\({%-\?\s*\)\@<=\<[a-zA-Z_][a-zA-Z0-9_]*\>\(\s*[,=]\)\@!/
-
-" and context modifiers
-syn match jinjaStatement containedin=jinjaTagBlock contained /\<with\(out\)\?\s\+context\>/ skipwhite
-
-
-" Define the default highlighting.
-" For version 5.7 and earlier: only when not done already
-" For version 5.8 and later: only when an item doesn't have highlighting yet
-if version >= 508 || !exists("did_jinja_syn_inits")
-  if version < 508
-    let did_jinja_syn_inits = 1
-    command -nargs=+ HiLink hi link <args>
-  else
-    command -nargs=+ HiLink hi def link <args>
-  endif
-
-  HiLink jinjaPunctuation jinjaOperator
-  HiLink jinjaAttribute jinjaVariable
-  HiLink jinjaFunction jinjaFilter
-
-  HiLink jinjaTagDelim jinjaTagBlock
-  HiLink jinjaVarDelim jinjaVarBlock
-  HiLink jinjaCommentDelim jinjaComment
-  HiLink jinjaRawDelim jinja
-
-  HiLink jinjaSpecial Special
-  HiLink jinjaOperator Normal
-  HiLink jinjaRaw Normal
-  HiLink jinjaTagBlock PreProc
-  HiLink jinjaVarBlock PreProc
-  HiLink jinjaStatement Statement
-  HiLink jinjaFilter Function
-  HiLink jinjaBlockName Function
-  HiLink jinjaVariable Identifier
-  HiLink jinjaString Constant
-  HiLink jinjaNumber Constant
-  HiLink jinjaComment Comment
-
-  delcommand HiLink
-endif
-
-let b:current_syntax = "jinja"

ext/django2jinja/django2jinja.py

@@ -1,768 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-    Django to Jinja
-    ~~~~~~~~~~~~~~~
-
-    Helper module that can convert django templates into Jinja2 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
-    writer, add extra conversion logic for your custom template tags,
-    configure your django environment and run the `convert_templates`
-    function.
-
-    Here a simple example::
-
-        # configure django (or use settings.configure)
-        import os
-        os.environ['DJANGO_SETTINGS_MODULE'] = 'yourapplication.settings'
-        from yourapplication.foo.templatetags.bar import MyNode
-
-        from django2jinja import Writer, convert_templates
-
-        def write_my_node(writer, node):
-            writer.start_variable()
-            writer.write('myfunc(')
-            for idx, arg in enumerate(node.args):
-                if idx:
-                    writer.write(', ')
-                writer.node(arg)
-            writer.write(')')
-            writer.end_variable()
-
-        writer = Writer()
-        writer.node_handlers[MyNode] = write_my_node
-        convert_templates('/path/to/output/folder', writer=writer)
-    
-    Here is an example hos to automatically translate your django
-    variables to jinja2::
-        
-        import re
-        # List of tuple (Match pattern, Replace pattern, Exclusion pattern)
-        
-        var_re  = ((re.compile(r"(u|user)\.is_authenticated"), r"\1.is_authenticated()", None),
-                  (re.compile(r"\.non_field_errors"), r".non_field_errors()", None),
-                  (re.compile(r"\.label_tag"), r".label_tag()", None),
-                  (re.compile(r"\.as_dl"), r".as_dl()", None),
-                  (re.compile(r"\.as_table"), r".as_table()", None),
-                  (re.compile(r"\.as_widget"), r".as_widget()", None),
-                  (re.compile(r"\.as_hidden"), r".as_hidden()", None),
-                  
-                  (re.compile(r"\.get_([0-9_\w]+)_url"), r".get_\1_url()", None),
-                  (re.compile(r"\.url"), r".url()", re.compile(r"(form|calendar).url")),
-                  (re.compile(r"\.get_([0-9_\w]+)_display"), r".get_\1_display()", None),
-                  (re.compile(r"loop\.counter"), r"loop.index", None),
-                  (re.compile(r"loop\.revcounter"), r"loop.revindex", None),
-                  (re.compile(r"request\.GET\.([0-9_\w]+)"), r"request.GET.get('\1', '')", None),
-                  (re.compile(r"request\.get_host"), r"request.get_host()", None),
-                  
-                  (re.compile(r"\.all(?!_)"), r".all()", None),
-                  (re.compile(r"\.all\.0"), r".all()[0]", None),
-                  (re.compile(r"\.([0-9])($|\s+)"), r"[\1]\2", None),
-                  (re.compile(r"\.items"), r".items()", None),
-        )
-        writer = Writer(var_re=var_re)
-        
-    For details about the writing process have a look at the module code.
-
-    :copyright: (c) 2009 by the Jinja Team.
-    :license: BSD.
-"""
-import re
-import os
-import sys
-from jinja2.defaults import *
-from django.conf import settings
-from django.template import defaulttags as core_tags, loader, TextNode, \
-     FilterExpression, libraries, Variable, loader_tags, TOKEN_TEXT, \
-     TOKEN_VAR
-from django.template.debug import DebugVariableNode as VariableNode
-from django.templatetags import i18n as i18n_tags
-from StringIO import StringIO
-
-
-_node_handlers = {}
-_resolved_filters = {}
-_newline_re = re.compile(r'(?:\r\n|\r|\n)')
-
-
-# Django stores an itertools object on the cycle node.  Not only is this
-# thread unsafe but also a problem for the converter which needs the raw
-# string values passed to the constructor to create a jinja loop.cycle()
-# call from it.
-_old_cycle_init = core_tags.CycleNode.__init__
-def _fixed_cycle_init(self, cyclevars, variable_name=None):
-    self.raw_cycle_vars = map(Variable, cyclevars)
-    _old_cycle_init(self, cyclevars, variable_name)
-core_tags.CycleNode.__init__ = _fixed_cycle_init
-
-
-def node(cls):
-    def proxy(f):
-        _node_handlers[cls] = f
-        return f
-    return proxy
-
-
-def convert_templates(output_dir, extensions=('.html', '.txt'), writer=None,
-                      callback=None):
-    """Iterates over all templates in the template dirs configured and
-    translates them and writes the new templates into the output directory.
-    """
-    if writer is None:
-        writer = Writer()
-
-    def filter_templates(files):
-        for filename in files:
-            ifilename = filename.lower()
-            for extension in extensions:
-                if ifilename.endswith(extension):
-                    yield filename
-
-    def translate(f, loadname):
-        template = loader.get_template(loadname)
-        original = writer.stream
-        writer.stream = f
-        writer.body(template.nodelist)
-        writer.stream = original
-
-    if callback is None:
-        def callback(template):
-            print template
-
-    for directory in settings.TEMPLATE_DIRS:
-        for dirname, _, files in os.walk(directory):
-            dirname = dirname[len(directory) + 1:]
-            for filename in filter_templates(files):
-                source = os.path.normpath(os.path.join(dirname, filename))
-                target = os.path.join(output_dir, dirname, filename)
-                basetarget = os.path.dirname(target)
-                if not os.path.exists(basetarget):
-                    os.makedirs(basetarget)
-                callback(source)
-                f = file(target, 'w')
-                try:
-                    translate(f, source)
-                finally:
-                    f.close()
-
-
-class Writer(object):
-    """The core writer class."""
-
-    def __init__(self, stream=None, error_stream=None,
-                 block_start_string=BLOCK_START_STRING,
-                 block_end_string=BLOCK_END_STRING,
-                 variable_start_string=VARIABLE_START_STRING,
-                 variable_end_string=VARIABLE_END_STRING,
-                 comment_start_string=COMMENT_START_STRING,
-                 comment_end_string=COMMENT_END_STRING,
-                 initial_autoescape=True,
-                 use_jinja_autoescape=False,
-                 custom_node_handlers=None,
-                 var_re=[],
-                 env=None):
-        if stream is None:
-            stream = sys.stdout
-        if error_stream is None:
-            error_stream = sys.stderr
-        self.stream = stream
-        self.error_stream = error_stream
-        self.block_start_string = block_start_string
-        self.block_end_string = block_end_string
-        self.variable_start_string = variable_start_string
-        self.variable_end_string = variable_end_string
-        self.comment_start_string = comment_start_string
-        self.comment_end_string = comment_end_string
-        self.autoescape = initial_autoescape
-        self.spaceless = False
-        self.use_jinja_autoescape = use_jinja_autoescape
-        self.node_handlers = dict(_node_handlers,
-                                  **(custom_node_handlers or {}))
-        self._loop_depth = 0
-        self._filters_warned = set()
-        self.var_re = var_re
-        self.env = env
-
-    def enter_loop(self):
-        """Increments the loop depth so that write functions know if they
-        are in a loop.
-        """
-        self._loop_depth += 1
-
-    def leave_loop(self):
-        """Reverse of enter_loop."""
-        self._loop_depth -= 1
-
-    @property
-    def in_loop(self):
-        """True if we are in a loop."""
-        return self._loop_depth > 0
-
-    def write(self, s):
-        """Writes stuff to the stream."""
-        self.stream.write(s.encode(settings.FILE_CHARSET))
-
-    def print_expr(self, expr):
-        """Open a variable tag, write to the string to the stream and close."""
-        self.start_variable()
-        self.write(expr)
-        self.end_variable()
-
-    def _post_open(self):
-        if self.spaceless:
-            self.write('- ')
-        else:
-            self.write(' ')
-
-    def _pre_close(self):
-        if self.spaceless:
-            self.write(' -')
-        else:
-            self.write(' ')
-
-    def start_variable(self):
-        """Start a variable."""
-        self.write(self.variable_start_string)
-        self._post_open()
-
-    def end_variable(self, always_safe=False):
-        """End a variable."""
-        if not always_safe and self.autoescape and \
-           not self.use_jinja_autoescape:
-            self.write('|e')
-        self._pre_close()
-        self.write(self.variable_end_string)
-
-    def start_block(self):
-        """Starts a block."""
-        self.write(self.block_start_string)
-        self._post_open()
-
-    def end_block(self):
-        """Ends a block."""
-        self._pre_close()
-        self.write(self.block_end_string)
-
-    def tag(self, name):
-        """Like `print_expr` just for blocks."""
-        self.start_block()
-        self.write(name)
-        self.end_block()
-
-    def variable(self, name):
-        """Prints a variable.  This performs variable name transformation."""
-        self.write(self.translate_variable_name(name))
-
-    def literal(self, value):
-        """Writes a value as literal."""
-        value = repr(value)
-        if value[:2] in ('u"', "u'"):
-            value = value[1:]
-        self.write(value)
-
-    def filters(self, filters, is_block=False):
-        """Dumps a list of filters."""
-        want_pipe = not is_block
-        for filter, args in filters:
-            name = self.get_filter_name(filter)
-            if name is None:
-                self.warn('Could not find filter %s' % name)
-                continue
-            if name not in DEFAULT_FILTERS and \
-               name not in self._filters_warned:
-                self._filters_warned.add(name)
-                self.warn('Filter %s probably doesn\'t exist in Jinja' %
-                            name)
-            if not want_pipe:
-                want_pipe = True
-            else:
-                self.write('|')
-            self.write(name)
-            if args:
-                self.write('(')
-                for idx, (is_var, value) in enumerate(args):
-                    if idx:
-                        self.write(', ')
-                    if is_var:
-                        self.node(value)
-                    else:
-                        self.literal(value)
-                self.write(')')
-
-    def get_location(self, origin, position):
-        """Returns the location for an origin and position tuple as name
-        and lineno.
-        """
-        if hasattr(origin, 'source'):
-            source = origin.source
-            name = '<unknown source>'
-        else:
-            source = origin.loader(origin.loadname, origin.dirs)[0]
-            name = origin.loadname
-        lineno = len(_newline_re.findall(source[:position[0]])) + 1
-        return name, lineno
-
-    def warn(self, message, node=None):
-        """Prints a warning to the error stream."""
-        if node is not None and hasattr(node, 'source'):
-            filename, lineno = self.get_location(*node.source)
-            message = '[%s:%d] %s' % (filename, lineno, message)
-        print >> self.error_stream, message
-
-    def translate_variable_name(self, var):
-        """Performs variable name translation."""
-        if self.in_loop and var == 'forloop' or var.startswith('forloop.'):
-            var = var[3:]
-        
-        for reg, rep, unless in self.var_re:
-            no_unless = unless and unless.search(var) or True
-            if reg.search(var) and no_unless:
-                var = reg.sub(rep, var)
-                break
-        return var
-
-    def get_filter_name(self, filter):
-        """Returns the filter name for a filter function or `None` if there
-        is no such filter.
-        """
-        if filter not in _resolved_filters:
-            for library in libraries.values():
-                for key, value in library.filters.iteritems():
-                    _resolved_filters[value] = key
-        return _resolved_filters.get(filter, None)
-
-    def node(self, node):
-        """Invokes the node handler for a node."""
-        for cls, handler in self.node_handlers.iteritems():
-            if type(node) is cls or type(node).__name__ == cls:
-                handler(self, node)
-                break
-        else:
-            self.warn('Untranslatable node %s.%s found' % (
-                node.__module__,
-                node.__class__.__name__
-            ), node)
-
-    def body(self, nodes):
-        """Calls node() for every node in the iterable passed."""
-        for node in nodes:
-            self.node(node)
-
-
-@node(TextNode)
-def text_node(writer, node):
-    writer.write(node.s)
-
-
-@node(Variable)
-def variable(writer, node):
-    if node.translate:
-        writer.warn('i18n system used, make sure to install translations', node)
-        writer.write('_(')
-    if node.literal is not None:
-        writer.literal(node.literal)
-    else:
-        writer.variable(node.var)
-    if node.translate:
-        writer.write(')')
-
-
-@node(VariableNode)
-def variable_node(writer, node):
-    writer.start_variable()
-    if node.filter_expression.var.var == 'block.super' \
-       and not node.filter_expression.filters:
-        writer.write('super()')
-    else:
-        writer.node(node.filter_expression)
-    writer.end_variable()
-
-
-@node(FilterExpression)
-def filter_expression(writer, node):
-    writer.node(node.var)
-    writer.filters(node.filters)
-
-
-@node(core_tags.CommentNode)
-def comment_tag(writer, node):
-    pass
-
-
-@node(core_tags.DebugNode)
-def comment_tag(writer, node):
-    writer.warn('Debug tag detected.  Make sure to add a global function '
-                'called debug to the namespace.', node=node)
-    writer.print_expr('debug()')
-
-
-@node(core_tags.ForNode)
-def for_loop(writer, node):
-    writer.start_block()
-    writer.write('for ')
-    for idx, var in enumerate(node.loopvars):
-        if idx:
-            writer.write(', ')
-        writer.variable(var)
-    writer.write(' in ')
-    if node.is_reversed:
-        writer.write('(')
-    writer.node(node.sequence)
-    if node.is_reversed:
-        writer.write(')|reverse')
-    writer.end_block()
-    writer.enter_loop()
-    writer.body(node.nodelist_loop)
-    writer.leave_loop()
-    writer.tag('endfor')
-
-
-@node(core_tags.IfNode)
-def if_condition(writer, node):
-    writer.start_block()
-    writer.write('if ')
-    join_with = 'and'
-    if node.link_type == core_tags.IfNode.LinkTypes.or_:
-        join_with = 'or'
-    
-    for idx, (ifnot, expr) in enumerate(node.bool_exprs):
-        if idx:
-            writer.write(' %s ' % join_with)
-        if ifnot:
-            writer.write('not ')
-        writer.node(expr)
-    writer.end_block()
-    writer.body(node.nodelist_true)
-    if node.nodelist_false:
-        writer.tag('else')
-        writer.body(node.nodelist_false)
-    writer.tag('endif')
-
-
-@node(core_tags.IfEqualNode)
-def if_equal(writer, node):
-    writer.start_block()
-    writer.write('if ')
-    writer.node(node.var1)
-    if node.negate:
-        writer.write(' != ')
-    else:
-        writer.write(' == ')
-    writer.node(node.var2)
-    writer.end_block()
-    writer.body(node.nodelist_true)
-    if node.nodelist_false:
-        writer.tag('else')
-        writer.body(node.nodelist_false)
-    writer.tag('endif')
-
-
-@node(loader_tags.BlockNode)
-def block(writer, node):
-    writer.tag('block ' + node.name.replace('-', '_').rstrip('_'))
-    node = node
-    while node.parent is not None:
-        node = node.parent
-    writer.body(node.nodelist)
-    writer.tag('endblock')
-
-
-@node(loader_tags.ExtendsNode)
-def extends(writer, node):
-    writer.start_block()
-    writer.write('extends ')
-    if node.parent_name_expr:
-        writer.node(node.parent_name_expr)
-    else:
-        writer.literal(node.parent_name)
-    writer.end_block()
-    writer.body(node.nodelist)
-
-
-@node(loader_tags.ConstantIncludeNode)
-@node(loader_tags.IncludeNode)
-def include(writer, node):
-    writer.start_block()
-    writer.write('include ')
-    if hasattr(node, 'template'):
-        writer.literal(node.template.name)
-    else:
-        writer.node(node.template_name)
-    writer.end_block()
-
-
-@node(core_tags.CycleNode)
-def cycle(writer, node):
-    if not writer.in_loop:
-        writer.warn('Untranslatable free cycle (cycle outside loop)', node=node)
-        return
-    if node.variable_name is not None:
-        writer.start_block()
-        writer.write('set %s = ' % node.variable_name)
-    else:
-        writer.start_variable()
-    writer.write('loop.cycle(')
-    for idx, var in enumerate(node.raw_cycle_vars):
-        if idx:
-            writer.write(', ')
-        writer.node(var)
-    writer.write(')')
-    if node.variable_name is not None:
-        writer.end_block()
-    else:
-        writer.end_variable()
-
-
-@node(core_tags.FilterNode)
-def filter(writer, node):
-    writer.start_block()
-    writer.write('filter ')
-    writer.filters(node.filter_expr.filters, True)
-    writer.end_block()
-    writer.body(node.nodelist)
-    writer.tag('endfilter')
-
-
-@node(core_tags.AutoEscapeControlNode)
-def autoescape_control(writer, node):
-    original = writer.autoescape
-    writer.autoescape = node.setting
-    writer.body(node.nodelist)
-    writer.autoescape = original
-
-
-@node(core_tags.SpacelessNode)
-def spaceless(writer, node):
-    original = writer.spaceless
-    writer.spaceless = True
-    writer.warn('entering spaceless mode with different semantics', node)
-    # do the initial stripping
-    nodelist = list(node.nodelist)
-    if nodelist:
-        if isinstance(nodelist[0], TextNode):
-            nodelist[0] = TextNode(nodelist[0].s.lstrip())
-        if isinstance(nodelist[-1], TextNode):
-            nodelist[-1] = TextNode(nodelist[-1].s.rstrip())
-    writer.body(nodelist)
-    writer.spaceless = original
-
-
-@node(core_tags.TemplateTagNode)
-def template_tag(writer, node):
-    tag = {
-        'openblock':            writer.block_start_string,
-        'closeblock':           writer.block_end_string,
-        'openvariable':         writer.variable_start_string,
-        'closevariable':        writer.variable_end_string,
-        'opencomment':          writer.comment_start_string,
-        'closecomment':         writer.comment_end_string,
-        'openbrace':            '{',
-        'closebrace':           '}'
-    }.get(node.tagtype)
-    if tag:
-        writer.start_variable()
-        writer.literal(tag)
-        writer.end_variable()
-
-
-@node(core_tags.URLNode)
-def url_tag(writer, node):
-    writer.warn('url node used.  make sure to provide a proper url() '
-                'function', node)
-    if node.asvar:
-        writer.start_block()
-        writer.write('set %s = ' % node.asvar)
-    else:
-        writer.start_variable()
-    autoescape = writer.autoescape
-    writer.write('url(')
-    writer.literal(node.view_name)
-    for arg in node.args:
-        writer.write(', ')
-        writer.node(arg)
-    for key, arg in node.kwargs.items():
-        writer.write(', %s=' % key)
-        writer.node(arg)
-    writer.write(')')
-    if node.asvar:
-        writer.end_block()
-    else:
-        writer.end_variable()
-
-
-@node(core_tags.WidthRatioNode)
-def width_ratio(writer, node):
-    writer.warn('widthratio expanded into formula.  You may want to provide '
-                'a helper function for this calculation', node)
-    writer.start_variable()
-    writer.write('(')
-    writer.node(node.val_expr)
-    writer.write(' / ')
-    writer.node(node.max_expr)
-    writer.write(' * ')
-    writer.write(str(int(node.max_width)))
-    writer.write(')|round|int')
-    writer.end_variable(always_safe=True)
-
-
-@node(core_tags.WithNode)
-def with_block(writer, node):
-    writer.warn('with block expanded into set statement.  This could cause '
-                'variables following that block to be overriden.', node)
-    writer.start_block()
-    writer.write('set %s = ' % node.name)
-    writer.node(node.var)
-    writer.end_block()
-    writer.body(node.nodelist)
-
-
-@node(core_tags.RegroupNode)
-def regroup(writer, node):
-    if node.expression.var.literal:
-        writer.warn('literal in groupby filter used.   Behavior in that '
-                    'situation is undefined and translation is skipped.', node)
-        return
-    elif node.expression.filters:
-        writer.warn('filters in groupby filter used.   Behavior in that '
-                    'situation is undefined which is most likely a bug '
-                    'in your code.  Filters were ignored.', node)
-    writer.start_block()
-    writer.write('set %s = ' % node.var_name)
-    writer.node(node.target)
-    writer.write('|groupby(')
-    writer.literal(node.expression.var.var)
-    writer.write(')')
-    writer.end_block()
-
-
-@node(core_tags.LoadNode)
-def warn_load(writer, node):
-    writer.warn('load statement used which was ignored on conversion', node)
-
-
-@node(i18n_tags.GetAvailableLanguagesNode)
-def get_available_languages(writer, node):
-    writer.warn('make sure to provide a get_available_languages function', node)
-    writer.tag('set %s = get_available_languages()' %
-               writer.translate_variable_name(node.variable))
-
-
-@node(i18n_tags.GetCurrentLanguageNode)
-def get_current_language(writer, node):
-    writer.warn('make sure to provide a get_current_language function', node)
-    writer.tag('set %s = get_current_language()' %
-               writer.translate_variable_name(node.variable))
-
-
-@node(i18n_tags.GetCurrentLanguageBidiNode)
-def get_current_language_bidi(writer, node):
-    writer.warn('make sure to provide a get_current_language_bidi function', node)
-    writer.tag('set %s = get_current_language_bidi()' %
-               writer.translate_variable_name(node.variable))
-
-
-@node(i18n_tags.TranslateNode)
-def simple_gettext(writer, node):
-    writer.warn('i18n system used, make sure to install translations', node)
-    writer.start_variable()
-    writer.write('_(')
-    writer.node(node.value)
-    writer.write(')')
-    writer.end_variable()
-
-
-@node(i18n_tags.BlockTranslateNode)
-def translate_block(writer, node):
-    first_var = []
-    variables = set()
-
-    def touch_var(name):
-        variables.add(name)
-        if not first_var:
-            first_var.append(name)
-
-    def dump_token_list(tokens):
-        for token in tokens:
-            if token.token_type == TOKEN_TEXT:
-                writer.write(token.contents)
-            elif token.token_type == TOKEN_VAR:
-                writer.print_expr(token.contents)
-                touch_var(token.contents)
-
-    writer.warn('i18n system used, make sure to install translations', node)
-    writer.start_block()
-    writer.write('trans')
-    idx = -1
-    for idx, (key, var) in enumerate(node.extra_context.items()):
-        if idx:
-            writer.write(',')
-        writer.write(' %s=' % key)
-        touch_var(key)
-        writer.node(var.filter_expression)
-
-    have_plural = False
-    plural_var = None
-    if node.plural and node.countervar and node.counter:
-        have_plural = True
-        plural_var = node.countervar
-        if plural_var not in variables:
-            if idx > -1:
-                writer.write(',')
-            touch_var(plural_var)
-            writer.write(' %s=' % plural_var)
-            writer.node(node.counter)
-
-    writer.end_block()
-    dump_token_list(node.singular)
-    if node.plural and node.countervar and node.counter:
-        writer.start_block()
-        writer.write('pluralize')
-        if node.countervar != first_var[0]:
-            writer.write(' ' + node.countervar)
-        writer.end_block()
-        dump_token_list(node.plural)
-    writer.tag('endtrans')
-
-@node("SimpleNode")
-def simple_tag(writer, node):
-    """Check if the simple tag exist as a filter in """
-    name = node.tag_name
-    if writer.env and \
-       name not in writer.env.filters and \
-       name not in writer._filters_warned:
-        writer._filters_warned.add(name)
-        writer.warn('Filter %s probably doesn\'t exist in Jinja' %
-                    name)
-        
-    if not node.vars_to_resolve:
-        # No argument, pass the request
-        writer.start_variable()
-        writer.write('request|')
-        writer.write(name)
-        writer.end_variable()
-        return 
-    
-    first_var =  node.vars_to_resolve[0]
-    args = node.vars_to_resolve[1:]
-    writer.start_variable()
-    
-    # Copied from Writer.filters()
-    writer.node(first_var)
-    
-    writer.write('|')
-    writer.write(name)
-    if args:
-        writer.write('(')
-        for idx, var in enumerate(args):
-            if idx:
-                writer.write(', ')
-            if var.var:
-                writer.node(var)
-            else:
-                writer.literal(var.literal)
-        writer.write(')')
-    writer.end_variable()   
-
-# get rid of node now, it shouldn't be used normally
-del node

ext/django2jinja/example.py

@@ -1,7 +0,0 @@
-from django.conf import settings
-settings.configure(TEMPLATE_DIRS=['templates'], TEMPLATE_DEBUG=True)
-
-from django2jinja import convert_templates, Writer
-
-writer = Writer(use_jinja_autoescape=True)
-convert_templates('converted', writer=writer)

ext/django2jinja/templates/index.html

@@ -1,58 +0,0 @@
-{% extends "layout.html" %}
-{% load i18n %}
-{% block title %}Foo{% endblock %}
-{% block page-body %}
-  {{ block.super }}
-  Hello {{ name|cut:"d" }}!
-
-  {% for item in seq reversed %}
-    {% if forloop.index|divisibleby:2 %}
-      <li class="{% cycle 'a' 'b' %}">{{ item }}</li>
-    {% endif %}
-  {% endfor %}
-  {% ifequal foo bar %}
-    haha
-  {% else %}
-    hmm
-  {% endifequal %}
-  {% filter upper %}
-    {% include "subtemplate.html" %}
-    {% include foo %}
-  {% endfilter %}
-  {% spaceless %}
-    Hello World
-      {{ foo }}
-    Hmm
-  {% endspaceless %}
-  {% templatetag opencomment %}...{% templatetag closecomment %}
-  {% url foo a, b, c=d %}
-  {% url foo a, b, c=d as hmm %}
-
-  {% with object.value as value %}
-    <img src='bar.gif' height='10' width='{% widthratio value 200 100 %}'>
-  {% endwith %}
-
-  <pre>{% debug %}</pre>
-
-  {% blocktrans with book|title as book_t and author|title as author_t %}
-  This is {{ book_t }} by {{ author_t }}
-  {% endblocktrans %}
-
-  {% blocktrans count list|length as counter %}
-  There is only one {{ name }} object.
-  {% plural %}
-  There are {{ counter }} {{ name }} objects.
-  {% endblocktrans %}
-
-  {% blocktrans with name|escape as name count list|length as counter %}
-  There is only one {{ name }} object.
-  {% plural %}
-  There are {{ counter }} {{ name }} objects.
-  {% endblocktrans %}
-
-  {% blocktrans %}This string will have {{ value }} inside.{% endblocktrans %}
-
-  <p>{% trans "This is the title." %}</p>
-
-  {% regroup people by gender as grouped %}
-{% endblock %}

ext/django2jinja/templates/layout.html

@@ -1,4 +0,0 @@
-<title>{% block title %}{% endblock %}</title>
-<div class="body">
-  {% block page-body %}{% endblock %}
-</div>