Загрузчики шаблонов модуля jinja2 в Python.

Загрузчики шаблонов отвечают за загрузку шаблонов из ресурса, такого, например, как файловая система. Среда будет хранить скомпилированные модули в памяти, как sys.modules Python. Однако, в отличие от sys.modules, этот кэш по умолчанию ограничен по размеру, и шаблоны автоматически перезагружаются.

Все загрузчики являются подклассами BaseLoader. Если необходимо создать свой собственный загрузчик, то создайте подкласс BaseLoader и переопределите метод BaseLoader.get_source().

Содержание:

• jinja2.BaseLoader базовый класс всех загрузчиков,
• Список встроенных загрузчиков, в модуль jinja2.
  • jinja2.FileSystemLoader() загружает шаблоны из файловой системы,
  • jinja2.PackageLoader() загружает шаблоны из пакетов Python,
  • jinja2.DictLoader() загружает шаблон из словаря Python,
  • jinja2.FunctionLoader() загружает шаблон через функцию-загрузчик,
  • jinja2.PrefixLoader() каждый загрузчик привязан к префиксу,
  • jinja2.ChoiceLoader() список загрузчиков, которые вызываются по очереди,
  • jinja2.ModuleLoader() загружает шаблоны из предварительно скомпилированных шаблонов.

jinja2.BaseLoader:

Класс jinja2.BaseLoader представляет базовый класс для всех загрузчиков. Создайте подкласс этого класса и переопределите метод .get_source(), чтобы реализовать собственный механизм загрузки. Среда предоставляет метод .get_template, который вызывает метод .load загрузчика для получения объекта Template.

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

from jinja2 import BaseLoader, TemplateNotFound
from os.path import join, exists, getmtime

MyLoader(BaseLoader):

    def __init__(self, path):
        self.path = path

    def get_source(self, environment, template):
        path = join(self.path, template)
        if not exists(path):
            raise TemplateNotFound(template)
        mtime = getmtime(path)
        with file(path) as f:
            source = f.read().decode('utf-8')
        return source, path, lambda: mtime == getmtime(path)

BaseLoader.get_source(environment, template):

Метод BaseLoader.get_source() получает источник шаблона, имя файла и перезагружает помощник шаблонов. Метод принимает среду environment и имя шаблона template и должен вернуть кортеж в форме (source, filename, uptodate) или вызвать ошибку jinja2.TemplateNotFound, если не может найти шаблон.

Значение source возвращаемого кортежа должна быть источником шаблона в виде строки Unicode или байтовой строки ASCII. Значение filename должно быть именем файла в файловой системе, если он был загружен оттуда, в противном случае - None. Значение filename используется python для трассировки, если не используется расширение загрузчика.

Последний элемент в кортеже uptodate - это функция обновления. Если автоматическая перезагрузка включена, то она вызывается всегда, чтобы проверить, не изменился ли шаблон. Аргументы не передаются, поэтому функция должна где-то хранить старое состояние. Если она вернет False, то шаблон будет перезагружен.

BaseLoader.load(environment, name, globals=None):

Метод BaseLoader.load() загружает шаблон. Этот метод ищет шаблон в кеше или загружает его, вызывая BaseLoader.get_source. Подклассы не должны переопределять этот метод, поскольку загрузчики, работающие с коллекциями других загрузчиков (например, PrefixLoader или ChoiceLoader), не будут вызывать этот метод, а напрямую get_source.

Список встроенных загрузчиков, в модуль jinja2.

jinja2.FileSystemLoader(searchpath, encoding='utf-8', followlinks=False):

Класс jinja2.FileSystemLoader() загружает шаблоны из файловой системы. Этот загрузчик может находить шаблоны в папках файловой системы и является предпочтительным способом их загрузки.

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

>>> loader = FileSystemLoader('/path/to/templates')
>>> loader = FileSystemLoader(['/path/to/templates', '/other/path'])

По умолчанию кодировка шаблона 'utf-8', которую можно изменить, установив для аргумента encoding другое значение.

Чтобы следовать символическим ссылкам в файловой системе, то необходимо установить параметр followlinks=True:

>>> loader = FileSystemLoader('/path/to/templates', followlinks=True)

jinja2.PackageLoader(package_name, package_path='templates', encoding='utf-8'):

Класс jinja2.PackageLoader() загружает шаблоны из пакетов Python. Класс принимает имя пакета package_name и пути к шаблонам в этом пакете package_path:

loader = PackageLoader('mypackage', 'views')

Если путь к пакету не указан, предполагается папка 'templates'.

По умолчанию кодировка шаблона 'utf-8', которую можно изменить, установив для параметра encoding другое значение. Перезагрузка шаблонов возможна только в том случае, если пакет был загружен из файловой системы, а не из zip-файла.

jinja2.DictLoader(mapping):

Класс jinja2.DictLoader() загружает шаблон из словаря Python. Аргумент mapping принимает набор строк юникода, привязанных к именам шаблонов. Этот загрузчик полезен для юнит-тестирования:

>>> loader = DictLoader({'index.html': 'source here'})

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

jinja2.FunctionLoader(load_func):

Метод jinja2.FunctionLoader() представляет собой загрузчик, которому передана функция load_func, выполняющая загрузку. Функция получает имя шаблона и должна возвращать либо строку Unicode с источником шаблона, либо кортеж в форме (source, filename, uptodatefunc) или None, если шаблон не существует.

>>> def load_template(name):
...     if name == 'index.html':
...         return '...'
...
>>> loader = FunctionLoader(load_template)

Значение возвращаемого кортежа uptodatefunc - это функция, которая вызывается, если включена автоматическая загрузка, и должна возвращать значение True, если шаблон все еще актуален. Для получения более подробной информации взгляните на BaseLoader.get_source(), который имеет то же возвращаемое значение.

jinja2.PrefixLoader(mapping, delimiter='/'):

Класс jinja2.PrefixLoader() представляет собой загрузчик, которому передается список загрузчиков, где каждый загрузчик привязан к префиксу.

По умолчанию префикс отделяется от шаблона косой чертой, которую можно изменить, установив в качестве аргумента-разделителя другое значение:

loader = PrefixLoader({
    'app1':     PackageLoader('mypackage.app1'),
    'app2':     PackageLoader('mypackage.app2')
})

При загрузке app1/index.html загружается файл из пакета app1, при загрузке app2/index.html файл из второго пакета.

jinja2.ChoiceLoader(loaders):

Класс jinja2.ChoiceLoader() работает так же, как jinja2.PrefixLoader, только без указания префикса. Если шаблон не может быть найден одним загрузчиком, пробуется следующий.

>>> loader = ChoiceLoader([
...     FileSystemLoader('/path/to/user/templates'),
...     FileSystemLoader('/path/to/system/templates')
... ])

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

jinja2.ModuleLoader(path):

Класс jinja2.ModuleLoader() загружает шаблоны из предварительно скомпилированных шаблонов.

Example usage:

>>> loader = ChoiceLoader([
...     ModuleLoader('/path/to/compiled/templates'),
...     FileSystemLoader('/path/to/templates')
... ])

Шаблоны можно предварительно скомпилировать с помощью метода Environment.compile_templates().