API

extend(**attributes)

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

Parameters: attributes (Any) –
Return type: None

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

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

Parameters

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

Return type

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

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

Changelog

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

Parameters

template_name_or_list (Union[str, jinja2.environment.Template, List[Union[str, jinja2.environment.Template]]]) –
parent (Optional[str]) –
globals (Optional[Mapping[str, Any]]) –

Return type

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

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

Параметры

name (Union[str, jinja2.environment.Template]) – Имя шаблона для загрузки.
parent (Optional[str]) – Имя родительского шаблона, импортирующего этот шаблон. join_path() можно использовать для реализации преобразований имён.
globals (Optional[Mapping[str, Any]]) – Расширьте среду globals с помощью этих дополнительных переменных, доступных для всех рендерингов этого шаблона. Если шаблон уже загружен и кэширован, его переменные глобального доступа обновляются новыми значениями.

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

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

Изменения

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

join_path(template, parent)

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

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

Параметры

template (str) –
parent (str) –

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

list_templates(extensions=None, filter_func=None)

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

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

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

Изменения

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

Параметры

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

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

Список[str]

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

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

Параметры

names (Iterable[Union[str, jinja2.environment.Template]]) – Список имён шаблонов, которые нужно попробовать загрузить в заданном порядке.
parent (Optional[str]) – Имя родительского шаблона, импортирующего этот шаблон. join_path() можно использовать для реализации преобразований имён.
globals (Optional[Mapping[str, Any]]) – Расширьте среду 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, который указывает на временную среду, которая, вероятно, используется совместно с другими шаблонами, созданными с помощью конструктора и совместимыми настройками.

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

Параметры

source (Union[str, jinja2.nodes.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 (Optional[str]) –
line_comment_prefix (Optional[str]) –
trim_blocks (bool) –
lstrip_blocks (bool) –
newline_sequence (te.Literal['\n', '\r\n', '\r']) –
keep_trailing_newline (bool) –
extensions (Sequence[Union[str, Type[Extension]]]) –
optimized (bool) –
undefined (Type[jinja2.runtime.Undefined]) –
finalize (Optional[Callable[[...], Any]]) –
autoescape (Union[bool, Callable[[Optional[str]], 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) –

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

jinja2.environment.TemplateStream

generate([context])

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

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

Параметры

args (Any) –
kwargs (Any) –

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

Iterator[str]

stream([context])

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

Параметры

args (Any) –
kwargs (Any) –

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

async render_async([context])

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

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

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

Параметры

args (Any) –
kwargs (Any) –

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

generate_async([context])

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

Параметры

args (Any) –
kwargs (Any) –

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

AsyncIterator[str]

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

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

Параметры

vars (Необязательный[Словарь[строка, любой тип]]) –
shared (булево значение) –
locals (Необязательный[отображение[строка, любой тип]]) –

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

jinja2.environment.TemplateModule

property module: jinja2.environment.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 (Итератор[строка]) –
Тип возвращаемого значения: None

disable_buffering()

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

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

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

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

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

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

Параметры

fp (Объединение[строка, IO]) –
encoding (Необязательный[строка]) –
errors (Необязательный[строка]) –

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

enable_buffering(size=5)

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

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

Автовывод

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

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

Jinja теперь поддерживает автоматический вывод. Начиная с 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 (Коллекция[строка]) –
disabled_extensions (Коллекция[строка]) –
default_for_string (булево значение) –
default (булево значение) –

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

Callable[[Optional[строка]], булево значение]

Вот рекомендуемая настройка, которая включает автоматический вывод для шаблонов, заканчивающихся '.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]) –
obj (Любой) –
name (Необязательно[str]) –
exc (Тип[jinja2.exceptions.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]) –
obj (Любой) –
name (Необязательно[str]) –
exc (Тип[jinja2.exceptions.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]) –
obj (Любой) –
name (Необязательно[str]) –
exc (Тип[jinja2.exceptions.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]) –
obj (Любой) –
name (Необязательно[str]) –
exc (Тип[jinja2.exceptions.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]) – используемый регистратор. Если не указан, создаётся стандартный.
base (Тип[jinja2.runtime.Undefined]) – базовый класс, к которому добавляется функциональность ведения журнала. По умолчанию Undefined.

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

Type[jinja2.runtime.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()

Контекст

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 (Optional[str]) –
blocks (Dict[str, Callable[[Context], Iterator[str]]]) –
globals (Optional[MutableMapping[str, Any]]) –

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

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

Union[Any, jinja2.runtime.Undefined]

get(key, default=None)

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

Параметры

key (str) – Имя переменной для поиска.
default (Optional[Any]) – Значение, которое нужно вернуть, если ключ не найден.

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

Any

get_all()

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

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

get_exported()

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

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

resolve(key)

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

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

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

resolve_or_missing(key)

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

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

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

Реализация

Контекст неизменяем по той же причине, что и локальные переменные кадра Python в функциях неизменяемы. Как Jinja, так и Python не используют контекст/локальные переменные фрейма в качестве хранилища переменных, а только в качестве основного источника данных.

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

END_OF_DOCUMENT_MARKER

Загрузчики

Загрузчики отвечают за загрузку шаблонов из ресурса, такого как файловая система. Среда будет хранить скомпилированные модули в памяти, как в 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 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 (строка) –

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

Кортеж[строка, Optional[строка], Optional[Callable[[], bool]]]

load(environment, name, globals=None)

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

Параметры

environment (Среда) –
name (строка) –
globals (Optional[MutableMapping[строка, любой]]) –

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

Шаблон

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

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

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

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

loader = FileSystemLoader("templates")

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

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

Параметры

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

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

Изменения

Изменено в версии 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 (Mapping[строка, строка]) –
Тип возвращаемого значения: None

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], Optional[Union[str, Tuple[str, Optional[str], Optional[Callable[[], bool]]]]]]) –
Тип возвращаемого значения: 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, jinja2.loaders.BaseLoader]) –
delimiter (str) –

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

