Jinja2

Jinja2 — это шаблонизатор для языка программирования Python, реализованный на чистом Python и распространяемый под лицензией BSD. Он предназначен для генерации текстовых файлов (HTML, XML, JSON, LaTeX, исходного кода и других) на основе шаблонов — текстовых файлов, содержащих статическое содержимое и специальные конструкции (переменные, выражения, теги, фильтры), которые обрабатываются движком и заменяются на динамические данные. Jinja2 является одним из наиболее популярных шаблонизаторов в экосистеме Python, широко используется в веб-фреймворках (например, Flask, Django, FastAPI, Pyramid) и в инструментах генерации статических сайтов (например, Pelican, Lektor), а также в системах автоматизации (Ansible, SaltStack) и других приложениях, где требуется отделение логики представления от бизнес-логики.

История

Jinja2 был создан Армином Ронахером (Armin Ronacher) как форк и переработка шаблонизатора Django Template Language. Первоначально проект назывался «Jinja» (японское «дзиндзя» — храм синто), но после переработки архитектуры и добавления новых возможностей в 2008 году вышла версия 2.0, получившая название Jinja2. Основные цели разработки: повышение производительности, гибкости и расширяемости по сравнению с оригинальным шаблонизатором Django, а также обеспечение полной совместимости с Python 2 и 3. С тех пор Jinja2 активно развивается сообществом, поддерживается проектом Pallets (также основанным Ронахером), который включает в себя Flask, Click, Werkzeug и другие библиотеки. Последняя стабильная версия на начало 2024 года — 3.1.x.

Архитектура и принципы работы

Jinja2 работает по следующей схеме:

1. Загрузка шаблона: Шаблон загружается из файла, строки, потока или другого источника с помощью загрузчика (loader). Встроенные загрузчики: FileSystemLoader (из файловой системы), PackageLoader (из пакетов Python), DictLoader (из словаря), FunctionLoader (из функции) и другие.
2. Компиляция: Шаблон компилируется в байт-код Python (или в абстрактное синтаксическое дерево — AST) при первом использовании. Компиляция включает синтаксический анализ, оптимизацию и генерацию выполняемого кода. Результат кэшируется для повышения производительности.
3. Рендеринг: Скомпилированный шаблон выполняется с переданным контекстом — словарём, содержащим переменные и функции. Движок подставляет значения, выполняет управляющие конструкции (циклы, условия) и применяет фильтры. Результат — строка или поток байтов.

Синтаксис

Jinja2 использует три основных типа синтаксических конструкций, заключённых в фигурные скобки:

Переменные и выражения

Вывод значения переменной или результата выражения:

``jinja2 {{ variable }} {{ user.name }} {{ items | length }} {{ 2 + 3 * 5 }} ``

Теги (управляющие конструкции)

Теги задают логику шаблона: циклы, условия, макросы, блоки наследования, включения других шаблонов и т.д. Они заключаются в {% %}.

```jinja2 {% if user.is_authenticated %} Добро пожаловать, {{ user.name }}! {% else %} Пожалуйста, войдите. {% endif %}

{% for item in items %} <li>{{ item }}</li> {% endfor %} ```

Комментарии

Комментарии не выводятся в результат:

