API

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

Основы

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

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

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

from jinja2 import Environment, PackageLoader, select_autoescape
env = Environment(
    loader=PackageLoader("yourapp"),
    autoescape=select_autoescape()
)

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

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

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

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

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

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

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

Примечания об автоматической экранировке

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

Высокоуровневый API

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

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

Новое в версии 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

Новое в версии 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: Размер кэша был увеличен до 400 с 50.

auto_reload

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

bytecode_cache

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

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

enable_async

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

Parameters:

block_start_string (str) –
block_end_string (str) –
variable_start_string (str) –
variable_end_string (str) –
comment_start_string (str) –
comment_end_string (str) –
line_statement_prefix (str | None) –
line_comment_prefix (str | None) –
trim_blocks (bool) –
lstrip_blocks (bool) –
newline_sequence (te.Literal['\n', '\r\n', '\r']) –
keep_trailing_newline (bool) –
extensions (Sequence[str | Type[Extension]]) –
optimized (bool) –
undefined (Type[Undefined]) –
finalize (Callable[[...], Any] | None) –
autoescape (bool | Callable[[str | None], bool]) –
loader (BaseLoader | None) –
cache_size (int) –
auto_reload (bool) –
bytecode_cache (BytecodeCache | None) –
enable_async (bool) –

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

sandboxed: Если среда изолирована, этот атрибут True. Для режима изоляции обратитесь к документации для SandboxedEnvironment.

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

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

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

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

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

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

overlay([options])

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

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

Изменено в версии 3.1.2: Добавлены параметры newline_sequence,, keep_trailing_newline, и enable_async для соответствия __init__.

Параметры:

block_start_string (str) –
block_end_string (str) –
variable_start_string (str) –
variable_end_string (str) –
comment_start_string (str) –
comment_end_string (str) –
line_statement_prefix (str | None) –
line_comment_prefix (str | None) –
trim_blocks (bool) –
lstrip_blocks (bool) –
newline_sequence (te.Literal['\n', '\r\n', '\r']) –
keep_trailing_newline (bool) –
extensions (Sequence[str | Type[Extension]]) –
optimized (bool) –
undefined (Type[Undefined]) –
finalize (Callable[[...], Any] | None) –
autoescape (bool | Callable[[str | None], bool]) –
loader (BaseLoader | None) –
cache_size (int) –
auto_reload (bool) –
bytecode_cache (BytecodeCache | None) –
enable_async (bool) –

Тип возвращаемого значения:

Environment

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)

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

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

Новая версия с 2.5.

Параметры:: extension (str | Type[Extension]) –
Тип возвращаемого значения:: None

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

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

Новая версия с 2.1.

Параметры:

source (str) –
undefined_to_none (bool) –

Тип возвращаемого значения:

TemplateExpression

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

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

Чтобы переключиться на сохранённый алгоритм, zip можно установить в 'stored'.

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

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

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

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

Параметры:

target (str | PathLike) –
extensions (Collection[str] | None) –
filter_func (Callable[[str], bool] | None) –
zip (str | None) –
log_function (Callable[[str], None] | None) –
ignore_errors (bool) –

Тип возвращаемого значения:

None

extend(**attributes)

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

Параметры:: attributes (Any) –
Тип возвращаемого значения:: None

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

Загружает шаблон из строки исходного кода без использования loader.

Параметры:

source (str | Template) – Исходный код Jinja для компиляции в шаблон.
globals (MutableMapping[str, Any] | None) – Расширяет среду globals дополнительными переменными, доступными для всех рендерингов этого шаблона. Если шаблон уже загружен и кэширован, его глобальные переменные обновляются любыми новыми элементами.
template_class (Type[Template] | None) – Возвращает экземпляр этого класса Template.

Тип возвращаемого значения:

Template

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

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

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

Новая версия с 2.3.

Параметры:

template_name_or_list (str | Template | List[str | Template]) –
parent (str | None) –
globals (MutableMapping[str, Any] | None) –

Тип возвращаемого значения:

Template

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

Загрузить шаблон по имени с loader и вернуть Template. Если шаблон не существует, возникает исключение TemplateNotFound.

