Расширения

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

Добавление расширений

Расширения добавляются к среде Jinja во время создания. Для добавления расширения передайте список классов расширений или имён путей импорта в параметр extensions конструктора Environment. Следующий пример создаёт среду Jinja с загруженным расширением i18n:

jinja_env = Environment(extensions=['jinja2.ext.i18n'])

Для добавления расширений после создания используйте метод add_extension():

jinja_env.add_extension('jinja2.ext.debug')

Расширение i18n

Имя импорта: jinja2.ext.i18n

Расширение i18n можно использовать в сочетании с gettext или Babel. При его включении Jinja предоставляет инструкцию trans для пометки блока как переводимого и вызова gettext.

После включения приложение должно предоставить функции для gettext, ngettext, и необязательно pgettext и npgettext, либо глобально, либо при отрисовке. Функция _() добавлена как псевдоним функции gettext.

Методы среды

После включения расширения среда предоставляет следующие дополнительные методы:

jinja2.Environment.install_gettext_translations(translations, newstyle=False): Устанавливает перевод глобально для среды. Объект translations должен реализовывать gettext, ngettext, и необязательно pgettext и npgettext. Поддерживаются gettext.NullTranslations, gettext.GNUTranslations и Translations от Babel.

Изменено в версии 3.0: Добавлено pgettext и npgettext.

Изменения

Изменено в версии 2.5: Добавлена поддержка gettext нового стиля.

jinja2.Environment.install_null_translations(newstyle=False): Устанавливает функции gettext, которые ничего не делают. Это полезно, если вы хотите подготовить приложение к международному использованию, но пока не хотите реализовывать полную систему.

Изменения

Изменено в версии 2.5: Добавлена поддержка gettext нового стиля.

jinja2.Environment.install_gettext_callables(gettext, ngettext, newstyle=False, pgettext=None, npgettext=None)

Устанавливает заданные gettext, ngettext, pgettext, и npgettext вызываемые объекты в среду. Они должны вести себя точно так же, как gettext.gettext(), gettext.ngettext(), gettext.pgettext() и gettext.npgettext().

Если newstyle включено, вызываемые объекты оборачиваются для работы как вызываемые объекты нового стиля. Подробнее см. Новый стиль Gettext.

Изменено в версии 3.0: Добавлено pgettext и npgettext.

Изменения

Добавлен в версии 2.5: Добавлена поддержка gettext нового стиля.

jinja2.Environment.uninstall_gettext_translations(): Удалить глобально установленный перевод среды.

jinja2.Environment.extract_translations(source)

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

Для каждой найденной строки эта функция возвращает кортеж (lineno, function, message), где:

lineno — номер строки, в которой была найдена строка.
function — имя используемой функции gettext (если строка была извлечена из вложенного Python-кода).
message — сама строка или кортеж строк для функций с несколькими аргументами.

Если установлен Babel, см. Babel для извлечения строк.

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

translations = get_gettext_translations()
env = Environment(extensions=["jinja2.ext.i18n"])
env.install_gettext_translations(translations)

Функция get_gettext_translations вернёт переводчика для текущей конфигурации, например, используя gettext.find.

Использование расширения i18n для разработчиков шаблонов описано в документации шаблонов.

Удаление пробелов

Изменения

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

Внутри блоков {% trans %} бывает полезно обрезать символы перевода строки и пробелы, чтобы блок текста выглядел как простая строка с одиночными пробелами в файле перевода.

Символы перевода строки и окружающие пробелы могут быть автоматически удалены путём включения политики ext.i18n.trimmed политики.

Новый стиль Gettext

Изменения

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

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

Вы можете использовать вызовы gettext «нового стиля», установив env.newstyle_gettext = True или передав newstyle=True в env.install_translations. Они полностью поддерживаются инструментом извлечения Babel, но могут не работать должным образом с другими инструментами извлечения.

В стандартных вызовах gettext, форматирование строки — это отдельный шаг, выполняемый с помощью фильтра |format. Это требует дублирования работы для ngettext вызовов.

{{ gettext("Hello, World!") }}
{{ gettext("Hello, %(name)s!")|format(name=name) }}
{{ ngettext(
       "%(num)d apple", "%(num)d apples", apples|count
   )|format(num=apples|count) }}
{{ pgettext("greeting", "Hello, World!") }}
{{ npgettext(
       "fruit", "%(num)d apple", "%(num)d apples", apples|count
   )|format(num=apples|count) }}

