Вбудовані фільтри Jinja2

Как применять фильтры к переменным.

В шаблонах Jinja2, переменные могут быть изменены фильтрами. Фильтры отделяются от переменной символом канала '|' и могут иметь необязательные аргументы в круглых скобках. Несколько фильтров могут быть объединены в цепочку. Выход одного фильтра применяется к следующему.

Например, выражение в шаблоне {{ name|striptags|title }} удалит все HTML-теги из переменной name, а так же все слова будут начинаться с заглавной буквы.

Фильтры в шаблонах jinja2 принимают левую часть выражения в качестве первого аргумента, а аргументы, передаваемые в сам фильтр служат дополнительными позиционными или ключевыми аргументами. Например, в выражении шаблона {{ lst|join(', ') }} функция фильтра join() будет вызываться с аргументами attr(lst, ', ').

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

{% filter upper %}
    Этот текст становится прописным
{% endfilter %}

Все встроенные фильтры модуля Jinja2:

• abs() возвращает абсолютное значение,

• attr() возвращает атрибут объекта по имени,

• batch() делит исходную последовательность на списки с заданным количеством элементов,

• capitalize() преобразует первый символ строки в верхний регистр,

• center() центрирует значение в поле заданной ширины,

• default() возвращает значение по умолчанию, если переменная не определена,

• dictsort() сортирует словарь,

• escape() экранирует HTML,

• filesizeformat() форматирует значение как размер файла,

• first() возвращает первый элемент списка,

• float() преобразует значение в float,

• forceescape() принудительно экранирует HTML,

• format() форматирует строку в стиле printf,

• groupby() группирует последовательность объектов по атрибуту,

• indent() делает отступы для каждой строки,

• int() преобразует значение в int,

• join() объединяет список строк в одну строку,

• last() возвращает последний элемент списка,

• length() возвращает количество элементов в контейнере,

• list() преобразует значение в список,

• lower() преобразует строку в нижний регистр,

• map() извлекает определенный атрибут из списка объектов,

• max() возвращает максимальный элемент списка,

• min() возвращает минимальный элемент списка,

• pprint() красиво печатает переменную,

• random() возвращает случайный элемент из списка,

• reject() фильтрует последовательность, исключая те элементы, для которых тест вернул True,

• rejectattr() фильтрует список объектов, исключая те объекты, для которых тест атрибута объекта вернул True,

• replace() заменяет подстроку в строке на новое значение,

• reverse() переворачивает последовательность/контейнер,

• round() округляет число до заданной точности,

• safe() отменяет автоматическое экранирование HTML,

• select() фильтрует последовательность, исключая те элементы, для которых тест вернул False,

• selectattr() фильтрует список объектов, исключая те объекты, для которых тест атрибута объекта вернул False,

• slice() делит исходную последовательность на указанное количество списков,

• sort() сортирует последовательность,

• string() преобразует строку в unicode,

• striptags() удаляет теги HTML,

• sum() возвращает сумму последовательности чисел,

• title() все слова начинаются с прописных букв,

• tojson() преобразует структуру в JSON,

• trim() удаляет начальные и конечные символы,

• truncate() возвращает усеченную копию строки,

• unique() возвращает список уникальных элементов,

• upper() преобразует строку в верхний регистр,

• urlencode() преобразует данные для использования в URL,

• urlize() преобразует текстовые URL-адреса в ссылки,

• wordcount() считает слова в строке,

• wordwrap() форматирует строку до заданной ширины,

• xmlattr() создает атрибуты HTML на основе словаря.

---

abs(x, /):

Фильтр abs() возвращает абсолютное значение аргумента..

attr(obj, name):

Фильтр attr() получает атрибут объекта obj по его имени name. Выражение шаблона {{ foo|attr("bar") }} работает так же, как foo.bar, только всегда возвращается атрибут и элементы не просматриваются.

Дополнительные сведения смотрите в разделе "Общий синтаксис шаблонов jinja2".

batch(value, linecount, fill_with=None):

Фильтр batch() делит исходный список на списки с заданным количеством элементов, и возвращает список списков. Если указан аргумент fill_with, то он используется для заполнения недостающих элементов.

Смотрим пример:

<table>
{%- for row in items|batch(3, '&nbsp;') %}
  <tr>
  {%- for column in row %}
    <td>{{ column }}</td>
  {%- endfor %}
  </tr>
{%- endfor %}
</table>

capitalize(s):

Фильтр capitalize() преобразует первый символ строки s в верхний регистр, все остальные символы будут - в нижнем регистре.

center(value, width=80):

Фильтр center() центрирует значение value в поле заданной ширины width.