Параметры:

name (str | Шаблон) – Имя загружаемого шаблона. При загрузке шаблонов из файловой системы используется «/» в качестве разделителя путей, даже в Windows.
parent (str | None) – Имя родительского шаблона, импортирующего этот шаблон. join_path() можно использовать для реализации преобразований имён.
globals (MutableMapping[str, Any] | None) – Расширяет globals среды дополнительными переменными, доступными для всех рендерингов этого шаблона. Если шаблон уже загружен и кэширован, его значения globals обновляются любыми новыми элементами.

Тип возвращаемого значения:

Шаблон

Изменения

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

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

join_path(template, parent)

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

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

Параметры:

template (str) –
parent (str) –

Тип возвращаемого значения:

str

list_templates(extensions=None, filter_func=None)

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

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

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

Изменения

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

Параметры:

extensions (Collection[str] | None) –
filter_func (Callable[[str], bool] | None) –

Тип возвращаемого значения:

Список[str]

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

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

Параметры:

names (Итерируемый[str | Шаблон]) – Список имён шаблонов для попытки загрузки в порядке.
parent (str | None) – Имя родительского шаблона, импортирующего этот шаблон. join_path() можно использовать для реализации преобразований имён.
globals (MutableMapping[str, Any] | None) – Расширяет globals среды дополнительными переменными, доступными для всех рендерингов этого шаблона. Если шаблон уже загружен и кэширован, его значения globals обновляются любыми новыми элементами.

Тип возвращаемого значения:

Шаблон

Изменения

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

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

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

class jinja2.Template(source, block_start_string='{%', block_end_string='%}', variable_start_string='{{', variable_end_string='}}', comment_start_string='{#', comment_end_string='#}', line_statement_prefix=None, line_comment_prefix=None, trim_blocks=False, lstrip_blocks=False, newline_sequence='\n', keep_trailing_newline=False, extensions=(), optimized=True, undefined=<class 'jinja2.runtime.Undefined'>, finalize=None, autoescape=False, enable_async=False)

Скомпилированная шаблон, которую можно отобразить.

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

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

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

Параметры:

source (str | Template) –
block_start_string (str) –
block_end_string (str) –
variable_start_string (str) –
variable_end_string (str) –
comment_start_string (str) –
comment_end_string (str) –
line_statement_prefix (str | None) –
line_comment_prefix (str | None) –
trim_blocks (bool) –
lstrip_blocks (bool) –
newline_sequence (te.Literal['\n', '\r\n', '\r']) –
keep_trailing_newline (bool) –
extensions (Sequence[str | Type[Extension]]) –
optimized (bool) –
undefined (Type[Undefined]) –
finalize (Callable[[...], Any] | None) –
autoescape (bool | Callable[[str | None], bool]) –
enable_async (bool) –

Тип возвращаемого значения:

Any

globals

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

По умолчанию Environment.globals, если дополнительные значения не переданы в Environment.get_template().

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

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

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

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

render([context])

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

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

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

Параметры:

args (Any) –
kwargs (Any) –

Тип возвращаемого значения:

str

generate([context])

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

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

Параметры:

args (Any) –
kwargs (Any) –

Тип возвращаемого значения:

Iterator[str]

stream([context])

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

Параметры:

args (Any) –
kwargs (Any) –

Тип возвращаемого значения:

TemplateStream

async render_async([context])

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

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

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

Параметры:

args (Any) –
kwargs (Any) –

Тип возвращаемого значения:

str

async generate_async([context])

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

Параметры:

args (Any) –
kwargs (Any) –

Тип возвращаемого значения:

AsyncIterator[str]

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

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

Параметры:

vars (Dict[str, Any] | None) –
shared (bool) –
locals (Mapping[str, Any] | None) –

Тип возвращаемого значения:

TemplateModule

property module: TemplateModule

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

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

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

class jinja2.environment.TemplateStream

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

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

Параметры:: gen (Iterator[str]) –

disable_buffering()

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

Тип возвращаемого значения:: None

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

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

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

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

Параметры:

fp (str | IO) –
encoding (str | None) –
errors (str | None) –

