Песочница

Песочница Jinja2 может использоваться для оценки небезопасного кода. Доступ к небезопасным атрибутам и методам запрещён.

Предполагая, что env является SandboxedEnvironment в конфигурации по умолчанию, следующий фрагмент кода демонстрирует, как это работает:

>>> env.from_string("{{ func.func_code }}").render(func=lambda:None)
u''
>>> env.from_string("{{ func.func_code.do_something }}").render(func=lambda:None)
Traceback (most recent call last):
  ...
SecurityError: access to attribute 'func_code' of 'function' object is unsafe.

API

class jinja2.sandbox.SandboxedEnvironment([options])

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

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

call_binop(context, operator, left, right)

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

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

Новая функция в версии 2.6.

call_unop(context, operator, arg)

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

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

Новая функция в версии 2.6.

default_binop_table = {'%': <built-in function mod>, '*': <built-in function mul>, '**': <built-in function pow>, '+': <built-in function add>, '-': <built-in function sub>, '/': <built-in function truediv>, '//': <built-in function floordiv>}

Стандартная таблица обратных вызовов для бинарных операторов. Копия этого объекта доступна в каждом экземпляре среды песочницы как binop_table

default_unop_table = {'+': <built-in function pos>, '-': <built-in function neg>}

Стандартная таблица обратных вызовов для унарных операторов. Копия этого объекта доступна в каждом экземпляре среды песочницы как unop_table

intercepted_binops = frozenset({})

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

Следующие бинарные операторы могут быть перехвачены: //, %, +, *, -, /, и **

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

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

Новая функция в версии 2.6.

intercepted_unops = frozenset({})

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

Следующие унарные операторы могут быть перехвачены: +, -

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

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

Новая функция в версии 2.6.

is_safe_attribute(obj, attr, value)

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

is_safe_callable(obj)

Проверяет, является ли объект безопасно вызываемым. По умолчанию функция считается безопасной, если атрибут unsafe_callable существует и равен True. Переопределите этот метод для изменения поведения, но это не повлияет на декоратор unsafe из этого модуля.

class jinja2.sandbox.ImmutableSandboxedEnvironment([options])

Работает точно так же, как и обычный SandboxedEnvironment , но не допускает изменений в встроенных изменяемых объектах list, set, и dict с помощью функции modifies_known_mutable().

exception jinja2.sandbox.SecurityError(message=None)

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

jinja2.sandbox.unsafe(f)

Помечает функцию или метод как небезопасный.

@unsafe
def delete(self):
    pass

jinja2.sandbox.is_internal_attribute(obj, attr)

Проверяет, является ли заданный атрибут внутренним атрибутом Python. Например, эта функция возвращает True для атрибута func_code объектов Python. Это полезно, если переопределён метод среды is_safe_attribute().

>>> from jinja2.sandbox import is_internal_attribute
>>> is_internal_attribute(str, "mro")
True
>>> is_internal_attribute(str, "upper")
False

jinja2.sandbox.modifies_known_mutable(obj, attr)

Эта функция проверяет, изменит ли вызов атрибута встроенного изменяемого объекта (список, словарь, множество или очередь с двойной стороной) его. Она также поддерживает «пользовательские» версии объектов (sets.Set, UserDict.* и т. д.) и, начиная с Python 2.6, абстрактные базовые классы MutableSet, MutableMapping, и MutableSequence.

>>> modifies_known_mutable({}, "clear")
True
>>> modifies_known_mutable({}, "keys")
False
>>> modifies_known_mutable([], "append")
True
>>> modifies_known_mutable([], "index")
False

Если вызов производится с недопустимым объектом (например, unicode), возвращается False.

>>> modifies_known_mutable("foo", "upper")
False

Перехват операторов

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

С Jinja 2.6 появилась поддержка явного перехвата операторов. Это позволяет настраивать определённые операторы по мере необходимости. Для перехвата оператора необходимо переопределить атрибут SandboxedEnvironment.intercepted_binops. После добавления оператора, который нужно перехватить, в этот набор Jinja2 сгенерирует байткод, который вызовет функцию SandboxedEnvironment.call_binop(). Для унарных операторов вместо этого необходимо использовать атрибуты и методы unary.

По умолчанию реализация SandboxedEnvironment.call_binop будет использовать SandboxedEnvironment.binop_table для перевода символов операторов в обработчики, выполняющие стандартное поведение операторов.

В этом примере показано, как можно отключить оператор «степень» (**) в Jinja2:

from jinja2.sandbox import SandboxedEnvironment


class MyEnvironment(SandboxedEnvironment):
    intercepted_binops = frozenset(['**'])

    def call_binop(self, context, operator, left, right):
        if operator == '**':
            return self.undefined('the power operator is unavailable')
        return SandboxedEnvironment.call_binop(self, context,
                                               operator, left, right)

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