default(value, default_value='', boolean=False):

Если переменная value не определена, то фильтр default() вернет значение аргумента default_value, в противном случае значение переменной value:

{{ my_variable|default('my_variable не определена') }}

Код выше выведет значение my_variable, если переменная была определена, если нет, то строку 'my_variable не определена'. Если надо использовать значение по умолчанию с переменными, которые оцениваются как False, то необходимо установить аргумент boolean=True:

{{ ''|default('the string was empty', true) }}

dictsort(value, case_sensitive=False, by='key', reverse=False):

Фильтр dictsort() сортирует словарь и возвращает парные кортежи (key, value). Так как изначально словари Python не отсортированы, этот фильтр можно использовать, чтобы упорядочить их по ключу или значению:

{% for key, value in mydict|dictsort %}
    сортирует словарь по ключу, без учета регистра

{% for key, value in mydict|dictsort(reverse=true) %}
    сортирует словарь по ключу, без учета регистра, обратный порядок

{% for key, value in mydict|dictsort(true) %}
    сортирует словарь по ключу, с учетом регистра

{% for key, value in mydict|dictsort(false, 'value') %}
    сортирует словарь по значению, без учета регистра

escape(s):

Фильтр escape() преобразует символы &, <, >, ' и ” в строках s в безопасные для HTML последовательности. Используйте фильтр, если необходимо отобразить текст, который может содержать такие символы в HTML. Помечает возвращаемое значение как Markup.

filesizeformat(value, binary=False):

Фильтр filesizeformat() форматирует значение как удобочитаемый размер файла (например, 13 KB; 4,1 MB; 102 bytes и т. д.).

По умолчанию используются десятичные префиксы (Mega, Giga и т. д.), Если второй параметр имеет значение True, используются двоичные префиксы (Mebi, Gibi).

first(seq):

Фильтр first() возвращает первый элемент последовательности..

float(value, default=0.0):

Фильтр float() преобразует значение value в число с плавающей запятой. Если преобразование невозможно, то возвращается 0,0. Можно изменить это значение по умолчанию.

forceescape(value):

Фильтр forceescape() принудительно экранирует HTML. Если HTML-разметка уже имеет HTML-сущности, то применение этого фильтра, повторно экранирует HTML-сущности.

format(value, *args, **kwargs):

Фильтр format() применяет заданные значения к строке формата в стиле printf, например string % values.

{{ "%s, %s!"|format(greeting, name) }}
Hello, World!

В большинстве случаев, в шаблонах, удобнее и эффективнее использовать оператор % или str.format().

{{ "%s, %s!" % (greeting, name) }}
{{ "{}, {}!".format(greeting, name) }}

groupby(value, attribute):

Фильтр groupby() группирует последовательность объектов по атрибуту с помощью Python itertools.groupby(). Атрибут может использовать точечную нотацию для вложенного доступа, например 'address.city'. В отличие от Python itertools.groupby(), значения сортируются первыми, поэтому для каждого уникального значения возвращается только одна группа.

Например, список объектов User с атрибутом city может отображаться в группах. В этом примере grouper относится к значению city в группе.

<ul>{% for city, items in users|groupby("city") %}
  <li>{{ city }}
    <ul>{% for user in items %}
      <li>{{ user.name }}
    {% endfor %}</ul>
  </li>
{% endfor %}</ul>

Фильтр groupby() возвращает [именованный кортеж] (grouper, list), который можно использовать вместо распаковки кортежей, описанной выше.

• grouper - это значение атрибута,

• list - это элементы с этим значением.

<ul>{% for group in users|groupby("city") %}
  <li>{{ group.grouper }}: {{ group.list|join(", ") }}
{% endfor %}</ul>

indent(s, width=4, first=False, blank=False, indentfirst=None):

Фильтр indent() возвращает копию строки s с отступом в 4 пробела для каждой строки. По умолчанию первая строка и пустые строки не имеют отступа.

Аргументы фильтра:

• width – Количество пробелов, на которые нужно сделать отступ.

• first – Не пропускает отступ в первой строке.

• blank – Не пропускает отступы в пустых строках.

int(value, default=0, base=10):

Фильтр int() преобразует значение в целое число. Если преобразование невозможно, то возвращается 0. Можно изменить это значение по умолчанию. Можно также переопределить базу по умолчанию (10) аргументом base, который обрабатывает ввод с такими префиксами, как 0b, 0o и 0x для оснований 2, 8 и 16 соответственно. База игнорируется для десятичных чисел и не строковых значений.

join(value, d='', attribute=None):