Вызовы gettext нового стиля делают форматирование частью вызова и обеспечивают большую согласованность.

{{ gettext("Hello, World!") }}
{{ gettext("Hello, %(name)s!", name=name) }}
{{ ngettext("%(num)d apple", "%(num)d apples", apples|count) }}
{{ pgettext("greeting", "Hello, World!") }}
{{ npgettext("fruit", "%(num)d apple", "%(num)d apples", apples|count) }}

Преимущества вызовов gettext нового стиля:

Нет отдельного шага форматирования, не нужно помнить о использовании фильтра |format.
Допускаются только именованные заполнитель. Это решает общую проблему, с которой сталкиваются переводчики, потому что позиционные плейсхолдеры не могут осмысленно переключаться. Именованные плейсхолдеры всегда содержат семантическую информацию о том, какое значение где расположено.
Форматирование строк используется даже если не используются плейсхолдеры, что делает все строки согласованными в формате. Не забудьте экранировать все необработанные проценты как %%, например 100%%.
Переведённая строка помечена как безопасная, форматирование выполняет экранирование по мере необходимости. Пометьте параметр как |safe если он уже экранирован.

Оператор выражения

Имя импорта: jinja2.ext.do

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

Управление циклами

Имя импорта: jinja2.ext.loopcontrols

Это расширение добавляет поддержку break и continue в циклах. После включения Jinja предоставляет эти два ключевых слова, которые работают точно так же, как и в Python.

Оператор with

Имя импорта: jinja2.ext.with_

Изменения

Изменено в версии 2.9: Это расширение теперь встроенное и больше ничего не делает.

Расширение автоматического экранирования

Имя импорта: jinja2.ext.autoescape

Изменения

Изменено в версии 2.9: Это расширение было удалено и теперь встроенное. Включение расширения больше ничего не делает.

Расширение отладки

Имя импорта: jinja2.ext.debug

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

END_OF_DOCUMENT_MARKER

Написание расширений

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

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

Примеры расширений

Кэширование

Следующий пример реализует тег cache для Jinja с использованием библиотеки cachelib:

from jinja2 import nodes
from jinja2.ext import Extension


class FragmentCacheExtension(Extension):
    # a set of names that trigger the extension.
    tags = {"cache"}

    def __init__(self, environment):
        super().__init__(environment)

        # add the defaults to the environment
        environment.extend(fragment_cache_prefix="", fragment_cache=None)

    def parse(self, parser):
        # the first token is the token that started the tag.  In our case
        # we only listen to ``'cache'`` so this will be a name token with
        # `cache` as value.  We get the line number so that we can give
        # that line number to the nodes we create by hand.
        lineno = next(parser.stream).lineno

        # now we parse a single expression that is used as cache key.
        args = [parser.parse_expression()]

        # if there is a comma, the user provided a timeout.  If not use
        # None as second parameter.
        if parser.stream.skip_if("comma"):
            args.append(parser.parse_expression())
        else:
            args.append(nodes.Const(None))

        # now we parse the body of the cache block up to `endcache` and
        # drop the needle (which would always be `endcache` in that case)
        body = parser.parse_statements(["name:endcache"], drop_needle=True)

        # now return a `CallBlock` node that calls our _cache_support
        # helper method on this extension.
        return nodes.CallBlock(
            self.call_method("_cache_support", args), [], [], body
        ).set_lineno(lineno)

    def _cache_support(self, name, timeout, caller):
        """Helper callback."""
        key = self.environment.fragment_cache_prefix + name

        # try to load the block from the cache
        # if there is no fragment in the cache, render it and store
        # it in the cache.
        rv = self.environment.fragment_cache.get(key)
        if rv is not None:
            return rv
        rv = caller()
        self.environment.fragment_cache.add(key, rv, timeout)
        return rv

Вот как его использовать в среде:

from jinja2 import Environment
from cachelib import SimpleCache

env = Environment(extensions=[FragmentCacheExtension])
env.fragment_cache = SimpleCache()

В шаблоне можно пометить блоки как кэшируемые. В следующем примере кешируется сайдбар на 300 секунд:

{% cache 'sidebar', 300 %}
<div class="sidebar">
    ...
</div>
{% endcache %}

Встроенная `gettext`

Следующий пример демонстрирует использование Extension.filter_stream() для разбора вызовов функции _() gettext в строке со статическими данными без необходимости использования блоков Jinja.

<h1>_(Welcome)</h1>
<p>_(This is a paragraph)</p>