class jinja2.ChoiceLoader(loaders)

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

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

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

Параметры: loaders (Sequence[jinja2.loaders.BaseLoader]) –
Тип возвращаемого значения: None

class jinja2.ModuleLoader(path)

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

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

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

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

Параметры: path (Union[str, os.PathLike, Sequence[Union[str, os.PathLike]]]) –
Тип возвращаемого значения: None

Кэш байткода

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 (jinja2.bccache.Bucket) –
Тип возвращаемого значения: None

load_bytecode(bucket)

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

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

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

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

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

Параметры

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

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

environment: %%CODE_BLOCK_364%%% создавшая корзину.

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 (BinaryIO) –
Тип возвращаемого значения: 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 (Optional[str]) –
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 (str) –
timeout (Optional[int]) –
ignore_memcache_errors (bool) –

class MinimalClientInterface

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

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

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

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

Changelog

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

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

Changelog

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

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

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

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

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

Политики

Начиная с 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:: Аргументы ключевых слов, которые будут переданы функции вывода. По умолчанию — {'sort_keys': True}.

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

Утилиты

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

jinja2.pass_context(f)

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

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

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

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

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

jinja2.pass_eval_context(f)

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

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

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

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

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

jinja2.pass_environment(f)

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

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

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

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

jinja2.contextfilter(f)

Передайте контекст в качестве первого аргумента декорированной функции.

Устарело начиная с версии 3.0: Будет удалено в Jinja 3.1. Используйте pass_context() вместо этого.

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

jinja2.evalcontextfilter(f)

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

Устарело начиная с версии 3.0: Будет удалено в Jinja 3.1. Используйте pass_eval_context() вместо этого.

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

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

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

jinja2.environmentfilter(f)

Передайте среду в качестве первого аргумента декорированной функции.

Устарело начиная с версии 3.0: Будет удалено в Jinja 3.1. Используйте pass_environment() вместо этого.

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

jinja2.contextfunction(f)

Передайте контекст в качестве первого аргумента декорированной функции.

Устарело начиная с версии 3.0: Будет удалено в Jinja 3.1. Используйте pass_context() вместо этого.

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

jinja2.evalcontextfunction(f)

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

Устарело начиная с версии 3.0: Будет удалено в Jinja 3.1. Используйте pass_eval_context() вместо этого.

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

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

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

jinja2.environmentfunction(f)

Передайте среду в качестве первого аргумента декорированной функции.

Устарело начиная с версии 3.0: Будет удалено в Jinja 3.1. Используйте pass_environment() вместо этого.

Параметры: f (jinja2.utils.F) –
Тип возвращаемого значения: jinja2.utils.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

END_OF_DOCUMENT_MARKER

Исключения

exception jinja2.TemplateError(message=None)

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

Параметры: message (Необязательно[str]) –
Тип возвращаемого значения: None

exception jinja2.UndefinedError(message=None)

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

Параметры: message (Необязательно[str]) –
Тип возвращаемого значения: None

exception jinja2.TemplateNotFound(name, message=None)

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

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

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

Параметры

name (Необязательно[Union[str, Undefined]]) –
message (Необязательно[str]) –

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

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

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

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

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

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

Параметры

names (Последовательность[Union[str, Undefined]]) –
message (Необязательно[str]) –

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

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

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

Параметры

message (str) –
lineno (int) –
name (Необязательно[str]) –
filename (Необязательно[str]) –

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

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

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

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

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

exception jinja2.TemplateRuntimeError(message=None)

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

Параметры: message (Необязательно[str]) –
Тип возвращаемого значения: None

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

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

Параметры

message (str) –
lineno (int) –
name (Необязательно[str]) –
filename (Необязательно[str]) –

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

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

Фильтры — это функции 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>. Он использует контекст оценки для проверки, включен ли в настоящее время autoescape, прежде чем экранировать вход и маркировать вывод безопасным.

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)

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

Parameters

environment (Environment) –
template_name (Optional[str]) –

Return type

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]) –
filename (Необязательно[str]) –

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

Iterator[Tuple[int, str, str]]

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

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

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

Параметры

source (str) –
name (Необязательно[str]) –
filename (Необязательно[str]) –

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

jinja2.nodes.Template

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

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

Параметры

source (str) –
name (Необязательно[str]) –
filename (Необязательно[str]) –

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