Загрузчики шаблонов отвечают за загрузку шаблонов из ресурса, такого, например, как файловая система. Среда будет хранить скомпилированные модули в памяти, как
sys.modules
Python. Однако, в отличие от
sys.modules
, этот кэш по умолчанию ограничен по размеру, и шаблоны автоматически перезагружаются.
Все загрузчики являются подклассами BaseLoader
. Если необходимо создать свой собственный загрузчик, то создайте подкласс BaseLoader
и переопределите метод BaseLoader.get_source()
.
Содержание:
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')
... ])