Для этого необходимо загрузить и настроить расширение i18n.

import re

from jinja2.exceptions import TemplateSyntaxError
from jinja2.ext import Extension
from jinja2.lexer import count_newlines
from jinja2.lexer import Token


_outside_re = re.compile(r"\\?(gettext|_)\(")
_inside_re = re.compile(r"\\?[()]")


class InlineGettext(Extension):
    """This extension implements support for inline gettext blocks::

        <h1>_(Welcome)</h1>
        <p>_(This is a paragraph)</p>

    Requires the i18n extension to be loaded and configured.
    """

    def filter_stream(self, stream):
        paren_stack = 0

        for token in stream:
            if token.type != "data":
                yield token
                continue

            pos = 0
            lineno = token.lineno

            while True:
                if not paren_stack:
                    match = _outside_re.search(token.value, pos)
                else:
                    match = _inside_re.search(token.value, pos)
                if match is None:
                    break
                new_pos = match.start()
                if new_pos > pos:
                    preval = token.value[pos:new_pos]
                    yield Token(lineno, "data", preval)
                    lineno += count_newlines(preval)
                gtok = match.group()
                if gtok[0] == "\\":
                    yield Token(lineno, "data", gtok[1:])
                elif not paren_stack:
                    yield Token(lineno, "block_begin", None)
                    yield Token(lineno, "name", "trans")
                    yield Token(lineno, "block_end", None)
                    paren_stack = 1
                else:
                    if gtok == "(" or paren_stack > 1:
                        yield Token(lineno, "data", gtok)
                    paren_stack += -1 if gtok == ")" else 1
                    if not paren_stack:
                        yield Token(lineno, "block_begin", None)
                        yield Token(lineno, "name", "endtrans")
                        yield Token(lineno, "block_end", None)
                pos = match.end()

            if pos < len(token.value):
                yield Token(lineno, "data", token.value[pos:])

        if paren_stack:
            raise TemplateSyntaxError(
                "unclosed gettext expression",
                token.lineno,
                stream.name,
                stream.filename,
            )

API расширений

Расширение

Расширения всегда должны расширять класс jinja2.ext.Extension:

class jinja2.ext.Extension(environment)

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

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

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

identifier: Идентификатор расширения. Это всегда истинное имя импорта класса расширения и его нельзя изменять.

tags: Если расширение реализует пользовательские теги, это набор имён тегов, за которыми расширение следит.

attr(name, lineno=None)

Возвращает узел атрибута для текущего расширения. Это полезно для передачи констант расширений сгенерированному коду шаблона.

self.attr('_my_attribute', lineno=lineno)

Параметры

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

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

jinja2.nodes.ExtensionAttribute

call_method(name, args=None, kwargs=None, dyn_args=None, dyn_kwargs=None, lineno=None)

Вызов метода расширения. Это сокращение для attr() + jinja2.nodes.Call.

Параметры

name (str) –
args (Необязательно[List[jinja2.nodes.Expr]]) –
kwargs (Необязательно[List[jinja2.nodes.Keyword]]) –
dyn_args (Необязательно[jinja2.nodes.Expr]) –
dyn_kwargs (Необязательно[jinja2.nodes.Expr]) –
lineno (Необязательно[int]) –

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

jinja2.nodes.Call

filter_stream(stream)

Ему передаётся TokenStream, который можно использовать для фильтрации возвращаемых токенов. Этот метод должен возвращать итерируемый набор Tokens, но он не обязан возвращать TokenStream.

Параметры: stream (TokenStream) –
Тип возвращаемого значения: Union[TokenStream, Iterable[Token]]

parse(parser)

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

Параметры: parser (Parser) –
Тип возвращаемого значения: Union[jinja2.nodes.Node, List[jinja2.nodes.Node]]

preprocess(source, name, filename=None)

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

Параметры

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

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

str

Парсер

Парсер, переданный в Extension.parse(), предоставляет способы разбора выражений разных типов. Расширения могут использовать следующие методы:

class jinja2.parser.Parser(environment, source, name=None, filename=None, state=None)

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

Параметры

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

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

Расширения

Добавление расширений

Расширение i18n

Методы среды

Удаление пробелов

Новый стиль Gettext

Оператор выражения

Управление циклами

Оператор with

Расширение автоматического экранирования

Расширение отладки

Написание расширений

Примеры расширений

Кэширование

Встроенная gettext

API расширений

Расширение

Парсер

AST

Встроенная `gettext`