Расширения

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

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

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

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

Расширение i18n

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

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

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

Методы среды

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

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

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

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

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

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

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

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

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

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

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

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

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

jinja2.Environment.extract_translations(source)

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

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

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

Если установлен 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) }}

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

{{ gettext("Hello, World!") }}
{{ gettext("Hello, %(name)s!", name=name) }}
{{ ngettext("%(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 %} тег для вывода текущего контекста, а также доступных фильтров и тестов. Это полезно для просмотра доступных ресурсов в шаблоне без настройки отладчика.

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

Написание расширений позволяет добавлять пользовательские теги в 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(FragmentCacheExtension, self).__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 было загружено и настроено.

# -*- coding: utf-8 -*-
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 1:
                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 += gtok == ")" and -1 or 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 — хорошее имя, так как включает имя расширения (кеш фрагментов).

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

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

attr(name, lineno=None)

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

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

call_method(name, args=None, kwargs=None, dyn_args=None, dyn_kwargs=None, lineno=None): Вызывает метод расширения. Это сокращение для attr() + jinja2.nodes.Call.

filter_stream(stream): Получает TokenStream, который можно использовать для фильтрации возвращаемых токенов. Этот метод должен вернуть итерируемый список Token элементов, но не обязательно TokenStream.

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

preprocess(source, name, filename=None): Этот метод вызывается перед фактическим лексированием и может использоваться для предварительной обработки исходного кода. filename — необязательно. Возвращаемое значение должно быть предварительно обработанным исходным кодом.

Парсер

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

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

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

filename: Имя файла шаблона, который обрабатывает анализатор. Это не имя загруженного шаблона. Для имени загруженного шаблона см. name. Для шаблонов, которые не загружались из файловой системы, это None.

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

stream: Текущий TokenStream

fail(msg, lineno=None, exc=<class 'jinja2.exceptions.TemplateSyntaxError'>): Удобный метод, который вызывает exc с сообщением, указанным номером строки или последним номером строки, а также текущим именем и именем файла.

free_identifier(lineno=None): Возвращает новый свободный идентификатор в виде InternalName.

parse_assign_target(with_tuple=True, name_only=False, extra_end_rules=None, with_namespace=False): Разбирает целевой объект присваивания. Поскольку Jinja допускает присваивания кортежам, эта функция может разбирать все разрешённые целевые объекты присваивания. По умолчанию присваивания кортежам разбираются, но это можно отключить, установив with_tuple в False. Если нужны только присваивания именам, name_only можно установить в True. Параметр extra_end_rules передаётся функции разбора кортежей. Если with_namespace включено, может быть разобран присваивание пространства имён.

parse_expression(with_condexpr=True): Разбирает выражение. По умолчанию все выражения разбираются, но если опциональный параметр with_condexpr установлен в False, условные выражения не разбираются.

parse_statements(end_tokens, drop_needle=False): Разбирает несколько операторов в список до тех пор, пока не будет достигнут один из операторов конца. Это используется для разбора тела операторов, так как оно также разбирает данные шаблона, если это уместно. Анализатор сначала проверяет, является ли текущий токен двоеточием, и пропускает его, если он есть. Затем он проверяет конец блока и разбирает, пока не будет достигнут один из end_tokens. По умолчанию активный токен в потоке в конце вызова — это соответствующий токен конца. Если этого не требуется, drop_needle можно установить в True, и токен конца будет удалён.

parse_tuple(simplified=False, with_condexpr=True, extra_end_rules=None, explicit_parentheses=False)

Работает как parse_expression, но если несколько выражений разделяются запятыми, создаётся узел Tuple. Этот метод также может вернуть обычное выражение вместо кортежа, если запятых не найдено.

Режим разбора по умолчанию — полный кортеж. Если simplified равно True, разбираются только имена и литералы. Параметр no_condexpr передаётся в parse_expression().

Поскольку кортежи не требуют разделителей и могут заканчиваться ложной запятой, требуется дополнительная подсказка, которая отмечает конец кортежа. Например, циклы for поддерживают кортежи между for и in. В этом случае extra_end_rules устанавливается в ['name:in'].

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

class jinja2.lexer.TokenStream(generator, name, filename)

Поток токенов — это итерируемый объект, который возвращает Tokenы. Однако парсер не итерируется по нему, а вызывает next() для перехода к следующему токену. Текущий активный токен хранится как current.

current: Текущий Token.

__next__()

Переход к следующему токену и возврат предыдущего.

Используйте встроенную функцию next() вместо прямого вызова.

property eos: Находимся ли мы в конце потока?

expect(expr): Ожидать указанного типа токена и вернуть его. Принимает те же аргументы, что и jinja2.lexer.Token.test().

look(): Просмотр следующего токена.

next_if(expr): Выполнить проверку токена и вернуть токен, если он соответствует. В противном случае возвращается None.

push(token): Возврат токена в поток.

skip(n=1): Переход к n токенам вперёд.

skip_if(expr): Аналогично next_if(), но возвращает только True или False.

class jinja2.lexer.Token

Класс токена.

lineno: Номер строки токена

type: Тип токена. Это строка, интернированная в памяти, поэтому ее можно сравнивать с произвольными строками, используя оператор is.

value: Значение токена.

test(expr): Проверка токена на соответствие выражению. Это может быть тип токена или 'token_type:token_value'. Проверка возможна только со строковыми значениями и типами.

test_any(*iterable): Проверка на соответствие нескольким выражениям токенов.

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

jinja2.lexer.count_newlines(value): Подсчёт количества символов новой строки в строке. Это полезно для расширений, которые фильтруют поток.

AST

AST (Абстрактное синтаксическое дерево) используется для представления шаблона после парсинга. Оно состоит из узлов, которые компилятор затем преобразует в исполняемые объекты кода Python. Расширения, предоставляющие пользовательские операторы, могут возвращать узлы для выполнения пользовательского кода Python.

Ниже перечислены все доступные узлы. AST может изменяться между версиями Jinja, но остаётся обратно совместимым.

Для получения дополнительной информации посмотрите repr jinja2.Environment.parse().

class jinja2.nodes.Node

Базовый класс для всех узлов Jinja. Доступно множество узлов разных типов. Есть четыре основных типа:

Stmt: операторы
Expr: выражения
Helper: узлы помощников
Template: внешний оберточный узел

Все узлы имеют поля и атрибуты. Поля могут быть другими узлами, списками или произвольными значениями. Поля передаются конструктору в качестве обычных позиционных аргументов, атрибуты — как ключевые аргументы. Каждый узел имеет два атрибута: lineno (номер строки узла) и environment. Атрибут environment устанавливается в конце процесса парсинга для всех узлов автоматически.

find(node_type): Найти первый узел заданного типа. Если такого узла не существует, возвращаемое значение — None.

find_all(node_type): Найти все узлы заданного типа. Если тип является кортежем, проверка выполняется для любого из элементов кортежа.

iter_child_nodes(exclude=None, only=None): Итерируется по всем непосредственным дочерним узлам узла. Итерируется по всем полям и возвращает значения, если они являются узлами. Если значение поля является списком, возвращаются все узлы в этом списке.

iter_fields(exclude=None, only=None): Этот метод итерируется по всем определённым полям и возвращает (key, value) кортежи. По умолчанию возвращаются все поля, но можно ограничить это некоторыми полями, предоставив параметр only, или исключить некоторые, используя параметр exclude. Оба должны быть наборами или кортежами имён полей.

set_ctx(ctx): Сбросить контекст узла и всех дочерних узлов. По умолчанию парсер будет генерировать все узлы с контекстом «load», так как это наиболее распространённый. Этот метод используется в парсере для установки целевых значений присваивания и других узлов в контекст «store».

set_environment(environment): Установить среду для всех узлов.

set_lineno(lineno, override=False): Установить номера строк узла и дочерних элементов.

class jinja2.nodes.Expr

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

Тип узла: Node

as_const(eval_ctx=None)

Возвращает значение выражения как константу или вызывает Impossible, если это невозможно.

Можно предоставить EvalContext; если нет, создаётся контекст по умолчанию, требующий наличия среды, привязанной к узлам.

Изменения

Изменено в версии 2.4: добавлен параметр eval_ctx.

can_assign(): Проверить возможность присваивания чему-либо данному узлу.

class jinja2.nodes.BinExpr(left, right)

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

Тип узла: Expr

class jinja2.nodes.Add(left, right)

Сложить левое к правому узлу.

Тип узла: BinExpr

class jinja2.nodes.And(left, right)

Короткое замыкание И.

Тип узла: BinExpr

class jinja2.nodes.Div(left, right)

Разделить левое на правое значение узла.

Тип узла: BinExpr

END_OF_DOCUMENT_MARKER ```

class jinja2.nodes.FloorDiv(left, right)

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

Тип узла: BinExpr

class jinja2.nodes.Mod(left, right)

Остаток от деления левого значения на правое.

Тип узла: BinExpr

class jinja2.nodes.Mul(left, right)

Перемножает левое значение с правым.

Тип узла: BinExpr

class jinja2.nodes.Or(left, right)

Короткое логическое ИЛИ.

Тип узла: BinExpr

class jinja2.nodes.Pow(left, right)

Возведение левого значения в степень правого.

Тип узла: BinExpr

class jinja2.nodes.Sub(left, right)

Вычитание правого значения из левого.

Тип узла: BinExpr

class jinja2.nodes.Call(node, args, kwargs, dyn_args, dyn_kwargs)

Вызов выражения. args — список аргументов, kwargs — список именованных аргументов (список узлов Keyword), а dyn_args и dyn_kwargs должны быть либо None, либо узлом, используемым для динамических позиционных (*args) или именованных (**kwargs) аргументов.

Тип узла: Expr

class jinja2.nodes.Compare(expr, ops)

Сравнение выражения с другими выражениями. ops должен быть списком Operand.

Тип узла: Expr

class jinja2.nodes.Concat(nodes)

Конкатенация списка выражений после преобразования их в строковый тип.

Тип узла: Expr

class jinja2.nodes.CondExpr(test, expr1, expr2)

Условное выражение (встроенное выражение if). ({{ foo if bar else baz }})

Тип узла: Expr

class jinja2.nodes.ContextReference

Возвращает текущий контекст шаблона. Его можно использовать как узел Name, с префиксом 'load', и он вернет текущий объект Context.

Пример присвоения имени текущего шаблона переменной foo:

Assign(Name('foo', ctx='store'),
       Getattr(ContextReference(), 'name'))

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

Тип узла: Expr

class jinja2.nodes.DerivedContextReference

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

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

Тип узла: Expr

class jinja2.nodes.EnvironmentAttribute(name)

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

Тип узла: Expr

class jinja2.nodes.ExtensionAttribute(identifier, name)

Возвращает атрибут расширения, связанного со средой. Идентификатор — это идентификатор Extension.

Этот узел обычно создаётся путём вызова метода attr() расширения.

Тип узла: Expr

class jinja2.nodes.Filter(node, name, args, kwargs, dyn_args, dyn_kwargs)

Этот узел применяет фильтр к выражению. name — имя фильтра, остальные поля такие же, как для Call.

Если node фильтра равен None, содержимое последнего буфера фильтруется. Буферы создаются макросами и блоками фильтров.

Тип узла: Expr

class jinja2.nodes.Getattr(node, attr, ctx)

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

Тип узла: Expr

class jinja2.nodes.Getitem(node, arg, ctx)

Получает атрибут или элемент из выражения и отдаёт предпочтение элементу.

Тип узла: Expr

class jinja2.nodes.ImportedName(importname)

Если создан с именем импорта, при обращении к узлу возвращается имя импорта. Например, ImportedName('cgi.escape') возвращает функцию escape из модуля cgi при оценке. Импорты оптимизируются компилятором, поэтому нет необходимости назначать их локальным переменным.

Тип узла: Expr

class jinja2.nodes.InternalName(name)

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

Тип узла: Expr

class jinja2.nodes.Literal

Базовый класс для литералов.

Тип узла: Expr

class jinja2.nodes.Const(value)

Все константные значения. Парсер вернёт этот узел для простых констант, таких как 42 или "foo", но его можно использовать для хранения более сложных значений, таких как списки. Только константы с безопасным представлением (объекты, для которых eval(repr(x)) == x истинно).

Тип узла: Literal

END_OF_DOCUMENT_MARKER

class jinja2.nodes.Dict(items)

Любой словарь-литерал, например {1: 2, 3: 4}. Элементы должны быть списком узлов Pair.

Тип узла: Literal

class jinja2.nodes.List(items)

Любой список-литерал, например [1, 2, 3]

Тип узла: Literal

class jinja2.nodes.TemplateData(data)

Константная строка шаблона.

Тип узла: Literal

class jinja2.nodes.Tuple(items, ctx)

Для распаковки циклов for и некоторых других задач, таких как передача нескольких аргументов для индексации. Например, для Name ctx указывает, используется ли кортеж для загрузки имён или для хранения.

Тип узла: Literal

class jinja2.nodes.MarkSafe(expr)

Пометить обернутое выражение как безопасное (обернуть как Markup).

Тип узла: Expr

class jinja2.nodes.MarkSafeIfAutoescape(expr)

Пометить обернутое выражение как безопасное (обернуть как Markup), но только если автоматическое экранирование включено.

Changelog

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

Тип узла: Expr

class jinja2.nodes.Name(name, ctx)

Ищет имя или сохраняет значение в имени. ctx узла может иметь одно из следующих значений:

store: сохранить значение в имени
load: загрузить имя
param: как store, но если имя определено как параметр функции.

Тип узла: Expr

class jinja2.nodes.NSRef(name, attr)

Ссылка на присвоение значения в пространстве имён

Тип узла: Expr

class jinja2.nodes.Slice(start, stop, step)

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

Тип узла: Expr

class jinja2.nodes.Test(node, name, args, kwargs, dyn_args, dyn_kwargs)

Применяет тест к выражению. name — имя теста, остальные поля совпадают с Call.

Тип узла: Expr

class jinja2.nodes.UnaryExpr(node)

Базовый класс для всех унарных выражений.

Тип узла: Expr

class jinja2.nodes.Neg(node)

Сделать выражение отрицательным.

Тип узла: UnaryExpr

class jinja2.nodes.Not(node)

Отрицание выражения.

Тип узла: UnaryExpr

class jinja2.nodes.Pos(node)

Сделать выражение положительным (ничего не делать для большинства выражений)

Тип узла: UnaryExpr

class jinja2.nodes.Helper

Узлы, существующие только в определённом контексте.

Тип узла: Node

class jinja2.nodes.Keyword(key, value)

Пара ключ-значение для ключевых аргументов, где ключ — строка.

Тип узла: Helper

class jinja2.nodes.Operand(op, expr)

Содержит оператор и выражение. Доступны следующие операторы: %, **, *, +, -, //, /, eq, gt, gteq, in, lt, lteq, ne, not, notin

Тип узла: Helper

class jinja2.nodes.Pair(key, value)

Пара ключ-значение для словарей.

Тип узла: Helper

class jinja2.nodes.Stmt

Базовый узел для всех инструкций.

Тип узла: Node

class jinja2.nodes.Assign(target, node)

Присваивает выражение цели.

Тип узла: Stmt

class jinja2.nodes.AssignBlock(target, filter, body)

Присваивает блок цели.

Тип узла: Stmt

class jinja2.nodes.Block(name, body, scoped)

Узел, представляющий блок.

Тип узла: Stmt

class jinja2.nodes.Break

Прервать цикл.

Тип узла: Stmt

class jinja2.nodes.CallBlock(call, args, defaults, body)

Как макрос без имени, но вместо вызова. call вызывается с безымянным макросом как аргумент caller этот узел держит.

Тип узла: Stmt

class jinja2.nodes.Continue

Продолжить цикл.

Тип узла: Stmt

class jinja2.nodes.EvalContextModifier(options)

Изменяет контекст вычисления. Для каждого параметра, который необходимо изменить, необходимо добавить Keyword в список options.

Пример изменения настройки %%%CODE_BLOCK_355%%:

EvalContextModifier(options=[Keyword('autoescape', Const(True))])

Тип узла: Stmt

END_OF_DOCUMENT_MARKER

class jinja2.nodes.ScopedEvalContextModifier(options, body)

Изменяет контекст вычисления и затем отменяет изменения. Работает точно так же, как EvalContextModifier, но будет изменять только EvalContext для узлов в body.

Тип узла: EvalContextModifier

class jinja2.nodes.ExprStmt(node)

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

Тип узла: Stmt

class jinja2.nodes.Extends(template)

Представляет оператор extends.

Тип узла: Stmt

class jinja2.nodes.FilterBlock(body, filter)

Узел для разделов фильтров.

Тип узла: Stmt

class jinja2.nodes.For(target, iter, body, else_, test, recursive)

Цикл for. target — целевой объект для итерации (обычно Name или Tuple), iter — объект итерирования. body — список узлов, используемых в теле цикла, а else_ — список узлов для блока else. Если узел else отсутствует, то список должен быть пустым.

Для отфильтрованных узлов выражение может храниться как test, иначе None.

Тип узла: Stmt

class jinja2.nodes.FromImport(template, names, with_context)

Узел, представляющий тэг from import. Важно не передавать небезопасные имена в атрибут name. Компилятор преобразует обращения к атрибутам напрямую в вызовы getattr и не использует обратный вызов подстроки интерфейса. Так как экспортированные переменные, вероятно, не начинаются с двойных подчеркиваний (что утверждается анализатором), это не проблема для обычного кода Jinja, но если этот узел используется в расширении, необходимо соблюдать особую осторожность.

Список имен может содержать кортежи, если требуются псевдонимы.

Тип узла: Stmt

class jinja2.nodes.If(test, body, elif_, else_)

Если test истинно, то body отображается, иначе else_.

Тип узла: Stmt

class jinja2.nodes.Import(template, target, with_context)

Узел, представляющий тэг import.

Тип узла: Stmt

class jinja2.nodes.Include(template, with_context, ignore_missing)

Узел, представляющий тэг include.

Тип узла: Stmt

class jinja2.nodes.Macro(name, args, defaults, body)

Определение макроса. name — имя макроса, args — список аргументов, а defaults — список значений по умолчанию, если таковые имеются. body — список узлов для тела макроса.

Тип узла: Stmt

class jinja2.nodes.Output(nodes)

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

Тип узла: Stmt

class jinja2.nodes.OverlayScope(context, body)

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

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

OverlayScope(context=self.call_method('get_context'),
             body=[...])

Изменения

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

Тип узла: Stmt

class jinja2.nodes.Scope(body)

Искусственная область.

Тип узла: Stmt

class jinja2.nodes.With(targets, values, body)

Узел для оператора with. В более ранних версиях Jinja оператор with реализовывался на основе узла Scope.

Изменения

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

Тип узла: Stmt

class jinja2.nodes.Template(body)

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

Тип узла: Node

exception jinja2.nodes.Impossible: Вызывается, если узел не смог выполнить запрошенное действие.

Расширения

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

Расширение i18n

Методы среды

Обрезка пробелов

Новая стилистика Gettext

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

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

Оператор with

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

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

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

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

Кэш

Встроенный gettext

API расширений

Расширение

Парсер

AST

Встроенный `gettext`