API

В данном документе описывается API для Jinja2, а не язык шаблонов. Он будет наиболее полезен для тех, кто реализует интерфейс шаблонов в приложении, а не для тех, кто создаёт шаблоны Jinja2.

Основы

Jinja2 использует центральный объект, называемый шаблоном Environment. Экземпляры этого класса используются для хранения конфигурации и глобальных объектов, а также для загрузки шаблонов из файловой системы или других источников. Даже если вы создаёте шаблоны из строк, используя конструктор класса Template, для вас автоматически создаётся окружение, хотя и общее.

Большинство приложений создают один объект Environment при инициализации приложения и используют его для загрузки шаблонов. Однако в некоторых случаях полезно иметь несколько окружений, если используются разные конфигурации.

Самый простой способ настроить Jinja2 для загрузки шаблонов для вашего приложения выглядит примерно так:

from jinja2 import Environment, PackageLoader, select_autoescape
env = Environment(
    loader=PackageLoader('yourapplication', 'templates'),
    autoescape=select_autoescape(['html', 'xml'])
)

Это создаст окружение шаблонов с настройками по умолчанию и загрузчиком, который ищет шаблоны в папке templates внутри пакета Python yourapplication. Доступны различные загрузчики, и вы также можете написать свой собственный, если хотите загружать шаблоны из базы данных или других ресурсов. Это также включает Автоэкранирование для HTML и XML-файлов.

Для загрузки шаблона из этого окружения достаточно вызвать метод get_template(), который затем возвращает загруженный Template:

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

Чтобы отобразить его с некоторыми переменными, просто вызовите метод render():

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

Использование загрузчика шаблонов вместо передачи строк в Template или Environment.from_string() имеет несколько преимуществ. Помимо того, что это намного проще в использовании, это также позволяет использовать наследование шаблонов.

Unicode

Jinja2 использует Unicode внутри, что означает, что вам нужно передавать объекты Unicode в функцию отображения или строки байтов, состоящие только из символов ASCII. Кроме того, новые строки нормализуются до одного кода новой строки, который по умолчанию является стилем UNIX (\n).

Python 2.x поддерживает два способа представления строковых объектов. Один — это тип str, а другой — тип unicode, оба из которых расширяют тип, называемый basestring. К сожалению, по умолчанию используется str, который не следует использовать для хранения текстовой информации, если не используются только символы ASCII. В Python 2.6 можно сделать unicode значением по умолчанию на уровне модуля, а в Python 3 это будет значением по умолчанию.

Чтобы явно использовать строку Unicode, нужно добавить префикс u к строковой литерале: u'Hänsel und Gretel sagen Hallo'. Таким образом, Python будет хранить строку в виде Unicode, декодируя её с помощью кодировки символов из текущего модуля Python. Если кодировка не указана, по умолчанию используется ‘ASCII’, что означает, что вы не можете использовать никаких символов, не являющихся ASCII.

Чтобы установить лучшую кодировку модуля, добавьте следующую строку комментария в первую или вторую строку модуля Python, использующего строковую литералу Unicode:

# -*- coding: utf-8 -*-

Мы рекомендуем utf-8 в качестве кодировки для модулей и шаблонов Python, так как в нём можно представить каждый символ Unicode, и он обратной совместим с ASCII. Для Jinja2 кодировка шаблонов по умолчанию предполагается utf-8.

Невозможно использовать Jinja2 для обработки не-Unicode данных. Причина в том, что Jinja2 использует Unicode уже на уровне языка. Например, Jinja2 рассматривает неразрывный пробел как допустимый пробел внутри выражений, что требует знания кодировки или работы со строкой Unicode.

Для получения более подробной информации об Unicode в Python ознакомьтесь с отличной документацией по Unicode.

Ещё одним важным моментом является то, как Jinja2 обрабатывает строковые литералы в шаблонах. Примитивное решение — использовать строки Unicode для всех строковых литералов, но в прошлом оказалось, что это проблематично, так как некоторые библиотеки проверяют тип str явно. Например, datetime.strftime не принимает аргументы Unicode. Чтобы не сломать это полностью, Jinja2 возвращает str для строк, которые помещаются в ASCII, и для всего остального unicode:

>>> m = Template(u"{% set a, b = 'foo', 'föö' %}").module
>>> m.a
'foo'
>>> m.b
u'f\xf6\xf6'

API высокого уровня

API высокого уровня — это API, которое вы будете использовать в приложении для загрузки и рендеринга шаблонов Jinja2. API низкого уровня, с другой стороны, полезно только если вы хотите углубиться в Jinja2 или разрабатывать расширения.

class jinja2.Environment([options])

Основной компонент Jinja — это Environment. Он содержит важные общие переменные, такие как конфигурация, фильтры, тесты, глобальные переменные и другие. Экземпляры этого класса можно изменять, если они не являются общими и если до сих пор не было загружено ни одной шаблона. Изменения в средах после загрузки первого шаблона приведут к неожиданным последствиям и неопределённому поведению.

Вот возможные параметры инициализации:

block_start_string

Строка, обозначающая начало блока. По умолчанию '{%'.

block_end_string

Строка, обозначающая конец блока. По умолчанию '%}'.

variable_start_string

Строка, обозначающая начало оператора вывода. По умолчанию '{{'.

variable_end_string

Строка, обозначающая конец оператора вывода. По умолчанию '}}'.

comment_start_string

Строка, обозначающая начало комментария. По умолчанию '{#'.

comment_end_string

Строка, обозначающая конец комментария. По умолчанию '#}'.

line_statement_prefix

Если задано и является строкой, это будет использоваться в качестве префикса для операторов на основе строк. См. также Операторы на основе строк.

line_comment_prefix

Если задано и является строкой, это будет использоваться в качестве префикса для комментариев на основе строк. См. также Операторы на основе строк.

Changelog

New in version 2.2.

trim_blocks

Если это установлено в True, первая новая строка после блока удаляется (блок, а не тег переменной!). По умолчанию False.

lstrip_blocks

Если это установлено в True, ведущие пробелы и табуляции удаляются из начала строки до блока. По умолчанию False.

newline_sequence

Последовательность, которая запускает новую строку. Должно быть одним из '\r', '\n' или '\r\n' По умолчанию '\n', что является полезным значением по умолчанию для систем Linux и OS X, а также веб-приложений.

keep_trailing_newline

Сохранить заключительную новую строку при рендеринге шаблонов. По умолчанию False, что приводит к удалению единственной новой строки, если она присутствует, из конца шаблона.

Changelog

New in version 2.7.

extensions

Список расширений Jinja для использования. Это могут быть пути импорта в виде строк или классы расширений. Более подробную информацию можно найти в документации по расширениям.

optimized

должен ли быть включён оптимизатор? По умолчанию True.

undefined

Undefined или подкласс от него, используемый для представления неопределённых значений в шаблоне.

finalize

Вызываемый объект, который может использоваться для обработки результата выражения переменной перед его выводом. Например, можно неявно преобразовать None в пустую строку здесь.

autoescape

Если установлено в True, функция автоматического экранирования XML/HTML включена по умолчанию. Более подробную информацию об автоматическом экранировании см. в Markup. Начиная с Jinja 2.4, это также может быть вызываемый объект, которому передаётся имя шаблона, и который должен вернуть True или False в зависимости от того, должно ли быть включено автоматическое экранирование по умолчанию.

Changelog

Изменено в версии 2.4: autoescape теперь может быть функцией

loader

Загрузчик шаблонов для этой среды.

cache_size

