summaryrefslogtreecommitdiffhomepage
path: root/scripts/jinja2/loaders.py
diff options
context:
space:
mode:
Diffstat (limited to 'scripts/jinja2/loaders.py')
-rw-r--r--scripts/jinja2/loaders.py487
1 files changed, 329 insertions, 158 deletions
diff --git a/scripts/jinja2/loaders.py b/scripts/jinja2/loaders.py
index 376e858..4fac3a0 100644
--- a/scripts/jinja2/loaders.py
+++ b/scripts/jinja2/loaders.py
@@ -1,40 +1,44 @@
-# -*- coding: utf-8 -*-
-"""
- jinja2.loaders
- ~~~~~~~~~~~~~~
-
- Jinja loader classes.
-
- :copyright: (c) 2010 by the Jinja Team.
- :license: BSD, see LICENSE for more details.
+"""API and implementations for loading templates from different data
+sources.
"""
+import importlib.util
import os
import sys
+import typing as t
import weakref
-from types import ModuleType
-from os import path
+import zipimport
+from collections import abc
from hashlib import sha1
-from jinja2.exceptions import TemplateNotFound
-from jinja2.utils import open_if_exists, internalcode
-from jinja2._compat import string_types, iteritems
+from importlib import import_module
+from types import ModuleType
+
+from .exceptions import TemplateNotFound
+from .utils import internalcode
+from .utils import open_if_exists
+
+if t.TYPE_CHECKING:
+ from .environment import Environment
+ from .environment import Template
-def split_template_path(template):
+def split_template_path(template: str) -> t.List[str]:
"""Split a path into segments and perform a sanity check. If it detects
'..' in the path it will raise a `TemplateNotFound` error.
"""
pieces = []
- for piece in template.split('/'):
- if path.sep in piece \
- or (path.altsep and path.altsep in piece) or \
- piece == path.pardir:
+ for piece in template.split("/"):
+ if (
+ os.path.sep in piece
+ or (os.path.altsep and os.path.altsep in piece)
+ or piece == os.path.pardir
+ ):
raise TemplateNotFound(template)
- elif piece and piece != '.':
+ elif piece and piece != ".":
pieces.append(piece)
return pieces
-class BaseLoader(object):
+class BaseLoader:
"""Baseclass for all loaders. Subclass this and override `get_source` to
implement a custom loading mechanism. The environment provides a
`get_template` method that calls the loader's `load` method to get the
@@ -56,8 +60,8 @@ class BaseLoader(object):
if not exists(path):
raise TemplateNotFound(template)
mtime = getmtime(path)
- with file(path) as f:
- source = f.read().decode('utf-8')
+ with open(path) as f:
+ source = f.read()
return source, path, lambda: mtime == getmtime(path)
"""
@@ -67,16 +71,18 @@ class BaseLoader(object):
#: .. versionadded:: 2.4
has_source_access = True
- def get_source(self, environment, template):
+ def get_source(
+ self, environment: "Environment", template: str
+ ) -> t.Tuple[str, t.Optional[str], t.Optional[t.Callable[[], bool]]]:
"""Get the template source, filename and reload helper for a template.
It's passed the environment and template name and has to return a
tuple in the form ``(source, filename, uptodate)`` or raise a
`TemplateNotFound` error if it can't locate the template.
The source part of the returned tuple must be the source of the
- template as unicode string or a ASCII bytestring. The filename should
- be the name of the file on the filesystem if it was loaded from there,
- otherwise `None`. The filename is used by python for the tracebacks
+ template as a string. The filename should be the name of the
+ file on the filesystem if it was loaded from there, otherwise
+ ``None``. The filename is used by Python for the tracebacks
if no loader extension is used.
The last item in the tuple is the `uptodate` function. If auto
@@ -86,18 +92,24 @@ class BaseLoader(object):
the template will be reloaded.
"""
if not self.has_source_access:
- raise RuntimeError('%s cannot provide access to the source' %
- self.__class__.__name__)
+ raise RuntimeError(
+ f"{type(self).__name__} cannot provide access to the source"
+ )
raise TemplateNotFound(template)
- def list_templates(self):
+ def list_templates(self) -> t.List[str]:
"""Iterates over all templates. If the loader does not support that
it should raise a :exc:`TypeError` which is the default behavior.
"""
- raise TypeError('this loader cannot iterate over all templates')
+ raise TypeError("this loader cannot iterate over all templates")
@internalcode
- def load(self, environment, name, globals=None):
+ def load(
+ self,
+ environment: "Environment",
+ name: str,
+ globals: t.Optional[t.MutableMapping[str, t.Any]] = None,
+ ) -> "Template":
"""Loads a template. This method looks up the template in the cache
or loads one by calling :meth:`get_source`. Subclasses should not
override this method as loaders working on collections of other
@@ -131,43 +143,57 @@ class BaseLoader(object):
bucket.code = code
bcc.set_bucket(bucket)
- return environment.template_class.from_code(environment, code,
- globals, uptodate)
+ return environment.template_class.from_code(
+ environment, code, globals, uptodate
+ )
class FileSystemLoader(BaseLoader):
- """Loads templates from the file system. This loader can find templates
- in folders on the file system and is the preferred way to load them.
+ """Load templates from a directory in the file system.
- The loader takes the path to the templates as string, or if multiple
- locations are wanted a list of them which is then looked up in the
- given order::
+ The path can be relative or absolute. Relative paths are relative to
+ the current working directory.
- >>> loader = FileSystemLoader('/path/to/templates')
- >>> loader = FileSystemLoader(['/path/to/templates', '/other/path'])
+ .. code-block:: python
- Per default the template encoding is ``'utf-8'`` which can be changed
- by setting the `encoding` parameter to something else.
+ loader = FileSystemLoader("templates")
- To follow symbolic links, set the *followlinks* parameter to ``True``::
+ A list of paths can be given. The directories will be searched in
+ order, stopping at the first matching template.
- >>> loader = FileSystemLoader('/path/to/templates', followlinks=True)
+ .. code-block:: python
- .. versionchanged:: 2.8+
- The *followlinks* parameter was added.
+ loader = FileSystemLoader(["/override/templates", "/default/templates"])
+
+ :param searchpath: A path, or list of paths, to the directory that
+ contains the templates.
+ :param encoding: Use this encoding to read the text from template
+ files.
+ :param followlinks: Follow symbolic links in the path.
+
+ .. versionchanged:: 2.8
+ Added the ``followlinks`` parameter.
"""
- def __init__(self, searchpath, encoding='utf-8', followlinks=False):
- if isinstance(searchpath, string_types):
+ def __init__(
+ self,
+ searchpath: t.Union[str, os.PathLike, t.Sequence[t.Union[str, os.PathLike]]],
+ encoding: str = "utf-8",
+ followlinks: bool = False,
+ ) -> None:
+ if not isinstance(searchpath, abc.Iterable) or isinstance(searchpath, str):
searchpath = [searchpath]
- self.searchpath = list(searchpath)
+
+ self.searchpath = [os.fspath(p) for p in searchpath]
self.encoding = encoding
self.followlinks = followlinks
- def get_source(self, environment, template):
+ def get_source(
+ self, environment: "Environment", template: str
+ ) -> t.Tuple[str, str, t.Callable[[], bool]]:
pieces = split_template_path(template)
for searchpath in self.searchpath:
- filename = path.join(searchpath, *pieces)
+ filename = os.path.join(searchpath, *pieces)
f = open_if_exists(filename)
if f is None:
continue
@@ -176,26 +202,29 @@ class FileSystemLoader(BaseLoader):
finally:
f.close()
- mtime = path.getmtime(filename)
+ mtime = os.path.getmtime(filename)
- def uptodate():
+ def uptodate() -> bool:
try:
- return path.getmtime(filename) == mtime
+ return os.path.getmtime(filename) == mtime
except OSError:
return False
+
return contents, filename, uptodate
raise TemplateNotFound(template)
- def list_templates(self):
+ def list_templates(self) -> t.List[str]:
found = set()
for searchpath in self.searchpath:
walk_dir = os.walk(searchpath, followlinks=self.followlinks)
- for dirpath, dirnames, filenames in walk_dir:
+ for dirpath, _, filenames in walk_dir:
for filename in filenames:
- template = os.path.join(dirpath, filename) \
- [len(searchpath):].strip(os.path.sep) \
- .replace(os.path.sep, '/')
- if template[:2] == './':
+ template = (
+ os.path.join(dirpath, filename)[len(searchpath) :]
+ .strip(os.path.sep)
+ .replace(os.path.sep, "/")
+ )
+ if template[:2] == "./":
template = template[2:]
if template not in found:
found.add(template)
@@ -203,96 +232,194 @@ class FileSystemLoader(BaseLoader):
class PackageLoader(BaseLoader):
- """Load templates from python eggs or packages. It is constructed with
- the name of the python package and the path to the templates in that
- package::
+ """Load templates from a directory in a Python package.
+
+ :param package_name: Import name of the package that contains the
+ template directory.
+ :param package_path: Directory within the imported package that
+ contains the templates.
+ :param encoding: Encoding of template files.
+
+ The following example looks up templates in the ``pages`` directory
+ within the ``project.ui`` package.
- loader = PackageLoader('mypackage', 'views')
+ .. code-block:: python
- If the package path is not given, ``'templates'`` is assumed.
+ loader = PackageLoader("project.ui", "pages")
- Per default the template encoding is ``'utf-8'`` which can be changed
- by setting the `encoding` parameter to something else. Due to the nature
- of eggs it's only possible to reload templates if the package was loaded
- from the file system and not a zip file.
+ Only packages installed as directories (standard pip behavior) or
+ zip/egg files (less common) are supported. The Python API for
+ introspecting data in packages is too limited to support other
+ installation methods the way this loader requires.
+
+ There is limited support for :pep:`420` namespace packages. The
+ template directory is assumed to only be in one namespace
+ contributor. Zip files contributing to a namespace are not
+ supported.
+
+ .. versionchanged:: 3.0
+ No longer uses ``setuptools`` as a dependency.
+
+ .. versionchanged:: 3.0
+ Limited PEP 420 namespace package support.
"""
- def __init__(self, package_name, package_path='templates',
- encoding='utf-8'):
- from pkg_resources import DefaultProvider, ResourceManager, \
- get_provider
- provider = get_provider(package_name)
- self.encoding = encoding
- self.manager = ResourceManager()
- self.filesystem_bound = isinstance(provider, DefaultProvider)
- self.provider = provider
+ def __init__(
+ self,
+ package_name: str,
+ package_path: "str" = "templates",
+ encoding: str = "utf-8",
+ ) -> None:
+ package_path = os.path.normpath(package_path).rstrip(os.path.sep)
+
+ # normpath preserves ".", which isn't valid in zip paths.
+ if package_path == os.path.curdir:
+ package_path = ""
+ elif package_path[:2] == os.path.curdir + os.path.sep:
+ package_path = package_path[2:]
+
self.package_path = package_path
+ self.package_name = package_name
+ self.encoding = encoding
- def get_source(self, environment, template):
- pieces = split_template_path(template)
- p = '/'.join((self.package_path,) + tuple(pieces))
- if not self.provider.has_resource(p):
- raise TemplateNotFound(template)
+ # Make sure the package exists. This also makes namespace
+ # packages work, otherwise get_loader returns None.
+ import_module(package_name)
+ spec = importlib.util.find_spec(package_name)
+ assert spec is not None, "An import spec was not found for the package."
+ loader = spec.loader
+ assert loader is not None, "A loader was not found for the package."
+ self._loader = loader
+ self._archive = None
+ template_root = None
+
+ if isinstance(loader, zipimport.zipimporter):
+ self._archive = loader.archive
+ pkgdir = next(iter(spec.submodule_search_locations)) # type: ignore
+ template_root = os.path.join(pkgdir, package_path)
+ else:
+ roots: t.List[str] = []
- filename = uptodate = None
- if self.filesystem_bound:
- filename = self.provider.get_resource_filename(self.manager, p)
- mtime = path.getmtime(filename)
- def uptodate():
- try:
- return path.getmtime(filename) == mtime
- except OSError:
- return False
+ # One element for regular packages, multiple for namespace
+ # packages, or None for single module file.
+ if spec.submodule_search_locations:
+ roots.extend(spec.submodule_search_locations)
+ # A single module file, use the parent directory instead.
+ elif spec.origin is not None:
+ roots.append(os.path.dirname(spec.origin))
+
+ for root in roots:
+ root = os.path.join(root, package_path)
+
+ if os.path.isdir(root):
+ template_root = root
+ break
+
+ if template_root is None:
+ raise ValueError(
+ f"The {package_name!r} package was not installed in a"
+ " way that PackageLoader understands."
+ )
+
+ self._template_root = template_root
+
+ def get_source(
+ self, environment: "Environment", template: str
+ ) -> t.Tuple[str, str, t.Optional[t.Callable[[], bool]]]:
+ p = os.path.join(self._template_root, *split_template_path(template))
+ up_to_date: t.Optional[t.Callable[[], bool]]
+
+ if self._archive is None:
+ # Package is a directory.
+ if not os.path.isfile(p):
+ raise TemplateNotFound(template)
+
+ with open(p, "rb") as f:
+ source = f.read()
+
+ mtime = os.path.getmtime(p)
+
+ def up_to_date() -> bool:
+ return os.path.isfile(p) and os.path.getmtime(p) == mtime
+
+ else:
+ # Package is a zip file.
+ try:
+ source = self._loader.get_data(p) # type: ignore
+ except OSError as e:
+ raise TemplateNotFound(template) from e
+
+ # Could use the zip's mtime for all template mtimes, but
+ # would need to safely reload the module if it's out of
+ # date, so just report it as always current.
+ up_to_date = None
+
+ return source.decode(self.encoding), p, up_to_date
+
+ def list_templates(self) -> t.List[str]:
+ results: t.List[str] = []
+
+ if self._archive is None:
+ # Package is a directory.
+ offset = len(self._template_root)
+
+ for dirpath, _, filenames in os.walk(self._template_root):
+ dirpath = dirpath[offset:].lstrip(os.path.sep)
+ results.extend(
+ os.path.join(dirpath, name).replace(os.path.sep, "/")
+ for name in filenames
+ )
+ else:
+ if not hasattr(self._loader, "_files"):
+ raise TypeError(
+ "This zip import does not have the required"
+ " metadata to list templates."
+ )
+
+ # Package is a zip file.
+ prefix = (
+ self._template_root[len(self._archive) :].lstrip(os.path.sep)
+ + os.path.sep
+ )
+ offset = len(prefix)
+
+ for name in self._loader._files.keys(): # type: ignore
+ # Find names under the templates directory that aren't directories.
+ if name.startswith(prefix) and name[-1] != os.path.sep:
+ results.append(name[offset:].replace(os.path.sep, "/"))
- source = self.provider.get_resource_string(self.manager, p)
- return source.decode(self.encoding), filename, uptodate
-
- def list_templates(self):
- path = self.package_path
- if path[:2] == './':
- path = path[2:]
- elif path == '.':
- path = ''
- offset = len(path)
- results = []
- def _walk(path):
- for filename in self.provider.resource_listdir(path):
- fullname = path + '/' + filename
- if self.provider.resource_isdir(fullname):
- _walk(fullname)
- else:
- results.append(fullname[offset:].lstrip('/'))
- _walk(path)
results.sort()
return results
class DictLoader(BaseLoader):
- """Loads a template from a python dict. It's passed a dict of unicode
- strings bound to template names. This loader is useful for unittesting:
+ """Loads a template from a Python dict mapping template names to
+ template source. This loader is useful for unittesting:
>>> loader = DictLoader({'index.html': 'source here'})
Because auto reloading is rarely useful this is disabled per default.
"""
- def __init__(self, mapping):
+ def __init__(self, mapping: t.Mapping[str, str]) -> None:
self.mapping = mapping
- def get_source(self, environment, template):
+ def get_source(
+ self, environment: "Environment", template: str
+ ) -> t.Tuple[str, None, t.Callable[[], bool]]:
if template in self.mapping:
source = self.mapping[template]
return source, None, lambda: source == self.mapping.get(template)
raise TemplateNotFound(template)
- def list_templates(self):
+ def list_templates(self) -> t.List[str]:
return sorted(self.mapping)
class FunctionLoader(BaseLoader):
"""A loader that is passed a function which does the loading. The
- function becomes the name of the template passed and has to return either
- an unicode string with the template source, a tuple in the form ``(source,
+ function receives the name of the template and has to return either
+ a string with the template source, a tuple in the form ``(source,
filename, uptodatefunc)`` or `None` if the template does not exist.
>>> def load_template(name):
@@ -307,15 +434,30 @@ class FunctionLoader(BaseLoader):
return value.
"""
- def __init__(self, load_func):
+ def __init__(
+ self,
+ load_func: t.Callable[
+ [str],
+ t.Optional[
+ t.Union[
+ str, t.Tuple[str, t.Optional[str], t.Optional[t.Callable[[], bool]]]
+ ]
+ ],
+ ],
+ ) -> None:
self.load_func = load_func
- def get_source(self, environment, template):
+ def get_source(
+ self, environment: "Environment", template: str
+ ) -> t.Tuple[str, t.Optional[str], t.Optional[t.Callable[[], bool]]]:
rv = self.load_func(template)
+
if rv is None:
raise TemplateNotFound(template)
- elif isinstance(rv, string_types):
+
+ if isinstance(rv, str):
return rv, None, None
+
return rv
@@ -334,40 +476,49 @@ class PrefixLoader(BaseLoader):
by loading ``'app2/index.html'`` the file from the second.
"""
- def __init__(self, mapping, delimiter='/'):
+ def __init__(
+ self, mapping: t.Mapping[str, BaseLoader], delimiter: str = "/"
+ ) -> None:
self.mapping = mapping
self.delimiter = delimiter
- def get_loader(self, template):
+ def get_loader(self, template: str) -> t.Tuple[BaseLoader, str]:
try:
prefix, name = template.split(self.delimiter, 1)
loader = self.mapping[prefix]
- except (ValueError, KeyError):
- raise TemplateNotFound(template)
+ except (ValueError, KeyError) as e:
+ raise TemplateNotFound(template) from e
return loader, name
- def get_source(self, environment, template):
+ def get_source(
+ self, environment: "Environment", template: str
+ ) -> t.Tuple[str, t.Optional[str], t.Optional[t.Callable[[], bool]]]:
loader, name = self.get_loader(template)
try:
return loader.get_source(environment, name)
- except TemplateNotFound:
- # re-raise the exception with the correct fileame here.
+ except TemplateNotFound as e:
+ # re-raise the exception with the correct filename here.
# (the one that includes the prefix)
- raise TemplateNotFound(template)
+ raise TemplateNotFound(template) from e
@internalcode
- def load(self, environment, name, globals=None):
+ def load(
+ self,
+ environment: "Environment",
+ name: str,
+ globals: t.Optional[t.MutableMapping[str, t.Any]] = None,
+ ) -> "Template":
loader, local_name = self.get_loader(name)
try:
return loader.load(environment, local_name, globals)
- except TemplateNotFound:
- # re-raise the exception with the correct fileame here.
+ except TemplateNotFound as e:
+ # re-raise the exception with the correct filename here.
# (the one that includes the prefix)
- raise TemplateNotFound(name)
+ raise TemplateNotFound(name) from e
- def list_templates(self):
+ def list_templates(self) -> t.List[str]:
result = []
- for prefix, loader in iteritems(self.mapping):
+ for prefix, loader in self.mapping.items():
for template in loader.list_templates():
result.append(prefix + self.delimiter + template)
return result
@@ -387,10 +538,12 @@ class ChoiceLoader(BaseLoader):
from a different location.
"""
- def __init__(self, loaders):
+ def __init__(self, loaders: t.Sequence[BaseLoader]) -> None:
self.loaders = loaders
- def get_source(self, environment, template):
+ def get_source(
+ self, environment: "Environment", template: str
+ ) -> t.Tuple[str, t.Optional[str], t.Optional[t.Callable[[], bool]]]:
for loader in self.loaders:
try:
return loader.get_source(environment, template)
@@ -399,7 +552,12 @@ class ChoiceLoader(BaseLoader):
raise TemplateNotFound(template)
@internalcode
- def load(self, environment, name, globals=None):
+ def load(
+ self,
+ environment: "Environment",
+ name: str,
+ globals: t.Optional[t.MutableMapping[str, t.Any]] = None,
+ ) -> "Template":
for loader in self.loaders:
try:
return loader.load(environment, name, globals)
@@ -407,7 +565,7 @@ class ChoiceLoader(BaseLoader):
pass
raise TemplateNotFound(name)
- def list_templates(self):
+ def list_templates(self) -> t.List[str]:
found = set()
for loader in self.loaders:
found.update(loader.list_templates())
@@ -433,20 +591,23 @@ class ModuleLoader(BaseLoader):
has_source_access = False
- def __init__(self, path):
- package_name = '_jinja2_module_templates_%x' % id(self)
+ def __init__(
+ self, path: t.Union[str, os.PathLike, t.Sequence[t.Union[str, os.PathLike]]]
+ ) -> None:
+ package_name = f"_jinja2_module_templates_{id(self):x}"
# create a fake module that looks for the templates in the
# path given.
mod = _TemplateModule(package_name)
- if isinstance(path, string_types):
+
+ if not isinstance(path, abc.Iterable) or isinstance(path, str):
path = [path]
- else:
- path = list(path)
- mod.__path__ = path
- sys.modules[package_name] = weakref.proxy(mod,
- lambda x: sys.modules.pop(package_name, None))
+ mod.__path__ = [os.fspath(p) for p in path] # type: ignore
+
+ sys.modules[package_name] = weakref.proxy(
+ mod, lambda x: sys.modules.pop(package_name, None)
+ )
# the only strong reference, the sys.modules entry is weak
# so that the garbage collector can remove it once the
@@ -455,27 +616,37 @@ class ModuleLoader(BaseLoader):
self.package_name = package_name
@staticmethod
- def get_template_key(name):
- return 'tmpl_' + sha1(name.encode('utf-8')).hexdigest()
+ def get_template_key(name: str) -> str:
+ return "tmpl_" + sha1(name.encode("utf-8")).hexdigest()
@staticmethod
- def get_module_filename(name):
- return ModuleLoader.get_template_key(name) + '.py'
+ def get_module_filename(name: str) -> str:
+ return ModuleLoader.get_template_key(name) + ".py"
@internalcode
- def load(self, environment, name, globals=None):
+ def load(
+ self,
+ environment: "Environment",
+ name: str,
+ globals: t.Optional[t.MutableMapping[str, t.Any]] = None,
+ ) -> "Template":
key = self.get_template_key(name)
- module = '%s.%s' % (self.package_name, key)
+ module = f"{self.package_name}.{key}"
mod = getattr(self.module, module, None)
+
if mod is None:
try:
- mod = __import__(module, None, None, ['root'])
- except ImportError:
- raise TemplateNotFound(name)
+ mod = __import__(module, None, None, ["root"])
+ except ImportError as e:
+ raise TemplateNotFound(name) from e
# remove the entry from sys.modules, we only want the attribute
# on the module object we have stored on the loader.
sys.modules.pop(module, None)
+ if globals is None:
+ globals = {}
+
return environment.template_class.from_module_dict(
- environment, mod.__dict__, globals)
+ environment, mod.__dict__, globals
+ )