Тип возвращаемого значения:

None

enable_buffering(size=5)

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

Параметры:: size (int) –
Тип возвращаемого значения:: None

END_OF_DOCUMENT_MARKER

Автовывод HTML-кода

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

Изменено в версии 2.4.

Jinja теперь поддерживает автоматический вывод HTML-кода. Начиная с Jinja 2.9, расширение автовывода включено по умолчанию. Тем не менее, автовывод по умолчанию пока не включён, хотя это, скорее всего, изменится в будущем. Рекомендуется настроить разумное значение по умолчанию для автовывода. Это позволяет включать и отключать автовывод на уровне каждой шаблона (например, 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.

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

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

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

Параметры:

enabled_extensions (Collection[str]) –
disabled_extensions (Collection[str]) –
default_for_string (bool) –
default (bool) –

Тип возвращаемого значения:

Callable[[str | None], bool]

Вот рекомендуемая настройка, которая включает автовывод для шаблонов, заканчивающихся на '.html', '.htm' и '.xml', и отключает его по умолчанию для всех других расширений. Вы можете использовать функцию select_autoescape() для этого:

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

Функция select_autoescape() возвращает функцию, которая работает примерно так:

def autoescape(template_name):
    if template_name is None:
        return False
    if template_name.endswith(('.html', '.htm', '.xml'))

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

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

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

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

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

Типы неопределённых значений

Эти классы могут использоваться как типы неопределённых значений. Конструктор 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

Параметры:

hint (str | None) –
obj (Any) –
name (str | None) –
exc (Type[TemplateRuntimeError]) –

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

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

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

_undefined_exception: Исключение, которое неопределённый объект хочет вызвать. Обычно это один из UndefinedError или SecurityError.

_fail_with_undefined_error(\*args, \**kwargs): При вызове с любыми аргументами этот метод вызывает _undefined_exception с сообщением об ошибке, сгенерированным из данных о неопределённости, хранящихся в неопределённом объекте.

class jinja2.ChainableUndefined

Неопределённое значение, которое можно использовать в цепочке, где оба __getattr__ и __getitem__ возвращают себя вместо того, чтобы генерировать UndefinedError.

>>> foo = ChainableUndefined(name='foo')
>>> str(foo.bar['baz'])
''
>>> foo.bar['baz'] + 42
Traceback (most recent call last):
  ...
jinja2.exceptions.UndefinedError: 'foo' is undefined

Изменения

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

Параметры:

hint (str | None) –
obj (Any) –
name (str | None) –
exc (Type[TemplateRuntimeError]) –

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

Параметры:

hint (str | None) –
obj (Any) –
name (str | None) –
exc (Type[TemplateRuntimeError]) –

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

Параметры:

hint (str | None) –
obj (Any) –
name (str | None) –
exc (Type[TemplateRuntimeError]) –

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

jinja2.make_logging_undefined(logger=None, base=<class 'jinja2.runtime.Undefined'>)

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

Пример:

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

Изменения

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

Параметры:

logger (logging.Logger | None) – логгер для использования. Если не указан, создаётся логгер по умолчанию.
base (Type[Undefined]) – базовый класс, к которому добавляется функциональность логгирования. По умолчанию это Undefined.

Тип возвращаемого значения:

Type[Undefined]

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

Реализация

Undefined реализовано путём переопределения специальных методов __underscore__. Например, базовый класс Undefined реализует __str__, чтобы возвращать пустую строку, в то время как __int__ и другие методы генерируют исключение. Чтобы разрешить преобразование в целое число путём возвращения 0, можно реализовать свой собственный подкласс.

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

    def __float__(self):
        return 0.0

Для запрета метода переопределите его и вызовите _undefined_exception. Поскольку это очень распространено, существует вспомогательный метод _fail_with_undefined_error(), который вызывает ошибку с правильной информацией. Вот класс, который работает как стандартный Undefined, но генерирует ошибку при итерировании:

class NonIterableUndefined(Undefined):
    def __iter__(self):
        self._fail_with_undefined_error()

END_OF_DOCUMENT_MARKER

Контекст

class jinja2.runtime.Context

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

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

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

Параметры:

environment (Environment) –
parent (Dict[str, Any]) –
name (str | None) –
blocks (Dict[str, Callable[[Context], Iterator[str]]]) –
globals (MutableMapping[str, Any] | None) –

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

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

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

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

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

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

eval_ctx: Текущий Контекст Оценивания.

call(callable, \*args, \**kwargs)

Вызывает вызываемую функцию с предоставленными аргументами и именованными аргументами, но вставляет активный контекст или среду в качестве первого аргумента, если вызываемая функция имеет pass_context() или pass_environment().

Параметры:

_Context__obj (Callable) –
args (Any) –
kwargs (Any) –

Тип возвращаемого значения:

Any | Undefined

get(key, default=None)

Ищет переменную по имени или возвращает значение по умолчанию, если ключ не найден.

Параметры:

key (str) – Имя переменной для поиска.
default (Any | None) – Возвращаемое значение, если ключ не найден.

Тип возвращаемого значения:

Any

get_all()

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

Тип возвращаемого значения:: Dict[str, Any]

get_exported()

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

Тип возвращаемого значения:: Dict[str, Any]

resolve(key)

Ищет переменную по имени или возвращает объект Undefined, если ключ не найден.

Если вам нужно добавить пользовательское поведение, переопределите resolve_or_missing(), а не этот метод. Различные функции поиска используют этот метод, а не этот.

Параметры:: key (str) – Имя переменной для поиска.
Тип возвращаемого значения:: Any | Undefined

END_OF_DOCUMENT_MARKER

resolve_or_missing(key)

Искать переменную по имени или возвращать missing метку, если ключ не найден.

Переопределите этот метод, чтобы добавить пользовательское поведение поиска. resolve(), get() и __getitem__() используют этот метод. Не вызывайте этот метод напрямую.

Параметры:: key (str) – Имя переменной для поиска.
Тип возвращаемого значения:: Any

Контекст неизменяемый, он предотвращает изменения, и если он каким-то образом изменяется, эти изменения могут не отобразиться. Для повышения производительности Jinja не использует контекст для хранения данных, только в качестве основного источника данных. Переменные, не определённые шаблоном, ищутся в контексте, но переменные, определённые шаблоном, хранятся локально.

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

{% set comments = get_latest_comments() %}

Загрузчики

Загрузчики отвечают за загрузку шаблонов из ресурсов, таких как файловая система. Среда будет хранить скомпилированные модули в памяти, как в Python’s 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 open(path) as f:
            source = f.read()
        return source, path, lambda: mtime == getmtime(path)

get_source(environment, template)

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

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

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

Параметры:

environment (Среда) –
template (строка) –

Тип возвращаемого значения:

Кортеж[строка, строка | None, Вызываемый объект[[], логическое значение] | None]

load(environment, name, globals=None)

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

Параметры:

environment (Среда) –
name (строка) –
globals (Изменяемое отображение[строка, любой тип] | None) –

Тип возвращаемого значения:

Шаблон

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

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

Загружает шаблоны из каталога в файловой системе.

Путь может быть относительным или абсолютным. Относительные пути относительны к текущей рабочей директории.

loader = FileSystemLoader("templates")

Можно указать список путей. Директории будут перебираться в указанном порядке, останавливаясь на первом совпавшем шаблоне.

loader = FileSystemLoader(["/override/templates", "/default/templates"])

Параметры:

searchpath (строка | PathLike | Последовательность[строка | PathLike]) – Путь или список путей к каталогу, содержащему шаблоны.
encoding (строка) – Использовать этот кодировку для чтения текста из файлов шаблонов.
followlinks (булево значение) – Следовать символическим ссылкам в пути.

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

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

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

Загружает шаблоны из каталога в пакете Python.

Параметры:

package_name (строка) – Имя импорта пакета, содержащего каталог шаблонов.
package_path (строка) – Каталог внутри импортированного пакета, содержащий шаблоны.
encoding (строка) – Кодировка файлов шаблонов.

Следующий пример ищет шаблоны в каталоге pages внутри пакета project.ui.

loader = PackageLoader("project.ui", "pages")

Поддерживаются только пакеты, установленные как каталоги (стандартное поведение pip) или zip/egg-файлы (менее распространённый случай). API Python для интроспекции данных в пакетах слишком ограничен, чтобы поддерживать другие методы установки таким образом, как требуется этому загрузчику.

Ограниченная поддержка пространств имён пакетов PEP 420. Предполагается, что каталог шаблонов находится только в одном участнике пространства имён. Zip-архивы, вносящие вклад в пространство имён, не поддерживаются.

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

Изменено в версии 3.0: Больше не использует setuptools в качестве зависимости.

Изменено в версии 3.0: Ограниченная поддержка пространств имён пакетов PEP 420.

class jinja2.DictLoader(mapping)

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

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

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

Параметры:: mapping (Отображение[строка, строка]) –

END_OF_DOCUMENT_MARKER

class jinja2.FunctionLoader(load_func)

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

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

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

Параметры:: load_func (Callable[[str], str | Tuple[str, str | None, Callable[[], bool] | None] | None]) –

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

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

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

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

Параметры:

mapping (Mapping[str, BaseLoader]) –
delimiter (str) –

class jinja2.ChoiceLoader(loaders)

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

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

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

Параметры:: loaders (Sequence[BaseLoader]) –

class jinja2.ModuleLoader(path)

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

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

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

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

Параметры:: path (str | PathLike | Sequence[str | PathLike]) –

Кэш байткода

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, но должен быть реализован, чтобы позволить приложениям очищать кэш байткода, используемый конкретной средой.

Тип возвращаемого значения:: None

dump_bytecode(bucket)

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

Параметры:: bucket (Ведро) –
Тип возвращаемого значения:: None

load_bytecode(bucket)

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

Параметры:: bucket (Ведро) –
Тип возвращаемого значения:: None

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

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

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

Параметры:

environment (Environment) –
key (str) –
checksum (str) –

environment: Environment , создавшая ведро.

key: Уникальный ключ кэша для этого ведра

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

bytecode_from_string(string)

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

Параметры:: string (bytes) –
Тип возвращаемого значения:: None

bytecode_to_string()

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

Тип возвращаемого значения:: bytes

load_bytecode(f)

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

Параметры:: f (BinaryIO) –
Тип возвращаемого значения:: None

reset()

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

Тип возвращаемого значения:: None

write_bytecode(f)

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

Параметры:: f (IO[bytes]) –
Тип возвращаемого значения:: None

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

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

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

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

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

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

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

Параметры:

directory (str | None) –
pattern (str) –

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

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

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

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

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

Параметры:

client (_MemcachedClient) –
prefix (строка) –
timeout (целое число | None) –
ignore_memcache_errors (bool) –

class MinimalClientInterface

set(key, value[, timeout]): Хранит байт-код в кэше. value — это строка, а timeout — тайм-аут ключа. Если тайм-аут не указан, предполагается значение по умолчанию или отсутствие тайм-аута. Если он указан, это целое число, обозначающее количество секунд, в течение которых элемент кэша должен существовать.

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

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

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

Изменения

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

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

Изменения

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

Jinja поддерживает синтаксис Python async и await. Для разработчика шаблонов эта поддержка (при включении) полностью прозрачна, шаблоны выглядят точно так же. Однако разработчики должны учитывать реализацию, так как это влияет на типы API, которые вы можете использовать.

По умолчанию поддержка асинхронных операций отключена. Ее включение заставит окружение скомпилировать другой код за кулисами для обработки асинхронного и синхронного кода в цикле событий asyncio. Это имеет следующие последствия:

Для рендеринга шаблонов требуется наличие цикла событий в текущей нити. asyncio.get_running_loop() должен возвращать цикл событий.
Скомпилированный код использует await для функций и атрибутов и использует async for циклы. Чтобы поддерживать использование как асинхронных, так и синхронных функций в этом контексте, вокруг всех вызовов и обращений размещается небольшой обертка, что увеличивает накладные расходы по сравнению с чисто асинхронным кодом.
Синхронные методы и фильтры становятся обертками вокруг соответствующих асинхронных реализаций, где это необходимо. Например, render вызывает async_render, а |map поддерживает асинхронные итерируемые объекты.

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

Политики

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

Пример:

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

truncate.leeway:: Настраивает значение leeway по умолчанию для фильтра truncate. Leeway был введён в версии 2.9, но для сохранения совместимости со старыми шаблонами, он может быть настроен на 0 для возвращения старого поведения. По умолчанию значение равно 5.
urlize.rel:: Строка, определяющая элементы для атрибута rel сгенерированных ссылок с фильтром urlize. Эти элементы всегда добавляются. По умолчанию значение равно noopener.
urlize.target:: Целевой адрес по умолчанию, который используется для ссылок из фильтра urlize при отсутствии явного определения другого адреса в вызове.
urlize.extra_schemes:: Распознаёт URL-адреса, начинающиеся со схем, помимо стандартных http://, https://, и mailto:.
json.dumps_function:: Если это значение не равно None, то фильтр tojson выведет данные с помощью этой функции вместо стандартной. Обратите внимание, что эта функция должна принимать произвольные дополнительные аргументы, которые могут быть переданы в будущем фильтром. В настоящее время единственным аргументом, который может быть передан, является indent. По умолчанию используется функция json.dumps.
json.dumps_kwargs:: Ключевые аргументы, которые должны быть переданы функции вывода. По умолчанию значение равно ext.i18n.trimmed:.

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

Утилиты

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

jinja2.pass_context(f)

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

Может быть использован для функций, фильтров и тестов.

Если нужен только Context.eval_context, используйте pass_eval_context(). Если нужен только Context.environment, используйте pass_environment().

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

Введено в версии 3.0.0: Заменяет contextfunction и contextfilter.

Параметры:: f (F) –
Тип возвращаемого значения:: F

jinja2.pass_eval_context(f)

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

Может быть использован для функций, фильтров и тестов.

Если нужен только EvalContext.environment, используйте pass_environment().

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

Введено в версии 3.0.0: Заменяет evalcontextfunction и evalcontextfilter.

Параметры:: f (F) –
Тип возвращаемого значения:: F

jinja2.pass_environment(f)

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

Может быть использован для функций, фильтров и тестов.

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

Введено в версии 3.0.0: Заменяет environmentfunction и environmentfilter.

Параметры:: f (F) –
Тип возвращаемого значения:: F

jinja2.clear_caches()

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

Тип возвращаемого значения:: None

jinja2.is_undefined(obj)

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

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

Параметры:: obj (Any) –
Тип возвращаемого значения:: bool

Исключения

exception jinja2.TemplateError(message=None)

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

Параметры:: message (str | None) –
Тип возвращаемого значения:: None

exception jinja2.UndefinedError(message=None)

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

Параметры:: message (str | None) –
Тип возвращаемого значения:: None

exception jinja2.TemplateNotFound(name, message=None)

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

Изменения

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

Параметры:

name (str | Undefined | None) –
message (str | None) –

Тип возвращаемого значения:

None

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

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

Изменения

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

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

Параметры:

names (Sequence[str | Undefined]) –
message (str | None) –

Тип возвращаемого значения:

None

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

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

Параметры:

message (str) –
lineno (int) –
name (str | None) –
filename (str | None) –

Тип возвращаемого значения:

None

message: Сообщение об ошибке.

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

name: Имя загруженного шаблона.

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

exception jinja2.TemplateRuntimeError(message=None)

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

Параметры:: message (str | None) –
Тип возвращаемого значения:: None

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

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

Параметры:

message (str) –
lineno (int) –
name (str | None) –
filename (str | None) –

Тип возвращаемого значения:

None

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

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

Например, фильтр {{ 42|myfilter(23) }} вызывается в фоновом режиме как myfilter(42, 23).

Jinja поставляется с некоторыми встроенными фильтрами. Чтобы использовать пользовательский фильтр, напишите функцию, которая принимает как минимум value аргумент, а затем зарегистрируйте ее в Environment.filters.

Вот фильтр, форматирующий объекты datetime:

def datetime_format(value, format="%H:%M %d-%m-%y"):
    return value.strftime(format)

environment.filters["datetime_format"] = datetime_format

Теперь он может использоваться в шаблонах:

{{ article.pub_date|datetimeformat }}
{{ article.pub_date|datetimeformat("%B %Y") }}

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

pass_environment() передаёт Environment.
pass_eval_context() передаёт Контекст оценки.
pass_context() передаёт текущий Context.

Вот фильтр, который преобразует переводы строк в HTML-теги <br> и <p>. Он использует контекст оценки, чтобы проверить, включен ли автоэскейп, прежде чем экранировать ввод и отметить вывод как безопасный.

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

@pass_eval_context
def nl2br(eval_ctx, value):
    br = "<br>\n"

    if eval_ctx.autoescape:
        value = escape(value)
        br = Markup(br)

    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 autoescape else result

Пользовательские тесты

Тесты — это функции Python, которые принимают значение слева от теста в качестве первого аргумента и возвращают True или False. Аргументы, передаваемые в тест, передаются после значения.

Например, тест {{ 42 is even }} вызывается за кулисами как is_even(42).

Jinja поставляется с некоторыми встроенными тестами. Чтобы использовать пользовательские тесты, напишите функцию, которая принимает по крайней мере один аргумент value, а затем зарегистрируйте её в Environment.tests.

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

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

environment.tests["prime"] = is_prime

Теперь его можно использовать в шаблонах:

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

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

pass_environment() передаёт Environment.
pass_eval_context() передаёт Контекст вычисления.
pass_context() передаёт текущий Context.

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

Контекст вычисления (сокращённо контекст вычисл. или ctx) позволяет активировать и деактивировать скомпилированные функции во время выполнения.

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

Настройка autoescape должна проверяться в контексте вычисления, а не в среде. Контекст вычисления будет содержать вычисленное значение для текущего шаблона.

Вместо pass_environment:

@pass_environment
def filter(env, value):
    result = do_something(value)

    if env.autoescape:
        result = Markup(result)

    return result

Используйте pass_eval_context если вам нужен только параметр:

@pass_eval_context
def filter(eval_ctx, value):
    result = do_something(value)

    if eval_ctx.autoescape:
        result = Markup(result)

    return result

Или используйте pass_context если вам необходимо также и другое поведение контекста:

@pass_context
def filter(context, value):
    result = do_something(value)

    if context.eval_ctx.autoescape:
        result = Markup(result)

    return result

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

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

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

Параметры:

environment (Environment) –
template_name (str | None) –

autoescape: True или False в зависимости от того, включена ли автоматическая экранизация.

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

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

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

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

Во время любого конкретного рендеринга используется только один набор глобальных переменных. Если шаблоны A и B оба имеют глобальные переменные шаблона, и B расширяет A, то только глобальные переменные B используются для обоих при использовании b.render().

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

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

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

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

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

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

Параметры:

source (str) –
name (str | None) –
filename (str | None) –

Тип возвращаемого значения:

Iterator[Tuple[int, str, str]]

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

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

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

Параметры:

source (str) –
name (str | None) –
filename (str | None) –

Тип возвращаемого значения:

Template

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

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

Параметры:

source (str) –
name (str | None) –
filename (str | None) –

Тип возвращаемого значения:

str

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

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

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

Параметры:

vars (Dict[str, Any] | None) –
shared (bool) –
locals (Mapping[str, Any] | None) –

Тип возвращаемого значения:

Context

Template.root_render_func(context)

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

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

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

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

Примечание

API низкого уровня хрупкий. Будущие версии Jinja будут стараться не изменять его в несовместимом обратном порядке, но изменения в ядре Jinja могут проявиться. Например, если Jinja добавит новый узел AST в последующих версиях, он может быть возвращен методом parse().

API метаданных

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

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

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) == {'bar'}
True

Реализация

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

Параметры:: ast (Шаблон) –
Тип возвращаемого значения:: Множество[строка]

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]

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

Параметры:: ast (Шаблон) –
Тип возвращаемого значения:: Итератор[строка | None]