Размер кэша. По умолчанию это 400, что означает, что если загружено более 400 шаблонов, загрузчик очистит наименее используемый шаблон. Если размер кэша установлен на 0, шаблоны будут перекомпилироваться каждый раз, если размер кэша -1, кэш не будет очищен.

Changelog

Изменено в версии 2.8: Размер кэша был увеличен с 50 до 400.

auto_reload

Некоторые загрузчики загружают шаблоны из мест, где исходные файлы шаблонов могут меняться (например, файловая система или база данных). Если auto_reload установлено в True (по умолчанию), каждый раз при запросе шаблона загрузчик проверяет, изменился ли исходный файл, и если да, то перезагружает шаблон. Для повышения производительности это можно отключить.

bytecode_cache

Если установлено в объект кэша байткода, этот объект предоставит кэш для внутреннего байткода Jinja, поэтому шаблоны не будут анализироваться, если они не были изменены.

См. Кэш байткода для получения дополнительной информации.

enable_async

Если установлено в значение true, это включит асинхронное выполнение шаблонов, что позволит вам воспользоваться новыми функциями Python. Это требует Python 3.6 или более поздней версии.

shared

Если шаблон был создан с помощью конструктора Template, среда создаётся автоматически. Эти среды создаются как общие среды, что означает, что несколько шаблонов могут иметь одну и ту же безымянную среду. Для всех общих сред этот атрибут True, иначе False.

sandboxed

Если среда защищена, этот атрибут True. Для режима защиты см. документацию по SandboxedEnvironment.

filters

Словарь фильтров для этой среды. Пока не загружен ни один шаблон, безопасно добавлять новые фильтры или удалять старые. Для пользовательских фильтров см. Пользовательские фильтры. Для допустимых имён фильтров см. Примечания по именованию идентификаторов.

tests

Словарь тестовых функций для этой среды. Пока не загружен ни один шаблон, безопасно изменять этот словарь. Для пользовательских тестов см. Пользовательские тесты. Для допустимых имён тестов см. Примечания по именованию идентификаторов.

globals

Словарь глобальных переменных. Эти переменные всегда доступны в шаблоне. Пока не загружен ни один шаблон, безопасно изменять этот словарь. Более подробную информацию см. в Глобальное пространство имён. Для допустимых имён объектов см. Примечания по именованию идентификаторов.

policies

Словарь Политики. Их можно переконфигурировать для изменения поведения во время выполнения или определённых функций шаблонов. Обычно это функции, связанные с безопасностью.

code_generator_class

Класс, используемый для генерации кода. Его обычно не следует изменять, если только вам не нужно изменить код Python, в который компилируется шаблон.

context_class

Контекст, используемый для шаблонов. Его обычно не следует изменять, если только вам не нужно изменить внутреннее устройство обработки переменных шаблона. Для получения подробностей см. Context.

overlay([options])

Создаёт новую среду с наложением, которая разделяет все данные с текущей средой, за исключением кэша и перезаписанных атрибутов. Расширения не могут быть удалены для наложенной среды. Наложенная среда автоматически получает все расширения среды, к которой она подключена, плюс дополнительные расширения.

Создание наложений должно происходить после полной настройки исходной среды. Не все атрибуты действительно связаны, некоторые просто копируются, поэтому изменения в исходной среде могут не проходить через наложенную.

undefined([hint, obj, name, exc])

Создаёт новый объект Undefined для name. Это полезно для фильтров или функций, которые могут возвращать неопределённые объекты для некоторых операций. Все параметры, кроме hint, должны быть предоставлены в виде именованных параметров для лучшей читаемости. hint используется в качестве сообщения об ошибке для исключения, если оно предоставлено, в противном случае сообщение об ошибке будет сгенерировано из obj и name автоматически. Исключение, предоставленное как exc, генерируется, если с сгенерированным неопределённым объектом выполняется операция, которую этот объект не поддерживает. По умолчанию используется исключение UndefinedError. Если предоставлен hint, name можно опустить.

Наиболее распространённый способ создания неопределённого объекта — это предоставление только имени:

return environment.undefined(name='some_name')

Это означает, что имя some_name не определено. Если имя взято из атрибута объекта, имеет смысл указать неопределённому объекту владелец объекта, чтобы улучшить сообщение об ошибке:

if not hasattr(obj, 'attr'):
    return environment.undefined(obj=obj, name='attr')

Для более сложного примера можно предоставить подсказку. Например, фильтр first() создаёт неопределённый объект таким образом:

return environment.undefined('no first item, sequence was empty')

Если известно значение name или obj (например, потому что был получен доступ к атрибуту), его следует передать в неопределённый объект, даже если предоставлено пользовательское hint. Это даёт неопределённым объектам возможность улучшать сообщение об ошибке.

add_extension(extension)

Добавляет расширение после создания среды.

Changelog

Добавлено в версии 2.5.

compile_expression(source, undefined_to_none=True)

Полезный вспомогательный метод, возвращающий вызываемый объект, принимающий именованные аргументы, которые появляются как переменные в выражении. При вызове он возвращает результат выражения.

Это полезно, если приложения хотят использовать те же правила, что и Jinja, в «конфигурационных файлах» шаблонов или подобных ситуациях.

Пример использования:

>>> env = Environment()
>>> expr = env.compile_expression('foo == 42')
>>> expr(foo=23)
False
>>> expr(foo=42)
True

По умолчанию возвращаемое значение преобразуется в None, если выражение возвращает неопределённое значение. Это можно изменить, установив undefined_to_none в False.

>>> env.compile_expression('var')() is None
True
>>> env.compile_expression('var', undefined_to_none=False)()
Undefined

Changelog

Добавлено в версии 2.1.

compile_templates(target, extensions=None, filter_func=None, zip='deflated', log_function=None, ignore_errors=True, py_compile=False)

Находит все шаблоны, которые может найти загрузчик, компилирует их и сохраняет в target. Если zip равно None, вместо zip-архива, шаблоны будут сохранены в каталоге. По умолчанию используется алгоритм сжатия deflate. Чтобы переключиться на другой алгоритм, zip можно установить на 'stored'.

extensions и filter_func передаются в list_templates(). Каждый возвращённый шаблон будет скомпилирован в целевую папку или zip-архив.

По умолчанию ошибки компиляции шаблонов игнорируются. В случае, если предоставлена функция регистрации, ошибки регистрируются. Если вы хотите, чтобы ошибки синтаксиса шаблонов приводили к прерыванию компиляции, вы можете установить ignore_errors на False, и при возникновении синтаксических ошибок будет сгенерировано исключение.

Если py_compile установлено на True, вместо стандартных файлов .py будут созданы файлы .pyc в целевой папке. Этот флаг не действует на pypy и Python 3, где файлы .pyc не используются по умолчанию и не дают значимого преимущества.

Changelog

Добавлено в версии 2.4.

extend(**attributes)

Добавляет элементы в экземпляр среды, если они ещё не существуют. Используется расширениями (расширения) для регистрации обратных вызовов и значений конфигурации без нарушения наследования.

from_string(source, globals=None, template_class=None)

Загружает шаблон из строки. Парсит предоставленный исходный код и возвращает объект Template.

get_or_select_template(template_name_or_list, parent=None, globals=None)

Выполняет проверку типа и перенаправляет вызов на select_template(), если предоставлен итерируемый список имён шаблонов, в противном случае на get_template().

Changelog

Добавлено в версии 2.3.

get_template(name, parent=None, globals=None)

Загружает шаблон из загрузчика. Если настроен загрузчик, этот метод запрашивает шаблон у загрузчика и возвращает объект Template. Если параметр parent не None, вызывается join_path() для получения реального имени шаблона перед загрузкой.