Фильтр join() возвращает строку, которая является конкатенацией строк в последовательности value.

Разделитель между элементами представляет собой пустую строку по умолчанию, можно определить ее с помощью необязательного параметра d:

{{ [1, 2, 3]|join('|') }}
    -> 1|2|3

{{ [1, 2, 3]|join }}
    -> 123

Также возможно объединение определенных атрибутов объекта:

{{ users|join(', ', attribute='username') }}

last(seq):

Фильтр last() возвращает последний элемент последовательности seq.

Примечание: не работает с генераторами. Его можно явно преобразовать в список:

{{ data | selectattr('name', '==', 'Jinja') | list | last }}

length(obj, /):

Фильтр length() возвращает количество элементов в контейнере.

list(value):

Фильтр list() преобразует значение value в список. Если это была строка, то возвращаемый список будет списком символов строки.

lower(s):

Фильтр lower() преобразует значение value в нижний регистр.

map(*args, **kwargs):

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

Основное использование - отображение атрибута. Представьте, что есть список пользователей, но необходимо извлечь только список имен пользователей:

Пользователи на этой странице: {{ users|map(attribute='username')|join(', ') }}

Можно указать значение по умолчанию, которое будет использоваться, если объект в списке не имеет данного атрибута.

{{ users|map(attribute="username", default="Anonymous")|join(", ") }}

В качестве альтернативы можно позволить ему вызывать фильтр, передав впоследствии имя фильтра и аргументы. Хорошим примером может быть применение фильтра преобразования текста к последовательности:

Пользователи на этой странице: {{ titles|map('lower')|join(', ') }}

Аналогично выражению-генератора, такому как:

(u.username for u in users)
(u.username or "Anonymous" for u in users)
(do_lower(x) for x in titles)

Изменено в версии 2.11.0: Добавлен параметр по умолчанию.

max(value, case_sensitive=False, attribute=None):

Фильтр max() возвращает самый большой элемент из последовательности.

{{ [1, 2, 3]|max }}
    -> 3

Аргументы фильтра:

• case_sensitive – рассматривает строки верхнего и нижнего регистра как отдельные.

• attribute – получает объект с максимальным значением этого атрибута.

min(value, case_sensitive=False, attribute=None):

Фильтр min() возвращает самый маленький элемент из последовательности.