``jinja2 {# Это комментарий #} ``

Фильтры

Фильтры применяются к переменным или выражениям для преобразования значения. Они разделяются символом | и могут принимать аргументы:

``jinja2 {{ name | upper }} {{ text | truncate(50) }} {{ date | date('Y-m-d') }} {{ list | join(', ') }} {{ value | default('по умолчанию') }} ``

Встроенные фильтры: capitalize, lower, title, trim, striptags, escape, safe, length, sort, reverse, map, select, reject, first, last, random, batch, slice, format, replace, wordcount, urlencode, jsonify и другие. Пользователь может добавлять собственные фильтры.

Тесты

Тесты проверяют значение на соответствие условию и возвращают True или False. Используются в конструкциях {% if %} и {% elif %}:

``jinja2 {% if user is defined %} {% if value is number %} {% if name is string %} {% if items is iterable %} ``

Встроенные тесты: defined, undefined, none, boolean, integer, float, string, mapping, sequence, iterable, callable, sameas, escaped, eq, ne, lt, gt, le, ge, in, between и другие.

Основные возможности

Наследование шаблонов

Один из ключевых механизмов Jinja2 — наследование. Базовый шаблон определяет общую структуру (например, каркас HTML-страницы) с блоками ({% block %}), которые могут быть переопределены в дочерних шаблонах. Это позволяет избежать дублирования кода и упрощает поддержку.

Базовый шаблон (base.html): ``html <!DOCTYPE html> <html> <head> <title>{% block title %}Мой сайт{% endblock %}</title> </head> <body> <header>{% block header %}{% endblock %}</header> <main>{% block content %}{% endblock %}</main> <footer>{% block footer %}&copy; 2024{% endblock %}</footer> </body> </html> ``

Дочерний шаблон (page.html): ``jinja2 {% extends "base.html" %} {% block title %}Главная страница{% endblock %} {% block content %} <h1>Добро пожаловать!</h1> <p>Содержимое страницы.</p> {% endblock %} ``

Включение (include)

Позволяет вставить содержимое другого шаблона в текущий:

``jinja2 {% include "header.html" %} {% include "footer.html" ignore missing %} ``

Макросы

Макросы — это аналог функций в шаблонах. Они позволяют переиспользовать фрагменты кода с параметрами:

```jinja2 {% macro input(name, value='', type='text', size=20) %} <input type="{{ type }}" name="{{ name }}" value="{{ value }}" size="{{ size }}"> {% endmacro %}

{{ input('username') }} {{ input('password', type='password') }} ```

Макросы могут быть импортированы из других шаблонов.

Автоматическое экранирование

По умолчанию Jinja2 автоматически экранирует HTML-спецсимволы (<, >, &, ", ') в выводимых переменных, что предотвращает XSS-атаки. Экранирование можно отключить с помощью фильтра safe или глобальной настройки autoescape = False.

Песочница (Sandbox)

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

Кэширование

Результат компиляции шаблона кэшируется в памяти (по умолчанию) или в файловой системе. Это значительно ускоряет рендеринг при многократном использовании одного и того же шаблона.

Применение

Веб-разработка

Jinja2 является стандартным шаблонизатором для фреймворка Flask и может использоваться в Django (через сторонние библиотеки, например, django-jinja). Он также применяется в FastAPI, Pyramid, Tornado и других веб-фреймворках.

Генерация статических сайтов

Инструменты, такие как Pelican, Lektor, Nikola, используют Jinja2 для генерации HTML-страниц из Markdown или reStructuredText с шаблонами.

Автоматизация и конфигурация

Системы управления конфигурацией, такие как Ansible и SaltStack, используют Jinja2 для генерации конфигурационных файлов (YAML, JSON, INI, Apache/Nginx conf и т.д.) на основе шаблонов и переменных.

Генерация кода

Jinja2 применяется для генерации исходного кода на разных языках программирования (Python, C++, Java, SQL, HTML, CSS, JavaScript и др.) в метапрограммировании, кодогенераторах, ORM (например, SQLAlchemy использует Jinja2 для генерации SQL-запросов).

Документация и отчёты

Jinja2 используется в системах генерации документации (Sphinx, MkDocs — через плагины), в отчётах (например, в Jupyter Notebooks через nbconvert), в PDF-генераторах (через LaTeX или HTML в PDF).

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

Пример 1: Простой шаблон HTML

Шаблон (hello.html): ``html <!DOCTYPE html> <html> <head><title>Приветствие</title></head> <body> <h1>Привет, {{ name }}!</h1> <p>Сегодня {{ date | date('d.m.Y') }}.</p> </body> </html> ``

Python-код: ```python from jinja2 import Environment, FileSystemLoader from datetime import datetime

env = Environment(loader=FileSystemLoader('templates')) template = env.get_template('hello.html') output = template.render(name='Мир', date=datetime.now()) print(output) ```

Пример 2: Цикл и условие

Шаблон (users.html): ``html <h1>Список пользователей</h1> <ul> {% for user in users %} <li>{{ user.name }} ({{ user.email }})</li> {% else %} <li>Нет пользователей.</li> {% endfor %} </ul> {% if users | length > 10 %} <p>Показаны первые 10 пользователей.</p> {% endif %} ``

Сравнение с другими шаблонизаторами

Интересные факты

• Название «Jinja» происходит от японского слова «дзиндзя» (храм синто), что символизирует «чистоту» и «святость» кода.
• Jinja2 поддерживает Unicode и автоматическую обработку кодировок.
• В Jinja2 есть встроенная поддержка i18n (интернационализации) через расширение jinja2.ext.i18n.
• Шаблоны Jinja2 могут быть использованы не только для HTML, но и для любых текстовых форматов: CSS, JavaScript, XML, YAML, JSON, Markdown, LaTeX, SQL, Python, C++ и т.д.
• Jinja2 используется в популярных проектах: Ansible, SaltStack, Pelican, Lektor, Sphinx, MkDocs, Jupyter Notebook, Airflow, Prefect, DBT, Great Expectations и многих других.

Источники

• Официальная документация Jinja2 (jinja.palletsprojects.com)
• Исходный код Jinja2 на GitHub (github.com/pallets/jinja)
• Книга «Flask Web Development» (Мигель Гринберг)
• Статья «Jinja2: The Python Template Engine» на Real Python
• Документация Ansible по шаблонам Jinja2
• Документация Flask по шаблонам