Параметр globals может использоваться для предоставления глобальных переменных для всего шаблона. Эти переменные доступны в контексте во время рендеринга.

Если шаблон не существует, генерируется исключение TemplateNotFound.

Changelog

Изменено в версии 2.4: Если name — объект Template, он возвращается из функции без изменений.

join_path(template, parent)

Объединяет имя шаблона с родительским. По умолчанию все запросы выполняются относительно корня загрузчика, поэтому этот метод возвращает значение параметра template без изменений. Однако если пути должны быть относительно родительского шаблона, эта функция может использоваться для вычисления реального имени шаблона.

Подклассы могут переопределить этот метод и реализовать объединение путей шаблонов здесь.

list_templates(extensions=None, filter_func=None)

Возвращает список шаблонов для данной среды. Для этого требуется, чтобы загрузчик поддерживал метод list_templates() загрузчика.

Если в папке шаблонов есть другие файлы помимо самих шаблонов, возвращаемый список можно отфильтровать. Существуют два способа: либо extensions установлено в список расширений файлов для шаблонов, либо предоставлен filter_func, который является вызываемым объектом, которому передаётся имя шаблона, и который должен возвращать True если имя должно быть включено в результирующий список.

Если загрузчик не поддерживает это, генерируется исключение TypeError.

Changelog

Добавлено в версии 2.4.

select_template(names, parent=None, globals=None)

Работает как get_template(), но пытается найти несколько шаблонов, прежде чем потерпеть неудачу. Если ни один шаблон не найден, генерируется исключение TemplatesNotFound.

Изменено в версии 2.11: Если names — Undefined, генерируется исключение UndefinedError. Если шаблоны не найдены, а names содержит Undefined, сообщение об ошибке будет более информативным.

Changelog

Изменено в версии 2.4: Если names содержит объект Template, он возвращается из функции без изменений.

Добавлено в версии 2.3.

class jinja2.Template

Основной объект шаблона. Этот класс представляет скомпилированный шаблон и используется для его оценки.

Обычно объект шаблона генерируется из Environment, но также имеет конструктор, позволяющий создать экземпляр шаблона напрямую. Он принимает те же аргументы, что и конструктор среды, но указать загрузчик нельзя.

Каждый объект шаблона имеет несколько методов и членов, гарантированно существующих. Однако важно, что объект шаблона должен рассматриваться как неизменяемый. Изменения в объекте не поддерживаются.

Объекты шаблонов, созданные с помощью конструктора, а не среды, имеют атрибут environment, который указывает на временную среду, которая, вероятно, совместно используется с другими шаблонами, созданными с помощью конструктора и совместимых настроек.

>>> template = Template('Hello {{ name }}!')
>>> template.render(name='John Doe') == u'Hello John Doe!'
True
>>> stream = template.stream(name='John Doe')
>>> next(stream) == u'Hello John Doe!'
True
>>> next(stream)
Traceback (most recent call last):
    ...
StopIteration

globals

Словарь со глобальными переменными этого шаблона. Изменять этот словарь небезопасно, так как он может быть совместно использован другими шаблонами или средой, загрузившей шаблон.

name

Имя загруженного шаблона. Если шаблон загружен из строки, это None.

filename

Имя файла шаблона в файловой системе, если он был загружен оттуда. В противном случае это None.

render([context])

Этот метод принимает те же аргументы, что и конструктор dict: Словарь, подкласс словаря или некоторые ключевые аргументы. Если аргументы не указаны, контекст будет пустым. Эти два вызова делают одно и то же:

template.render(knights='that say nih')
template.render({'knights': 'that say nih'})

Это вернёт отрендеренный шаблон в виде строки Unicode.

generate([context])

Для очень больших шаблонов может быть полезно не рендерить весь шаблон сразу, а оценивать каждую инструкцию поочерёдно и выводить фрагменты по частям. Этот метод делает именно это и возвращает генератор, который выдает по одному элементу за раз в виде строк Unicode.

Он принимает те же аргументы, что и render().

stream([context])

Работает точно так же, как generate(), но возвращает TemplateStream.

render_async([context])

Поведение аналогично render(), но возвращает корутину, которая при ожидании возвращает всю отрендеренную строку шаблона. Для этого требуется включить асинхронный режим.

Пример использования:

await template.render_async(knights='that say nih; asynchronously')

generate_async([context])

Асинхронная версия generate(). Работает очень похоже, но возвращает асинхронный итератор.

make_module(vars=None, shared=False, locals=None)

Этот метод работает как атрибут module при вызове без аргументов, но он будет оценивать шаблон при каждом вызове, а не кешировать его. Также можно указать словарь, который затем используется в качестве контекста. Аргументы такие же, как и для метода new_context().

property module

Шаблон как модуль. Используется для импортов в шаблон во время выполнения, но также полезен, если нужно получить доступ к экспортированным переменным шаблона из Python-слоя:

>>> t = Template('{% macro foo() %}42{% endmacro %}23')
>>> str(t.module)
'23'
>>> t.module.foo() == u'42'
True

Этот атрибут недоступен, если включен асинхронный режим.

class jinja2.environment.TemplateStream

Поток шаблона работает примерно так же, как обычный Python-генератор, но может буферизовать несколько элементов, чтобы уменьшить общее количество итераций. По умолчанию вывод не буферизуется, что означает, что для каждой небуферизованной инструкции в шаблоне генерируется одна строка Unicode.

Если буферизация включена с размером буфера 5, пять элементов объединяются в новую строку Unicode. Это в основном полезно, если вы передаете большие шаблоны клиенту через WSGI, который сбрасывает буфер после каждой итерации.

disable_buffering()

Отключить буферизацию вывода.

dump(fp, encoding=None, errors='strict')

Выгрузить весь поток в файл или файл-подобный объект. По умолчанию записываются строки Unicode, если вы хотите закодировать перед записью, укажите encoding.

Пример использования:

Template('Hello {{ name }}!').stream(name='foo').dump('hello.html')

enable_buffering(size=5)

Включить буферизацию. Буферизовать size элементов перед выдачей.

Автоэскэпинг

Автоэскэпинг — это функция, позволяющая минимизировать атаки при рендеринге HTML и XML документов. При включённом автоэскэпинге Jinja будет использовать MarkupSafe для экранирования небезопасных символов в выводе выражений, если вывод не помечен как безопасный. Например, если комментарий содержал <script>alert("hello")</script>, теги будут отображены с экранированием, таким как <script>. В браузере пользователя комментарий будет отображаться как текст, а не интерпретироваться как сценарий.

Поскольку Jinja может использоваться для рендеринга любого типа документа для многих типов приложений, а не только HTML с ненадежными данными, автоэскэпинг не включён по умолчанию. При создании среды вы должны настроить разумное значение по умолчанию, исходя из вашего случая использования. Функция select_autoescape() может быть использована для включения автоэскэпинга для HTML-шаблонов и отключения его в текстовых шаблонах.

jinja2.select_autoescape(enabled_extensions=('html', 'htm', 'xml'), disabled_extensions=(), default_for_string=True, default=False)

Умный способ установить начальное значение автоэскэпинга на основе имени файла шаблона. Это рекомендуемый способ настроить автоэскэпинг, если вы не хотите писать собственную функцию.

Если вы хотите включить его для всех шаблонов, созданных из строк, или для всех шаблонов с расширениями .html и .xml:

from jinja2 import Environment, select_autoescape
env = Environment(autoescape=select_autoescape(
    enabled_extensions=('html', 'xml'),
    default_for_string=True,
))

Пример конфигурации для включения всегда, кроме случаев, когда шаблон заканчивается на .txt:

from jinja2 import Environment, select_autoescape
env = Environment(autoescape=select_autoescape(
    disabled_extensions=('txt',),
    default_for_string=True,
    default=True,
))

enabled_extensions — это итерируемый объект всех расширений, для которых должен быть включен автоэскэпинг. Соответственно, disabled_extensions — это список всех шаблонов, для которых он должен быть отключён. Если шаблон загружен из строки, используется значение по умолчанию из default_for_string. Если ничего не соответствует, начальное значение автоэскэпинга устанавливается в значение default.

По соображениям безопасности эта функция работает без учёта регистра.

Changelog

Добавлена в версии 2.9.

Вы также можете передать autoescape=True для его безусловного включения или свою собственную функцию, которая принимает имя шаблона и возвращает, нужно ли его включать. При написании функции убедитесь, что вы принимаете None в качестве имени, так как это будет передаваться для шаблонов из строк.

Внутри шаблона поведение можно временно изменить, используя блок autoescape, см. Автоэскэпинг.

Примечания по именованию идентификаторов

Jinja2 использует стандартные правила именования Python 2.x. Действительные идентификаторы должны соответствовать [a-zA-Z_][a-zA-Z0-9_]*. На самом деле в настоящее время не допускаются символы, отличные от ASCII. Это ограничение, вероятно, исчезнет, как только идентификаторы Unicode будут полностью специфицированы для Python 3.