возвращает{{ [1, 2, 3]|min }}-> 1```

Аргументы фильтра:

• case_sensitive – рассматривает строки верхнего и нижнего регистра как отдельные.

• attribute – получает объект с максимальным значением этого атрибута.

pprint(value, verbose=False):

Фильтр pprint() красиво печатает переменную value. Полезно для отладки.

random(seq):

Фильтр random() возвращает случайный элемент из последовательности seq.

reject(*args, **kwargs):

Фильтр reject() фильтрует последовательность объектов, применяя тест к каждому объекту и отклоняя объекты при успешном выполнении теста.

Если тест не указан, каждый объект будет оцениваться как логическое значение.

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

{{ numbers|reject("odd") }}

Работает подобно выражению-генератора, например:

(n for n in numbers if not test_odd(n))

rejectattr(*args, **kwargs):

Фильтр rejectattr() фильтрует последовательность объектов, применяя тест к указанному атрибуту каждого объекта и отклоняя объекты при успешном завершении теста.

Если тест не указан, то значение атрибута будет оцениваться как логическое.

{{ users|rejectattr("is_active") }}
{{ users|rejectattr("email", "none") }}

Работает подобно выражению-генератора, например:

(u for user in users if not user.is_active)
(u for user in users if not test_none(user.email))

replace(s, old, new, count=None):

Фильтр replace() возвращает копию строки s со всеми вхождениями old, замененными на new. Аргумент old - это подстрока, которую следует заменить, new - строка замены. Если указан необязательный аргумент count, то заменяются только count первых вхождений:

{{ "Hello World"|replace("Hello", "Goodbye") }}
    -> Goodbye World

{{ "aaaaargh"|replace("a", "d'oh, ", 2) }}
    -> d'oh, d'oh, aaargh

reverse(value):

Фильтр reverse() переворачивает объект или возвращает [итератор][t-iterator], который повторяет его в обратном порядке.

round(value, precision=0, method='common'):

Фильтр round() округляет число до заданной точности. Аргумент precision указывает точность (по умолчанию 0), а method - метод округления (по умолчанию 'common'):

• 'common': округляет либо вверх, либо вниз.

• 'ceil': всегда округляет вверх.

• 'floor': всегда округляет вниз.

{{ 42.55|round }}
    -> 43.0
{{ 42.55|round(1, 'floor') }}
    -> 42.5

Обратите внимание, что даже при округлении до точности 0 возвращается число float. Если необходим получить целое число, то пропустите его через фильтр int:

{{ 42.55|round|int }}
    -> 43

safe(value):

Фильтр safe() отмечает значение value как безопасное. Это означает, что в [среде Environment][jinja2.Environment] с включенным автоматическим экранированием переменная value не будет экранирована.

select(*args, **kwargs):

Фильтр select() фильтрует последовательность объектов, применяя тест к каждому объекту и выбирая только те объекты, которые прошли его успешно.

Если тест не указан, то каждый объект будет оцениваться как логическое значение.

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

{{ numbers|select("odd") }}
{{ numbers|select("divisibleby", 3) }}
{{ numbers|select("lessthan", 42) }}
{{ strings|select("equalto", "mystring") }}

Работает подобно выражению-генератора, например:

(n for n in numbers if test_odd(n))
(n for n in numbers if test_divisibleby(n, 3))

selectattr(*args, **kwargs):

Фильтр selectattr() фильтрует последовательность объектов, применяя тест к указанному атрибуту каждого объекта и выбирая только те объекты, которые прошли его успешно.

Если тест не указан, то значение атрибута будет оцениваться как логическое.

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

{{ users|selectattr("is_active") }}
{{ users|selectattr("email", "none") }}

Работает подобно выражению-генератора, например:

(u for user in users if user.is_active)
(u for user in users if test_none(user.email))

slice(value, slices, fill_with=None):

Фильтр slice() делит последовательность на slices списков и возвращает список списков, содержащих эти элементы. Полезно, если нужно создать <div>, содержащий три тега <ul>, представляющих столбцы:

<div class="columnwrapper">
  {%- for column in items|slice(3) %}
    <ul class="column-{{ loop.index }}">
    {%- for item in column %}
      <li>{{ item }}</li>
    {%- endfor %}
    </ul>
  {%- endfor %}
</div>

Аргумент fill_with используется для заполнения отсутствующих значений на последней итерации.

sort(value, reverse=False, case_sensitive=False, attribute=None):

Фильтр sort() сортирует итерацию с помощью функции Python [sorted()][f-sorted].

{% for city in cities|sort %}
    ...
{% endfor %}

Аргументы фильтра sort:

• reverse – сортировка по убыванию.

• case_sensitive – при сортировке строк сортирует верхний и нижний регистр отдельно.

• attribute – при сортировке объектов или словарей используется атрибут или ключ для сортировки. Можно использовать точечную нотацию, например "address.city". Может быть список атрибутов, таких как "age,name".

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

{% for user in users|sort(attribute="name")
    |sort(reverse=true, attribute="age") %}
    ...
{% endfor %}

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

{% for user users|sort(attribute="age,name") %}
    ...
{% endfor %}

Изменено в версии 2.11.0: Параметр атрибута может представлять собой разделенный запятыми список атрибутов, например "age,name".

string(object):

Фильтр string() преобразует строку в unicode, если она еще не преобразована. Таким образом, строка разметки не преобразуется обратно в unicode.

striptags(value):

Фильтр striptags() удаляет теги SGML/XML и замените соседние пробелы одним пробелом.

sum(iterable, attribute=None, start=0):

Фильтр sum() возвращает сумму последовательности чисел плюс значение аргумента start (по умолчанию 0). Когда последовательность пуста, возвращается значение start.

Также можно суммировать только определенные атрибуты:

Total: {{ items|sum(attribute='price') }}

title(s):

Фильтр title() возвращает версию строки, в которой все слова начинаются с прописных букв, все остальные символы будут строчными.

tojson(value, indent=None):

Фильтр tojson() преобразует структуру в JSON, чтобы ее можно было безопасно использовать в тегах <script>. Фильтр возвращает строку JSON. Обратите внимание, что это доступно в шаблонах через фильтр | tojson, который также пометит результат как безопасный. Благодаря тому, как этот фильтр экранирует определенные символы, результат безопасен, даже если используется вне тегов <script>.

Следующие символы экранируются в строках: <, >,&,'`. Это делает безопасным встраивание таких строк в любое место HTML, за исключением атрибутов, заключенных в двойные кавычки. В этом случае одиночные кавычки для атрибутов или HTML дополнительно экранируют его.

Аргумент indent можно использовать для включения красивой печати и устанавливает количество пробелов, для отступов структуры.

Обратите внимание, что этот фильтр предназначен для использования только в контексте HTML.

trim(value, chars=None):

Фильтр trim() удаляет начальные и конечные символы, по умолчанию - пробелы.

