Настройка экранирования для шаблонов Jinja

Начиная с Jinja-2.9, расширение autoescape удалено и встроено в модуль. Однако автоматического экранирования еще не включено по умолчанию и рекомендуется настроить для него разумное значение по умолчанию. Это позволяет включать и отключать автоматическое экранирование для каждого шаблона (например, HTML вместо текста).

Содержание:

• Назначение функции jinja2.select_autoescape().
• Отключение экранирования некоторых HTML-элементов в шаблонах.
• Работа с экранированием HTML в ручную.

Назначение функции jinja2.select_autoescape().

Синтаксис:

import jinja2

jinja2.select_autoescape(enabled_extensions=('html', 'htm', 'xml'), 
                                         disabled_extensions=(), 
                                         default_for_string=True, 
                                         default=False)

Параметры:

• enabled_extensions=('html', 'htm', 'xml') - список всех расширений файлов шаблонов, для которых включено автоматическое экранирование,
• disabled_extensions=() - список всех расширений файлов шаблонов, для которых выключено автоматическое экранирование,
• default_for_string=True - автоматическое экранирование для шаблонов, загруженных из строки,
• default=False - автоматическое экранирование по умолчанию для других шаблонов выключено.

Описание:

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

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

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

Вот рекомендуемая настройка, которая включает автоматическое экранирование для шаблонов, заканчивающихся на .html, .htm и .xml, и отключение его по умолчанию для всех других расширений.

from jinja2 import Environment, PackageLoader, select_autoescape

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

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

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

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

Отключение экранирования HTML-элементов в шаблонах.

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

1. либо в словаре контекста приложения с помощью markupsafe.Markup
2. либо в шаблоне при помощи фильтра {{ value | safe }}.

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

Если значение было экранировано, но не помечено как безопасное, автоматическое экранирование все равно будет иметь место и приведет к появлению двойных экранированных символов. Если уверены, что есть данные, которые уже являются безопасными, но не отмечены как безопасные, то использовать фильтр |safe, что бы отменить экранирование HTML.

Работа с экранированием HTML в ручную.

Если включено ручное экранирование, то ответственность за экранирование переменных, если это необходимо, лежит на пользователе. Когда нужно экранировать HTML? Если есть переменная, которая может содержать любой из следующих символов ( > ,<, & или "), то НЕОБХОДИМО экранировать ее, если только переменная не содержит хорошо сформированный и надежный HTML. Экранирование выполняется путем пропускания переменной через фильтр |e: например {{ user.username|e }}

Внутри шаблонов поведение можно временно изменить с помощью блока autoescape. При желании можно активировать и деактивировать автоэкранирование прямо из шаблонов.

Пример:

{% autoescape true %}
    Autoescaping is active within this block
{% endautoescape %}

{% autoescape false %}
    Autoescaping is inactive within this block
{% endautoescape %}

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

Примечание. В более старых версиях Jinja2 (до версии 2.9) требовалось включить эту функцию с помощью расширения. Теперь она включена по умолчанию.