Фильтры и тесты ищутся в отдельных пространствах имён и имеют немного изменённый синтаксис идентификаторов. Фильтры и тесты могут содержать точки для группировки фильтров и тестов по темам. Например, вполне допустимо добавить функцию в словарь фильтров и вызвать её to.unicode. Регулярное выражение для идентификаторов фильтров и тестов — [a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)*`.

Типы Undefined

Эти классы могут быть использованы как типы Undefined. Конструктор Environment принимает параметр undefined, который может быть одним из этих классов или настраиваемым подклассом Undefined. Всякий раз, когда движок шаблонов не может найти имя или получить доступ к атрибуту, создается один из этих объектов и возвращается. Некоторые операции с неопределёнными значениями разрешены, другие — нет.

Наиболее близким к стандартному поведению Python является тип StrictUndefined, который запрещает все операции, кроме проверки, является ли объект неопределённым.

class jinja2.Undefined

Тип по умолчанию для неопределённых значений. Этот тип неопределённого значения можно выводить на печать и итерировать по нему, но любой другой доступ вызовет UndefinedError:

>>> foo = Undefined(name='foo')
>>> str(foo)
''
>>> not foo
True
>>> foo + 42
Traceback (most recent call last):
  ...
jinja2.exceptions.UndefinedError: 'foo' is undefined

_undefined_hint

Либо None или строка Юникод с сообщением об ошибке для неопределённого объекта.

_undefined_obj

Либо None или владеющий объект, который вызвал создание неопределённого объекта (например, потому что атрибут не существует).

_undefined_name

Имя неопределённой переменной/атрибута или просто None если такая информация отсутствует.

_undefined_exception

Исключение, которое должен поднять неопределённый объект. Обычно это одно из UndefinedError или SecurityError.

_fail_with_undefined_error(*args, **kwargs)

При вызове с любыми аргументами этот метод поднимает _undefined_exception с сообщением об ошибке, сгенерированным из подсказок неопределённости, хранящихся в неопределённом объекте.

class jinja2.DebugUndefined

Неопределённое значение, которое возвращает отладочную информацию при выводе на печать.

>>> foo = DebugUndefined(name='foo')
>>> str(foo)
'{{ foo }}'
>>> not foo
True
>>> foo + 42
Traceback (most recent call last):
  ...
jinja2.exceptions.UndefinedError: 'foo' is undefined

class jinja2.StrictUndefined

Неопределённое значение, которое подаёт сигнал об ошибке при печати, итерации, а также при проверках на истинность и всех видах сравнений. Другими словами: вы ничего не можете с ним сделать, кроме как проверить, определено ли оно с помощью проверки defined.

>>> foo = StrictUndefined(name='foo')
>>> str(foo)
Traceback (most recent call last):
  ...
jinja2.exceptions.UndefinedError: 'foo' is undefined
>>> not foo
Traceback (most recent call last):
  ...
jinja2.exceptions.UndefinedError: 'foo' is undefined
>>> foo + 42
Traceback (most recent call last):
  ...
jinja2.exceptions.UndefinedError: 'foo' is undefined

Также существует фабричная функция, которая может модифицировать неопределённые объекты для реализации ведения журнала при возникновении ошибок:

jinja2.make_logging_undefined(logger=None, base=None)

Принимая объект регистратора, эта функция возвращает новый класс неопределённых значений, который будет вести журнал определённых ошибок. Будет вести журнал итераций и печати. Если регистратор не указан, создаётся стандартный регистратор.

Пример:

logger = logging.getLogger(__name__)
LoggingUndefined = make_logging_undefined(
    logger=logger,
    base=Undefined
)

Changelog

Добавлена в версии 2.8.

Параметры

• logger – используемый регистратор. Если не указан, создаётся стандартный регистратор.
• base – базовый класс, к которому нужно добавить функциональность ведения журнала. По умолчанию Undefined.

Неопределённые объекты создаются путём вызова undefined.

class NullUndefined(Undefined):
    def __int__(self):
        return 0
    def __float__(self):
        return 0.0

class NonIterableUndefined(Undefined):
    __iter__ = Undefined._fail_with_undefined_error

Контекст

class jinja2.runtime.Context

Контекст шаблона хранит переменные шаблона. Он хранит значения, переданные в шаблон, а также имена, экспортируемые шаблоном. Создание экземпляров не поддерживается и не нужно, так как он создаётся автоматически на различных этапах оценки шаблона и не должен создаваться вручную.

Контекст неизменяемый. Изменения в parent не должны происходить, а изменения в vars разрешены только для сгенерированного кода шаблона. Фильтры шаблонов и глобальные функции, помеченные как contextfunction()s получают активный контекст в качестве первого аргумента и могут получать доступ к контексту только для чтения.

Контекст шаблона поддерживает операции только для чтения словаря (get, keys, values, items, iterkeys, itervalues, iteritems, __getitem__, __contains__). Кроме того, есть метод resolve(), который не приводит к ошибке при KeyError а возвращает объект Undefined для отсутствующих переменных.

parent

Словарь только для чтения, глобальных переменных, которые просматривает шаблон. Они могут поступать от другого Context, из Environment.globals или Template.globals или ссылаются на словарь, созданный путём объединения глобальных значений с переменными, переданными в функцию рендеринга. Он не должен изменяться.

vars

Локальные переменные шаблона. Этот список содержит функции среды и контекста из области parent, а также локальные изменения и экспортируемые переменные из шаблона. Шаблон будет изменять этот словарь во время оценки шаблона, но фильтры и функции контекста не могут его изменять.

environment

Среда, которая загрузила шаблон.

exported_vars

Этот набор содержит все имена, экспортируемые шаблоном. Значения для имён находятся в словаре vars. Для получения копии экспортированных переменных как словаря можно использовать get_exported().

name

Имя загрузки шаблона, владеющего этим контекстом.

blocks

Словарь с текущим отображением блоков в шаблоне. Ключи в этом словаре — имена блоков, а значения — список зарегистрированных блоков. Последний элемент в каждом списке — текущий активный блок (последний в цепочке наследования).

eval_ctx

Текущий Контекст оценки.

call(callable, *args, **kwargs)

Вызывает вызываемый объект с предоставленными аргументами и ключевыми аргументами, но вводит активный контекст или среду в качестве первого аргумента, если вызываемый объект является contextfunction() или environmentfunction().

get_all()

Возвращает весь контекст в виде словаря, включая экспортируемые переменные. Из соображений оптимизации это может не возвращать фактическую копию, поэтому будьте осторожны при её использовании.

get_exported()

Получает новый словарь с экспортированными переменными.

resolve(key)

Ищет переменную, как __getitem__ или get, но возвращает объект Undefined с именем искомого имени.

Загрузчики

Загрузчики отвечают за загрузку шаблонов из ресурсов, таких как файловая система. Среда будет хранить скомпилированные модули в памяти, как в Python sys.modules. В отличие от sys.modules однако, этот кэш по умолчанию ограничен по размеру, а шаблоны автоматически перезагружаются. Все загрузчики являются подклассами BaseLoader. Если вы хотите создать свой загрузчик, создайте подкласс BaseLoader и переопределите get_source.

class jinja2.BaseLoader

Базовый класс для всех загрузчиков. Подклассируйте его и переопределите get_source для реализации пользовательской механизма загрузки. Среда предоставляет метод get_template, который вызывает метод загрузчика load для получения объекта Template.

Очень простой пример загрузчика, который ищет шаблоны в файловой системе, может выглядеть так:

from jinja2 import BaseLoader, TemplateNotFound
from os.path import join, exists, getmtime

class MyLoader(BaseLoader):

    def __init__(self, path):
        self.path = path

    def get_source(self, environment, template):
        path = join(self.path, template)
        if not exists(path):
            raise TemplateNotFound(template)
        mtime = getmtime(path)
        with file(path) as f:
            source = f.read().decode('utf-8')
        return source, path, lambda: mtime == getmtime(path)

get_source(environment, template)

Получение исходного кода шаблона, имени файла и помощника по перезагрузке для шаблона. Ему передаются среда и имя шаблона, и он должен вернуть кортеж в формате (source, filename, uptodate) или поднять ошибку TemplateNotFound, если шаблон не найден.

Часть исходного кода возвращаемого кортежа должна содержать исходный код шаблона в виде строки Unicode или байтовой строки ASCII. Имя файла должно содержать имя файла в файловой системе, если он загружен оттуда, иначе None. Имя файла используется Python для отладки, если не используется расширение загрузчика.

Последним элементом кортежа является функция uptodate. Если включена автоматическая перезагрузка, она всегда вызывается для проверки изменения шаблона. Аргументы не передаются, поэтому функция должна где-то сохранить старое состояние (например, в замыкании). Если она возвращает False, шаблон будет перезагружен.

load(environment, name, globals=None)

Загрузка шаблона. Этот метод ищет шаблон в кэше или загружает его, вызывая get_source(). Подклассы не должны переопределять этот метод, так как загрузчики, работающие со множеством других загрузчиков (например, PrefixLoader или ChoiceLoader) не будут вызывать этот метод, а вызовут get_source напрямую.

Вот список встроенных загрузчиков, которые предоставляет Jinja2:

class jinja2.FileSystemLoader(searchpath, encoding='utf-8', followlinks=False)

Загружает шаблоны из файловой системы. Этот загрузчик может находить шаблоны в папках файловой системы и является предпочтительным способом их загрузки.

Загрузчик принимает путь к шаблонам в виде строки, или, если требуется несколько расположений, список из них, которые затем ищутся в заданном порядке:

>>> loader = FileSystemLoader('/path/to/templates')
>>> loader = FileSystemLoader(['/path/to/templates', '/other/path'])

По умолчанию кодировка шаблона — 'utf-8', которую можно изменить, установив параметр encoding на другое значение.

Для следования символическим ссылкам установите параметр followlinks в True:

>>> loader = FileSystemLoader('/path/to/templates', followlinks=True)

Изменения

Изменено в версии 2.8: Добавлен параметр followlinks.

class jinja2.PackageLoader(package_name, package_path='templates', encoding='utf-8')

Загружает шаблоны из python egg или пакетов. Он создаётся с именем python-пакета и путём к шаблонам в этом пакете:

loader = PackageLoader('mypackage', 'views')

Если путь к пакету не указан, предполагается 'templates'.

По умолчанию кодировка шаблона — 'utf-8', которую можно изменить, установив параметр encoding на другое значение. Из-за особенностей egg, перезагрузка шаблонов возможна только если пакет загружен из файловой системы, а не из zip-файла.

class jinja2.DictLoader(mapping)

Загружает шаблон из python-словаря. Ему передаётся словарь строк Unicode, связанных с именами шаблонов. Этот загрузчик полезен для юнит-тестирования:

>>> loader = DictLoader({'index.html': 'source here'})

Поскольку автоматическая перезагрузка редко полезна, она по умолчанию отключена.

class jinja2.FunctionLoader(load_func)

Загрузчик, которому передаётся функция, которая выполняет загрузку. Функция получает имя шаблона и должна вернуть либо строку Unicode с исходным кодом шаблона, кортеж в формате (source, filename, uptodatefunc) или None, если шаблон не существует.

>>> def load_template(name):
...     if name == 'index.html':
...         return '...'
...
>>> loader = FunctionLoader(load_template)

Функция uptodatefunc, которая вызывается при включённой автоматической перезагрузке, должна вернуть True, если шаблон не изменился. Дополнительную информацию см. в BaseLoader.get_source(), который имеет то же возвращаемое значение.

class jinja2.PrefixLoader(mapping, delimiter='/')

Загрузчик, которому передаётся словарь загрузчиков, где каждый загрузчик привязан к префиксу. Префикс отделяется от шаблона слешем по умолчанию, который можно изменить, установив параметр delimiter на другое значение:

loader = PrefixLoader({
    'app1':     PackageLoader('mypackage.app1'),
    'app2':     PackageLoader('mypackage.app2')
})

Загружая 'app1/index.html', загружается файл из пакета app1, а загружая 'app2/index.html', файл из второго.

class jinja2.ChoiceLoader(loaders)

Этот загрузчик работает как PrefixLoader, только без указания префикса. Если загрузчик не смог найти шаблон, используется следующий.

>>> loader = ChoiceLoader([
...     FileSystemLoader('/path/to/user/templates'),
...     FileSystemLoader('/path/to/system/templates')
... ])

Это полезно, если вы хотите разрешить пользователям переопределять встроенные шаблоны из другого местоположения.

class jinja2.ModuleLoader(path)

Этот загрузчик загружает шаблоны из предварительно скомпилированных шаблонов.

Пример использования:

>>> loader = ChoiceLoader([
...     ModuleLoader('/path/to/compiled/templates'),
...     FileSystemLoader('/path/to/templates')
... ])

Шаблоны можно предварительно скомпилировать с помощью Environment.compile_templates().

Кэш байткода

Jinja 2.1 и более поздние версии поддерживают внешний кэш байткода. Кэши байткода позволяют хранить сгенерированный байткод в файловой системе или другом месте, чтобы избежать разбора шаблонов при первом использовании.

Это особенно полезно для веб-приложений, которые инициализируются при первом запросе, и Jinja компилирует много шаблонов сразу, что замедляет работу приложения.

Для использования кэша байткода, инициализируйте его и передайте его в Environment.

class jinja2.BytecodeCache

Для реализации собственного кэша байткода необходимо подклассировать этот класс и переопределить load_bytecode() и dump_bytecode(). Оба этих метода получают Bucket.

Очень простой кэш байткода, который сохраняет байткод в файловой системе:

from os import path

class MyCache(BytecodeCache):

    def __init__(self, directory):
        self.directory = directory

    def load_bytecode(self, bucket):
        filename = path.join(self.directory, bucket.key)
        if path.exists(filename):
            with open(filename, 'rb') as f:
                bucket.load_bytecode(f)

    def dump_bytecode(self, bucket):
        filename = path.join(self.directory, bucket.key)
        with open(filename, 'wb') as f:
            bucket.write_bytecode(f)

Более продвинутая версия кэша байткода на основе файловой системы входит в состав Jinja.

clear()

Очищает кэш. Этот метод не используется Jinja, но должен быть реализован, чтобы приложения могли очищать кэш байткода, используемый конкретной средой.

dump_bytecode(bucket)

Подклассы должны переопределить этот метод, чтобы записать байткод из корзины обратно в кэш. Если это невозможно, не нужно молчать, а следует выбросить исключение.

load_bytecode(bucket)

Подклассы должны переопределить этот метод, чтобы загрузить байткод в корзину. Если они не могут найти код в кэше для корзины, ничего не должно происходить.

class jinja2.bccache.Bucket(environment, key, checksum)

Корзины используются для хранения байткода одного шаблона. Они создаются и инициализируются кэшем байткода и передаются функциям загрузки.

Корзины получают внутреннюю контрольную сумму, назначенную кэшем, и используют её для автоматического отклонения устаревшего кэшированного материала. Отдельным подклассам кэша байткода не нужно беспокоиться о недействительности кэша.

environment

Среда, которая создала корзину.

key

Уникальный ключ кэша для этой корзины

code

Байткод, если он загружен, иначе None.

bytecode_from_string(string)

Загрузка байткода из строки.

bytecode_to_string()

Возвращает байткод в виде строки.

load_bytecode(f)

Загрузка байткода из файла или объекта-подобного файлу.

reset()

Сброс корзины (выгрузка байткода).

write_bytecode(f)

Выгрузка байткода в переданный файл или похожий на файл объект.

Встроенные кэши байткода:

class jinja2.FileSystemBytecodeCache(directory=None, pattern='__jinja2_%s.cache')

Кэш байткода, который хранит байткод в файловой системе. Он принимает два аргумента: директорию, где хранятся элементы кэша, и строку шаблона, используемую для построения имени файла.

Если каталог не указан, выбирается каталог кэша по умолчанию. В Windows используется временный каталог пользователя, в системах UNIX создаётся каталог для пользователя в системном временном каталоге.

Шаблон можно использовать для работы с несколькими отдельными кэшами в одном каталоге. Шаблон по умолчанию — '__jinja2_%s.cache'. %s заменяется ключом кэша.

>>> bcc = FileSystemBytecodeCache('/tmp/jinja_cache', '%s.cache')

Этот кэш байткода поддерживает очистку кэша с помощью метода clear.

class jinja2.MemcachedBytecodeCache(client, prefix='jinja2/bytecode/', timeout=None, ignore_memcache_errors=True)

Этот класс реализует кэш байткода, использующий кэш memcache для хранения информации. Он не навязывает конкретную библиотеку memcache (memcache от tummy или cmemcache), а примет любой класс, предоставляющий минимальный необходимый интерфейс.

Библиотеки, совместимые с этим классом:

• cachelib
• python-memcached

(К сожалению, интерфейс кэша django несовместим, так как он не поддерживает хранение двоичных данных, только unicode. Однако вы можете передать базовый клиент кэша в кэш байткода, который доступен как django.core.cache.cache._client.)

Минимальный интерфейс для клиента, передаваемого в конструктор, выглядит так:

class MinimalClientInterface

set(key, value[, timeout])

Сохраняет байткод в кэше. value — строка, а timeout — таймаут ключа. Если таймаут не указан, предполагается стандартный таймаут или отсутствие таймаута; если он указан, это целое число, представляющее количество секунд, в течение которого элемент кэша должен существовать.

get(key)

Возвращает значение для ключа кэша. Если элемент не существует в кэше, возвращаемое значение должно быть None.

Другие аргументы конструктора — это префикс для всех ключей, добавляемый перед фактическим ключом кэша, и таймаут байткода в системе кэширования. Рекомендуется высокий (или отсутствующий) таймаут.

Этот кэш байткода не поддерживает очистку использованных элементов в кэше. Метод clear — это функция без действий.

Журнал изменений

Введено в версии 2.7: Добавлена поддержка игнорирования ошибок memcache через параметр ignore_memcache_errors.

Поддержка асинхронных операций

Начиная с версии 2.9, Jinja2 также поддерживает Python async и await конструкции. Что касается разработчиков шаблонов, эта функция полностью непрозрачна для них, однако как разработчик вы должны понимать, как она реализована, так как это влияет на типы API, которые вы можете безопасно экспонировать в среде шаблонов.

Сначала вы должны понимать, что по умолчанию поддержка асинхронных операций отключена, так как её включение сгенерирует другой код шаблона за кулисами, передавая всё через цикл событий asyncio. Это важно понимать, так как это оказывает некоторое влияние на ваши действия:

• для рендеринга шаблона потребуется цикл событий для текущей нити (asyncio.get_event_loop должен вернуть один)
• весь код генерации шаблонов внутри выполняется асинхронными генераторами, что означает, что вы будете платить за производительность даже если используются асинхронные методы!
• синхронные методы основаны на асинхронных методах, если включён асинхронный режим, что означает, что render , например, внутри вызовет render_async и выполнит его как часть текущего цикла событий до завершения выполнения.

Из функций в шаблонах могут возвращаться объекты awaitable, и любой вызов функции в шаблоне автоматически ожидает результата. Это означает, что вы можете предоставить метод, который асинхронно загружает данные из базы данных, если это необходимо, и с точки зрения разработчика шаблонов это просто ещё одна функция, которую они могут вызвать. Это означает, что await, который вы обычно используете в Python, подразумевается. Однако это относится только к вызовам функций. Если атрибут, например, является объектом avaitable, это не приведёт к ожидаемому поведению.

Аналогично, итерации с for циклом поддерживают асинхронные итераторы.

Политики

Начиная с Jinja 2.9, политики могут быть настроены в среде, что может немного повлиять на поведение фильтров и других конструкций шаблонов. Их можно настроить с помощью атрибута policies.

Пример:

env.policies['urlize.rel'] = 'nofollow noopener'

compiler.ascii_str:

Этот логический параметр управляет тем, будет ли Jinja2 в Python 2 хранить литералы только ASCII как байтовые строки вместо строк unicode. Это всегда было включено для версий Jinja ниже 2.9, а теперь его можно изменить. Раньше это делалось так, поскольку некоторые API в Python 2 плохо работали со строками unicode (например, API datetime strftime). Однако теперь иногда верно обратное (например, str.format). Если это значение установлено в False, все строки хранятся как unicode внутри.

truncate.leeway:

Настраивает значение по умолчанию leeway для фильтра truncate. Leeway введён в версии 2.9, но для сохранения совместимости со старыми шаблонами его можно настроить на 0 для возврата старого поведения. Значение по умолчанию — 5.

urlize.rel:

Строка, определяющая элементы для атрибута rel сгенерированных ссылок с помощью фильтра urlize. Эти элементы всегда добавляются. Значение по умолчанию — noopener.

urlize.target:

Целевой объект по умолчанию, который генерируется для ссылок от фильтра urlize при отсутствии другого явно указанного целевого объекта.

json.dumps_function:

Если это значение установлено не на None, то фильтр tojson будет использовать эту функцию вместо стандартной. Обратите внимание, что эта функция должна принимать произвольные дополнительные аргументы, которые могут быть переданы в будущем от фильтра. В настоящее время единственный аргумент, который может быть передан, — indent. Стандартная функция вывода — json.dumps.

json.dumps_kwargs:

Ключевые аргументы, которые должны быть переданы функции вывода. Значение по умолчанию — {'sort_keys': True}.

ext.i18n.trimmed:

Если это значение установлено на True, блоки {% trans %} расширения i18n Extension всегда объединяют символы переноса строки и окружающие пробелы, как если бы использовался модификатор trimmed.

Утилиты

Эти вспомогательные функции и классы полезны, если вы добавляете пользовательские фильтры или функции в среду Jinja2.

jinja2.environmentfilter(f)

Декоратор для обозначения фильтров, зависящих от среды. Текущий Environment передаётся фильтру в качестве первого аргумента.

jinja2.contextfilter(f)

Декоратор для обозначения фильтров, зависящих от контекста. Текущий Context будет передан как первый аргумент.

jinja2.evalcontextfilter(f)

Декоратор для обозначения фильтров, зависящих от контекста оценки. Объект контекста оценки передаётся в качестве первого аргумента. Для получения дополнительной информации о контексте оценки см. Контекст оценки.

Журнал изменений

Новое в версии 2.4.

jinja2.environmentfunction(f)

Этот декоратор можно использовать для обозначения функции или метода как вызываемой функцией среды. Этот декоратор работает точно так же, как декоратор contextfunction(), за исключением того, что первым аргументом является активная Environment, а не контекст.

jinja2.contextfunction(f)

Этот декоратор можно использовать для обозначения функции или метода как вызываемой функцией контекста. Вызываемая функция контекста получает активный Context как первый аргумент при вызове из шаблона. Это полезно, если функция хочет получить доступ к контексту или функциям, предоставляемым объектом контекста. Например, функция, возвращающая отсортированный список переменных шаблона, которые экспортирует текущий шаблон, может выглядеть так:

@contextfunction
def get_exported_names(context):
    return sorted(context.exported_vars)

jinja2.evalcontextfunction(f)

Этот декоратор можно использовать для обозначения функции или метода как вызываемой функцией контекста оценки. Это аналогично contextfunction(), но вместо передачи контекста передаётся объект контекста оценки. Для получения дополнительной информации о контексте оценки см. Контекст оценки.

Журнал изменений

Новое в версии 2.4.

jinja2.clear_caches()

Jinja сохраняет внутренние кэши для сред и лексических анализаторов. Они используются, чтобы Jinja не приходилось постоянно создавать среды и лексические анализаторы. Обычно вам об этом не нужно беспокоиться, но если вы измеряете потребление памяти, вы можете очистить кэши.

jinja2.is_undefined(obj)

Проверка, является ли переданный объект неопределённым. Это не делает ничего больше, чем выполняет проверку экземпляра на Undefined, но выглядит лучше. Это может быть использовано для пользовательских фильтров или проверок, которые хотят реагировать на неопределённые переменные. Например, пользовательский фильтр по умолчанию может выглядеть так:

def default(var, default=''):
    if is_undefined(var):
        return default
    return var

markupsafe.escape(s) → markup

Преобразует символы &, <, >, ‘ и ” в строке s в безопасные для HTML последовательности. Используйте это, если вам нужно отобразить текст, который может содержать такие символы в HTML. Помечает возвращаемое значение как строку разметки.

class markupsafe.Markup

Строка, готовая к безопасному вставлению в HTML- или XML-документ, либо потому, что она была экранирована, либо потому, что она была помечена как безопасная.

Передача объекта в конструктор преобразует его в текст и оборачивает его, чтобы пометить его как безопасный без экранирования. Для экранирования текста используйте метод класса escape() вместо этого.

>>> Markup('Hello, <em>World</em>!')
Markup('Hello, <em>World</em>!')
>>> Markup(42)
Markup('42')
>>> Markup.escape('Hello, <em>World</em>!')
Markup('Hello &lt;em&gt;World&lt;/em&gt;!')

Это реализует интерфейс __html__(), который используют некоторые фреймворки. Передача объекта, реализующего __html__(), обернёт вывод этого метода, помечая его как безопасный.

>>> class Foo:
...     def __html__(self):
...         return '<a href="/foo">foo</a>'
...
>>> Markup(Foo())
Markup('<a href="/foo">foo</a>')

Это подкласс типа text (str в Python 3, unicode в Python 2). Он имеет те же методы, что и этот тип, но все методы экранируют свои аргументы и возвращают экземпляр Markup.

>>> Markup('<em>%s</em>') % 'foo & bar'
Markup('<em>foo &amp; bar</em>')
>>> Markup('<em>Hello</em> ') + '<foo>'
Markup('<em>Hello</em> &lt;foo&gt;')

classmethod escape(s)

Экранировать строку. Вызывает escape() и гарантирует, что для подклассов возвращается правильный тип.

striptags()

Разобрать разметку, удалить теги и нормализовать пробелы до одиночных пробелов.

>>> Markup('Main &raquo;        <em>About</em>').striptags()
'Main » About'

unescape()

Преобразовать экранированную разметку обратно в строку текста. Это заменяет HTML-сущности соответствующими символами.

>>> Markup('Main &raquo; <em>About</em>').unescape()
'Main » <em>About</em>'

Исключения

exception jinja2.TemplateError(message=None)

Базовый класс для всех ошибок шаблонов.

exception jinja2.UndefinedError(message=None)

Вызывается, если шаблон пытается выполнить операцию над Undefined.

exception jinja2.TemplateNotFound(name, message=None)

Вызывается, если шаблон не существует.

Изменено в версии 2.11: Если заданное имя равно Undefined, и сообщение не было предоставлено, генерируется исключение UndefinedError.

exception jinja2.TemplatesNotFound(names=(), message=None)

Подобно TemplateNotFound, но вызывается, если выбрано несколько шаблонов. Это подкласс исключения TemplateNotFound, поэтому перехват базового исключения перехватывает оба.

Изменено в версии 2.11: Если имя в списке имён равно Undefined, отображается сообщение об этом, а не пустая строка.

Изменения

Новое в версии 2.2.

exception jinja2.TemplateSyntaxError(message, lineno, name=None, filename=None)

Вызывается, чтобы сообщить пользователю о проблеме с шаблоном.

message

Сообщение об ошибке в виде байтовой строки utf-8.

lineno

Номер строки, где произошла ошибка

name

Имя загружаемого шаблона в виде строки unicode.

filename

Имя файла, загрузившего шаблон, в виде байтовой строки в кодировке файловой системы (вероятно, utf-8 или mbcs в системах Windows).

Причина, по которой имя файла и сообщение об ошибке являются байтовыми строками, а не строками unicode, заключается в том, что Python 2.x не использует unicode для исключений и трассировок, а также для компилятора. Это изменится с Python 3.

exception jinja2.TemplateRuntimeError(message=None)

Общая ошибка выполнения в движке шаблонов. В некоторых ситуациях Jinja может вызвать это исключение.

exception jinja2.TemplateAssertionError(message, lineno, name=None, filename=None)

Подобно ошибке синтаксиса шаблона, но охватывает случаи, когда что-то в шаблоне вызвало ошибку во время компиляции, которая не обязательно была вызвана синтаксической ошибкой. Однако это непосредственный подкласс TemplateSyntaxError и имеет те же атрибуты.

Настройка фильтров

Пользовательские фильтры — это обычные функции Python, которые принимают левую часть фильтра в качестве первого аргумента и аргументы, переданные фильтру, в качестве дополнительных аргументов или аргументов ключевых слов.

Например, в фильтре {{ 42|myfilter(23) }} функция вызывалась бы с myfilter(42, 23). Вот, например, простой фильтр, который может применяться к объектам datetime для форматирования их:

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

Вы можете зарегистрировать его в среде шаблонов, обновив словарь filters в среде:

environment.filters['datetimeformat'] = datetimeformat

Внутри шаблона он может использоваться следующим образом:

written on: {{ article.pub_date|datetimeformat }}
publication date: {{ article.pub_date|datetimeformat('%d-%m-%Y') }}

Фильтры также могут получать текущий контекст шаблона или среду. Это полезно, если фильтр хочет вернуть неопределенное значение или проверить текущую настройку autoescape. Для этой цели существуют три декоратора: environmentfilter(), contextfilter() и evalcontextfilter().

Вот небольшой пример фильтра, который разбивает текст на HTML-строки разрыва и абзацы, и помечает возвращаемое значение как безопасную HTML-строку, если включено автоматическое экранирование:

import re
from jinja2 import evalcontextfilter
from markupsafe import Markup, escape

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

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

Контекстные фильтры работают аналогично, только первый аргумент — это текущий активный Context вместо среды.

Контекст вычисления

Контекст вычисления (кратко контекст вычисления или контекст ctx) — новый объект, введённый в Jinja 2.4, который позволяет активировать и деактивировать скомпилированные функции во время выполнения.

В настоящее время он используется только для включения и выключения автоматического экранирования, но может использоваться и для расширений.

В предыдущих версиях Jinja фильтры и функции помечались как вызываемые в среде, чтобы проверить состояние autoescape из среды. В новых версиях рекомендуется проверять настройку из контекста вычисления вместо этого.

Предыдущие версии:

@environmentfilter
def filter(env, value):
    result = do_something(value)
    if env.autoescape:
        result = Markup(result)
    return result

В новых версиях вы можете использовать contextfilter() и получить доступ к контексту вычисления из фактического контекста или использовать evalcontextfilter(), который напрямую передаёт контекст вычисления функции:

@contextfilter
def filter(context, value):
    result = do_something(value)
    if context.eval_ctx.autoescape:
        result = Markup(result)
    return result

@evalcontextfilter
def filter(eval_ctx, value):
    result = do_something(value)
    if eval_ctx.autoescape:
        result = Markup(result)
    return result

Контекст вычисления не должен изменяться во время выполнения. Изменения должны происходить только с помощью nodes.EvalContextModifier и nodes.ScopedEvalContextModifier из расширения, а не на самом объекте контекста вычисления.

class jinja2.nodes.EvalContext(environment, template_name=None)

Содержит информацию о времени вычисления. Дополнительные атрибуты могут быть добавлены к нему в расширениях.

autoescape

True или False в зависимости от того, активен ли автоэкранирование или нет.

volatile

True если компилятор не может оценить некоторые выражения во время компиляции. Во время выполнения это всегда должно быть False.

Настройка тестов

Тесты работают как фильтры, только тесты не имеют возможности получить доступ к среде или контексту и не могут быть объединены. Возвращаемое значение теста должно быть True или False. Цель теста — предоставить разработчикам шаблонов возможность выполнять проверки типа и соответствия.

Вот простой тест, проверяющий, является ли переменная простым числом:

import math

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

Вы можете зарегистрировать его в среде шаблонов, обновив словарь tests в среде:

environment.tests['prime'] = is_prime

Разработчик шаблона может использовать тест следующим образом:

{% if 42 is prime %}
    42 is a prime number
{% else %}
    42 is not a prime number
{% endif %}

Глобальное пространство имен

Переменные, хранящиеся в словаре Environment.globals, являются специальными, так как они также доступны для импортированных шаблонов, даже если они импортируются без контекста. Это место, где можно поместить переменные и функции, которые должны быть доступны постоянно. Кроме того, существуют Template.globals, являющиеся переменными, доступными для конкретного шаблона, которые доступны всем вызовам render().

API низкого уровня

API низкого уровня предоставляет функциональность, которая может быть полезна для понимания некоторых деталей реализации, отладки или продвинутых методов расширений. Если вы не знаете точно, что делаете, мы не рекомендуем использовать ни один из них.

Environment.lex(source, name=None, filename=None)

Проанализируйте заданный исходный код и верните генератор, который возвращает токены в виде кортежей в формате (lineno, token_type, value). Это может быть полезно для разработки расширений и отладки шаблонов.

Эта функция не выполняет предобработку. Если вы хотите применить предобработку расширений, необходимо отфильтровать исходный код через метод preprocess().

Environment.parse(source, name=None, filename=None)

Проанализируйте исходный код и верните абстрактное синтаксическое дерево. Это дерево узлов используется компилятором для преобразования шаблона в исполняемый исходный или байткод. Это полезно для отладки или извлечения информации из шаблонов.

Если вы разрабатываете расширения Jinja, это даст вам хорошее представление о генерируемом дереве узлов.

Environment.preprocess(source, name=None, filename=None)

Предварительно обрабатывает исходный код с помощью всех расширений. Это автоматически вызывается для всех методов разбора и компиляции, но не для lex(), так как там обычно требуется только токенизация фактического исходного кода.

Template.new_context(vars=None, shared=False, locals=None)

Создайте новый Context для этого шаблона. Переданные переменные будут переданы в шаблон. По умолчанию глобальные переменные добавляются в контекст. Если shared установлено в значение True, данные передаются в контекст как есть без добавления глобальных переменных.

locals может быть словарем локальных переменных для внутреннего использования.

Template.root_render_func(context)

Это функция рендеринга низкого уровня. Ей передаётся Context , которая должна быть создана с помощью new_context() того же шаблона или совместимого шаблона. Эта функция рендеринга генерируется компилятором из кода шаблона и возвращает генератор, который возвращает строки Unicode.

Если в коде шаблона произойдёт исключение, движок шаблонов не перепишет исключение, а передаст исходное. Фактически, эта функция должна вызываться только из вызова render() / generate() / stream().

Template.blocks

Словарь функций рендеринга блоков. Каждая из этих функций работает точно так же, как root_render_func() с теми же ограничениями.

Template.is_up_to_date

Это свойство False , если доступна более новая версия шаблона, в противном случае True.

Мета-API

Мета-API возвращает некоторую информацию об абстрактных синтаксических деревьях, которая может помочь приложениям реализовать более сложные концепции шаблонов. Все функции мета-API работают с абстрактным синтаксическим деревом, возвращаемым методом Environment.parse().

jinja2.meta.find_undeclared_variables(ast)

Возвращает множество всех переменных в AST, которые будут извлекаться из контекста во время выполнения. Поскольку на этапе компиляции неизвестно, какие переменные будут использоваться в зависимости от пути выполнения во время выполнения, возвращаются все переменные.

>>> from jinja2 import Environment, meta
>>> env = Environment()
>>> ast = env.parse('{% set foo = 42 %}{{ bar + foo }}')
>>> meta.find_undeclared_variables(ast) == set(['bar'])
True

Реализация

Внутренне для поиска не объявленных переменных используется генератор кода. Это полезно знать, потому что генератор кода может вызывать TemplateAssertionError во время компиляции, и, фактически, эта функция также может вызвать это исключение.

jinja2.meta.find_referenced_templates(ast)

Находит все ссылающиеся на шаблоны в AST. Это вернёт итератор по всем жёстко закодированным расширениям шаблонов, включениям и импортам. Если используются динамическое наследование или включение, None будет возвращено.

>>> from jinja2 import Environment, meta
>>> env = Environment()
>>> ast = env.parse('{% extends "layout.html" %}{% include helper %}')
>>> list(meta.find_referenced_templates(ast))
['layout.html', None]

Эта функция полезна для отслеживания зависимостей. Например, если вы хотите перестроить части сайта после изменения шаблона макета.