truncate(s, length=255, killwords=False, end='...', leeway=None):

Фильтр truncate() возвращает усеченную копию строки s. Длина указывается в аргументе length, который по умолчанию равен 255. Если значение аргумента killwords=True, то фильтр будет обрезать текст по длине. В противном случае последнее слово будет отброшено. Если текст действительно был усечен, то к нему будет добавлено многоточие (...). Если нужен другой знак, вместо многоточия ..., то можно указать его с помощью аргумента end. Строки, длина которых превышают допустимый предел leeway, усечены не будут.

{{ "foo bar baz qux"|truncate(9) }}
    -> "foo..."
{{ "foo bar baz qux"|truncate(9, True) }}
    -> "foo ba..."
{{ "foo bar baz qux"|truncate(11) }}
    -> "foo bar baz qux"
{{ "foo bar baz qux"|truncate(11, False, '...', 0) }}
    -> "foo bar..."

Свободное пространство leeway по умолчанию в новых версиях Jinja равно 5, а раньше было 0, но его можно перенастроить глобально.

unique(value, case_sensitive=False, attribute=None):

Фильтр unique() возвращает список уникальных элементов из заданного итеративного объекта.

{{ ['foo', 'bar', 'foobar', 'FooBar']|unique|list }}
    -> ['foo', 'bar', 'foobar']

Уникальные элементы выдаются в том же порядке, что и их первое вхождение в итерации, переданной фильтру.

Аргументы фильтра unique:

• case_sensitive – рассматривает строки верхнего и нижнего регистра как разные.

• attribute – фильтрует объекты с уникальными значениями для этого атрибута.

upper(s):

Фильтр upper() преобразует значение в верхний регистр.

urlencode(value):

Фильтр urlencode() цитирует данные value для использования в URL или запросе с использованием UTF-8.

Фильтр представляет собой обертку для [urllib.parse.quote()][urllib.parse.quote], если value это строка или [urllib.parse.urlencode()][urllib.parse.urlencode] для словаря или последовательности.

Аргумент value – данные для цитирования. Строка будет заключена в кавычки напрямую. Словари dict или последовательности кортежей (key, value) будут объединены в строку запроса.

Если в строке встречаются косые черты, то '/' не заключается в кавычки. HTTP - серверы обрабатывают '/' и '%2F' в путях эквивалентно. Если нужны косые черты в кавычках, то дополнительно используйте фильтр |replace("/", "%2F").

urlize(value, trim_url_limit=None, nofollow=False, target=None, rel=None):

Фильтр urlize() преобразует URL-адреса в виде обычного текста в кликабельные ссылки.

Если вы передадите фильтру дополнительное целое число trim_url_limit, то он сократит URL-адрес до этого числа. Также существует аргумент nofollow, который добавляет rel='nofollow':

{{ mytext|urlize(40, true) }}
    Ссылки сокращаются до 40 символов и определяются с помощью rel='nofollow'

Если указан target, то атрибут target будет добавлен в тег <a>:

{{ mytext|urlize(40, target='_blank') }}

wordcount(s):

Фильтр wordcount() считает слова в этой строке.

wordwrap(s, width=79, break_long_words=True, wrapstring=None, break_on_hyphens=True):

Фильтр wordwrap() форматирует строку до заданной ширины. Существующие символы новой строки обрабатываются как абзацы, которые нужно переносить отдельно.

Аргументы фильтра wordwrap:

• s – Исходный текст для обертывания

• width – Максимальная длина для переноса строк.

• break_long_words – Если слово длиннее ширины, то оно будет разделено и часть перенесется на другую строку.

• break_on_hyphens – Если слово содержит дефис, оно может быть разделено на несколько строк.

• wrapstring – Строка для присоединения к каждой обернутой строке. По умолчанию [Environment.newline_sequence][jinja2.Environment].

Изменено в версии 2.11: существующие символы новой строки обрабатываются как отдельные абзацы.

Изменено в версии 2.11: Добавлен параметр break_on_hyphens.

xmlattr(d, autospace=True):

Фильтр xmlattr() создает строку атрибута SGML/XML на основе элементов словаря dict. Все значения, которые не равны ни none, ни undefined, автоматически экранируются:

<ul{{ {'class': 'my_list', 'missing': none,
        'id': 'list-%d'|format(variable)}|xmlattr }}>
...
</ul>

В результате получается что-то вроде этого:

<ul class="my_list" id="list-42">
...
</ul>

Как видно из примера, если фильтр что-то возвращает, то он автоматически добавляет пробел перед элементом, если только аргумент autospace не равен False.