Перейти на сайт

Фильтры в Jinja

Применение фильтров для более удобной работы с шаблонизатором

Для удобной работы с данными в Jinja можно использовать фильтры. Фильтры — это функции, которые применяются к вашим данным определенным образом:

  • Принимают ваши данные и возвращают их измененными.
  • Не изменяют исходные данные, ваши данные остаются целыми и корректными.

Синтаксис фильтров

Чтобы применить фильтр к переменной или структуре данных, используйте символ вертикальной черты — | , а затем укажите нужный фильтр. Вертикальную черту можно понимать как "так, чтобы".

Пример

Фильтр upper принимает строку и возвращает её в верхнем регистре.

{{ user["$name"] | upper }}

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

Фильтры и аргументы

Фильтры в Jinja работают как функции и принимают как минимум один аргумент. Первый аргумент — это значение перед символом вертикальной черты | . Дополнительные аргументы указываются в круглых скобках после имени фильтра. Если дополнительных аргументов нет, скобки можно не использовать.

Пример фильтра без дополнительных аргументов:

{{ "orange" | upper }}  {# Выведет "ORANGE" #}
{{ "orange" | upper() }}  {# Тоже выведет "ORANGE" #}

Пример фильтра с дополнительными аргументами

Фильтр replace  принимает строку и два символа для замены:

{{ "apple" | replace('p', 'b') }}  {# Выведет "abble" #}

Если не указать аргументы, будет ошибка:

{{ "apple" | replace }}  {# Ошибка, так как отсутствуют аргументы #}

Генераторы и списки

Фильтры, работающие со списками, создают объекты типа Generator. Чтобы преобразовать их обратно в списки, используйте фильтр list .

{% set arr = [1, 2, 3] %}
{% set arr = arr | batch(1) %}

{# Печатает объект-генератор #}
{{ arr }}

{# Преобразует в список и печатает #}
{{ arr | list }}

Строковые фильтры и нестроковые переменные

Строковые фильтры преобразуют нестроковые переменные в строки.

{% set o = ['b1', 'a1', 'c1'] %}
{{ 'Длина списка: ' ~ o | count }}  {# Выведет "Длина списка: 3" #}

{% set o = o | join(', ') | upper %}
{{ 'Длина строки: ' ~ o | count }}  {# Выведет "Длина строки: 14" #}

Цепочка фильтров в Jinja

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

{{ "apple" | upper | replace('P', 'b') }}  {# Выведет "AbbLE" #}
{{ "apple" | replace('P', 'b') | upper }}  {# Выведет "APPLE" #}

Доступные фильтры

center(value, width=80) 

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

{{ "apple" | center(10) }} {# Выведет "  apple   " #}


capitalize(value)

Делает первый символ строки заглавным, остальные строчными.

{{ "orange" | capitalize }}  {# Выведет "Orange" #}


escape(value) или e(value) 

Преобразует специальные символы в строке в безопасные HTML-последовательности.

forceescape(value)

Похоже на escape(), но также экранирует вывод макросов.

format(value, *args, **kwargs)

Форматирует строку с использованием старого форматирования Python (% ).

hash(value, hash_fn, input_encoding='utf-8', output_encoding='hex')

Хеширует строки с помощью различных алгоритмов. Параметры:

  • value : строка, которую нужно хешировать.
  • hash_fn : тип хеша (например, 'md5', 'sha1', 'sha224', 'sha256', 'sha384', 'sha512').
  • input_encoding(необязательно): кодировка входной строки (по умолчанию 'utf-8').
  • output_encoding (необязательно): кодировка выходной строки (по умолчанию 'hex', также поддерживается 'base64')

hmac(key, message, hash_fn, input_encoding='utf-8', output_encoding='hex')

Создаёт HMAC (кода аутентификации сообщений на основе хеша) с использованием различных алгоритмов. Параметры:

  • key : строка, используемая в качестве ключа.
  • message : строка сообщения, которое нужно аутентифицировать.
  • hash_fn : тип хеша (например, 'md5', 'sha1', 'sha224', 'sha256', 'sha384', 'sha512').
  • input_encoding  (необязательно): кодировка входных строк (по умолчанию 'utf-8').
  • output_encoding (необязательно): кодировка выходной строки (по умолчанию 'hex', также поддерживается 'base64').

indent(value, width=4, first=False, blank=False)

Добавляет отступы к каждой строке. Параметры:

  • width : количество пробелов для отступа во всех строках, кроме первой.
  • first : отступ первой строки.
  • blank : отступ пустых строк.
{% set text = "Line 1\nLine 2\nLine 3" %}
{{ text | indent(width=4, first=False) }}

{# Выведет:
Line 1
    Line 2
    Line 3
#}


lower(value)

Преобразует строку в нижний регистр.

{{ "Hello, World!" | lower }}  {# Выведет "hello, world!" #}


pprint(value, verbose=False) 

Красиво выводит переменную, полезно для отладки.

{{ {"name": "Alice", "age": 30, "hobbies": ["reading", "hiking"]} | pprint }}

{# Выведет:
{
    'age': 30,
    'hobbies': ['reading', 'hiking'],
    'name': 'Alice'
}
#}


replace(value, old, new, count=None) 

Заменяет все или указанное количество вхождений подстроки в строке. Этот фильтр также позволяет удалить вхождение одного символа, если в качестве второго аргумента указать пустую строку.

{{ "apple" | replace('p', 'b') }}  {# Выведет "abble" #}


title(value) 

Преобразует строку в формат заглавных букв (каждое слово с заглавной буквы).

{{ "hello, world!" | title }}  {# Выведет "Hello, World!" #}


trim(value)

Удаляет начальные и конечные пробелы в строке.

{{ "   Hello, World!   " | trim }}  {# Выведет "Hello, World!" #}


slice(value)

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

{{ "hello world" | slice(1, 5) }}  {# Выведет "ello" #}

{{ "abcdefg" | slice(0, None, 2) }}  {# Выведет "aceg" #}


striptags(value)

Удаляет теги SGML/XML из строки.

{{ "Hello <b>world</b>" | striptags }}  {# Выведет "Hello world" #}


truncate(value, length=255, killwords=False, end='...')

Обрезает строку до заданного количества символов. Параметры:

  • length : длина строки.
  • killwords : обрезка по словам.
  • end : строка, добавляемая в конец обрезанной строки.
{{ "hello world" | truncate(5) }}  {# Выведет "hello..." #}


upper(value) 

Преобразует строку в верхний регистр.

{{ "orange" | upper }}  {# Выведет "ORANGE" #}


urlencode(value) 

Кодирует строку для использования в URL.

{{ "Hello, World!" | urlencode }}  {# Выведет "Hello%2C%20World%21" #}


wordwrap(value, width=79, break_long_words=True, wrapstring=None) 

Разбивает строку на строки длиной width символов. Параметры:

  • width : длина строки.
  • break_long_words : разбивать длинные слова.
  • wrapstring : строка для замены новой строки.


Подробнее о фильтре format

Фильтр format  позволяет подставлять значения в строку. Это работает так же, как оператор %  в Python.

Использование с позиционными аргументами (args ):

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

{{ "Hello, %s!" | format("world") }} 
{# Выведет "Hello, world!" #}

Использование с именованными аргументами (kwargs ):

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

{{ "Hello, %(name)s!" | format(name="world") }} 
{# Выведет "Hello, world!" #}

Важно! Jinja не поддерживает форматирование переменных напрямую из словаря. Вместо этого используйте именованные аргументы.

Пример с позиционными аргументами:

{{ "Hello, %s %s!" | format("John", "Doe") }}
{# Выведет "Hello, John Doe!" #}

Пример с именованными аргументами:

{{ "Hello, %(first_name)s %(last_name)s!" | format(first_name="John", last_name="Doe") }}
{# Выведет "Hello, John Doe!" #}

Фильтры для работы с числами

abs(число)

Возвращает абсолютное значение числа.

 {{ -5 | abs }} {# Выведет "5" #}

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

Округляет число до заданной точности. Параметры:

  • точность  (необязательно): количество знаков после запятой (по умолчанию 0).
  • метод  (необязательно): метод округления (по умолчанию 'common').

Методы округления:

  • 'common' : округляет либо вверх, либо вниз (обычное округление).
  • 'ceil' : всегда округляет вверх.
  • 'floor' : всегда округляет вниз.
{{ 3.14159 | round(2) }} {# Выведет "3.14" #}
{{ 3.14159 | round(2, 'ceil') }} {# Выведет "3.15" #}
{{ 3.14159 | round(2, 'floor') }} {# Выведет "3.14" #}

Фильтры, которые изменяют итерируемые объекты

Итерируемые объекты — это списки, кортежи, строки и словари.

Фильтры для выбора одного элемента из итерируемого объекта

attr(Object, name) 

Получает значение атрибута объекта.
Параметры: Любой объект, имя атрибута (строка).

{{ foo | attr("bar") }}  {# Работает как foo.bar #}

Примечание: Не используется для получения значений словаря по ключам или элементов списка/кортежа/строки по индексу.

first(Iterable) 

Возвращает первый элемент итерируемого объекта.

{{ [1, 2, 3] | first }}  {# Выведет 1 #}


last(Iterable) 

Возвращает последний элемент итерируемого объекта.

{{ [1, 2, 3] | last }}  {# Выведет 3 #}


random(Iterable)

Возвращает случайный элемент итерируемого объекта.

{{ [1, 2, 3] | random }}  {# Выведет случайный элемент, например, 2 #}


Фильтры для изменения содержимого итерируемых объектов

batch(value, batchSize, fill_with=None) 

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

{{ [1, 2, 3, 4, 5] | batch(2) }}  {# Выведет [[1, 2], [3, 4], [5]] #}


slice(value, slices, fill_with=None)

Делит итерируемый объект на заданное количество частей.
Параметры: Итерируемое значение, количество частей, необязательное значение для заполнения.

{{ [1, 2, 3, 4, 5] | slice(2) }}  {# Выведет [[1, 2, 3], [4, 5]] #}


map(attribute) 

Ищет атрибут для каждого элемента из списка.

{{ users | map(attribute='name') }}  {# Выведет список имен всех пользователей #}

Фильтры для создания подмножеств из итерируемых объектов

map(filter) 

Применяет фильтр к каждому элементу списка.

{{ ["apple", "banana"] | map("upper") }}  {# Выведет ["APPLE", "BANANA"] #}


rejectattr(attribute, test, *testArgs) 

Отклоняет элементы, где атрибут проходит тест.
Параметры: Атрибут (строка), тест, аргументы для теста.

{{ users | rejectattr("is_active", "equalto", True) }}  {# Выведет пользователей, у которых is_active не равен True #}


select(test, *testArgs) 

Выбирает элементы, прошедшие тест.
Параметры: Тест, аргументы для теста.

{{ [1, 2, 3, 4] | select("odd") }}  {# Выведет [1, 3] #}


selectattr(attribute, test, *testArgs)

Выбирает элементы, у которых атрибут проходит тест.
Параметры: Атрибут (строка), тест, аргументы для теста.

{{ users | selectattr("is_active", "equalto", True) }}  {# Выведет только активных пользователей #}

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


unique(value) 

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

{{ [1, 2, 2, 3] | unique }}  {# Выведет [1, 2, 3] #}

Фильтры для изменения порядка итерируемых объектов

reverse(value)

Изменяет порядок элементов на обратный.

{{ [1, 2, 3] | reverse }}  {# Выведет [3, 2, 1] #}


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

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

Обычная сортировка:

{{ [3, 1, 2] | sort }}  {# Выведет [1, 2, 3] #}

Обратная сортировка:

{{ [3, 1, 2] | sort(reverse=True) }}  {# Выведет [3, 2, 1] #}

Сортировка строк с учетом регистра:

{{ ["apple", "Banana", "cherry"] | sort(case_sensitive=True) }}
{# Выведет ["Banana", "apple", "cherry"] #}

Сортировка по атрибуту:

{{ users | sort(attribute="age") }}  
{# Выведет пользователей, отсортированных по возрасту #}

Фильтры для изменения типов данных

 float(value, default=0.0) 

Преобразует значение в число с плавающей точкой.
Параметры: Любое значение, необязательное значение по умолчанию.

{{ "3.14" | float }}  {# Выведет 3.14 #}
{{ "abc" | float(1.23) }}  {# Выведет 1.23 #}

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

Преобразует значение в целое число.
Параметры: Любое значение, необязательное значение по умолчанию, основание.

{{ "42" | int }}  {# Выведет 42 #}
{{ "0x2A" | int(base=16) }}  {# Выведет 42 #}
{{ "abc" | int(7) }}  {# Выведет 7 #}

string(value)

Преобразует значение в строку Unicode

{{ 123 | string }}  {# Выведет "123" #}

list(value)

Преобразует итерируемое значение в список.

{{ "abc" | list }}  {# Выведет ["a", "b", "c"] #}
{{ {"a": 1, "b": 2} | list }}  {# Выведет ["a", "b"] #}}

safe(value)

Отмечает значение как безопасное

{{ "<div>Hello</div>" | safe }}  {# Выведет <div>Hello</div> #}

Фильтры для преобразования данных между типами

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

Возвращает значение, если оно определено, иначе значение по умолчанию. Параметры: Любое значение, значение по умолчанию, флаг для учета пустых строк и None.

{{ my_variable | default("не определено") }}  {# Выведет "не определено", если my_variable не определена #}

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

Сортирует словарь и возвращает список кортежей пар (ключ, значение).
Параметры: Словарь, флаг чувствительности к регистру, сортировка по ключу или значению.

{{ {"b": 1, "a": 2} | dictsort }}  {# Выведет [("a", 2), ("b", 1)] #}

filesizeformat(value, binary=False)

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

{{ 1024 | filesizeformat }}  {# Выведет "1.0 KB" #}
{{ 1048576 | filesizeformat(binary=True) }}  {# Выведет "1.0 MiB" #}

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

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

{{ ["a", "b", "c"] | join(", ") }}  {# Выведет "a, b, c" #}

length(value) 

Возвращает количество элементов в итерируемом объекте.

{{ [1, 2, 3] | length }}  {# Выведет 3 #}

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

Возвращает сумму чисел в последовательности плюс значение параметра start. Параметры: Итерируемый объект, необязательный атрибут (строка), начальное значение (целое число).

Сумма чисел в списке:

{{ [1, 2, 3] | sum }}  {# Выведет 6 #}

Сумма чисел в списке с начальным значением:

{{ [1, 2, 3] | sum(start=10) }}  {# Выведет 16 #}

Сумма значений атрибута в списке объектов:

{{ items | sum(attribute='price') }}
{# Суммирует значения атрибута 'price' каждого элемента в items #}


wordcount(value)  

Подсчитывает количество слов в строк

{{ "Hello world" | wordcount }}  {# Выведет 2 #}


xmlattr(value, autospace=True) 

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

{{ {"id": "123", "class": "button"} | xmlattr }}
{# Выведет 'id="123" class="button"' #}


Другие статьи про Jinja:

Базовый синтаксис Jinja
Структура данных в Jinja
Персонализация с помощью Jinja

Работает на