1 # -*- coding: utf-8 -*-
8 :copyright: (c) 2010 by the Jinja Team.
9 :license: BSD, see LICENSE for more details.
13 from hashlib import sha1
15 from sha import new as sha1
16 from jinja2.exceptions import TemplateNotFound
17 from jinja2.utils import LRUCache, open_if_exists, internalcode
20 def split_template_path(template):
21 """Split a path into segments and perform a sanity check. If it detects
22 '..' in the path it will raise a `TemplateNotFound` error.
25 for piece in template.split('/'):
26 if path.sep in piece \
27 or (path.altsep and path.altsep in piece) or \
29 raise TemplateNotFound(template)
30 elif piece and piece != '.':
35 class BaseLoader(object):
36 """Baseclass for all loaders. Subclass this and override `get_source` to
37 implement a custom loading mechanism. The environment provides a
38 `get_template` method that calls the loader's `load` method to get the
39 :class:`Template` object.
41 A very basic example for a loader that looks up templates on the file
42 system could look like this::
44 from jinja2 import BaseLoader, TemplateNotFound
45 from os.path import join, exists, getmtime
47 class MyLoader(BaseLoader):
49 def __init__(self, path):
52 def get_source(self, environment, template):
53 path = join(self.path, template)
55 raise TemplateNotFound(template)
56 mtime = getmtime(path)
58 source = f.read().decode('utf-8')
59 return source, path, lambda: mtime == getmtime(path)
62 def get_source(self, environment, template):
63 """Get the template source, filename and reload helper for a template.
64 It's passed the environment and template name and has to return a
65 tuple in the form ``(source, filename, uptodate)`` or raise a
66 `TemplateNotFound` error if it can't locate the template.
68 The source part of the returned tuple must be the source of the
69 template as unicode string or a ASCII bytestring. The filename should
70 be the name of the file on the filesystem if it was loaded from there,
71 otherwise `None`. The filename is used by python for the tracebacks
72 if no loader extension is used.
74 The last item in the tuple is the `uptodate` function. If auto
75 reloading is enabled it's always called to check if the template
76 changed. No arguments are passed so the function must store the
77 old state somewhere (for example in a closure). If it returns `False`
78 the template will be reloaded.
80 raise TemplateNotFound(template)
83 def load(self, environment, name, globals=None):
84 """Loads a template. This method looks up the template in the cache
85 or loads one by calling :meth:`get_source`. Subclasses should not
86 override this method as loaders working on collections of other
87 loaders (such as :class:`PrefixLoader` or :class:`ChoiceLoader`)
88 will not call this method but `get_source` directly.
94 # first we try to get the source for this template together
95 # with the filename and the uptodate function.
96 source, filename, uptodate = self.get_source(environment, name)
98 # try to load the code from the bytecode cache if there is a
99 # bytecode cache configured.
100 bcc = environment.bytecode_cache
102 bucket = bcc.get_bucket(environment, name, filename, source)
105 # if we don't have code so far (not cached, no longer up to
106 # date) etc. we compile the template
108 code = environment.compile(source, name, filename)
110 # if the bytecode cache is available and the bucket doesn't
111 # have a code so far, we give the bucket the new code and put
112 # it back to the bytecode cache.
113 if bcc is not None and bucket.code is None:
115 bcc.set_bucket(bucket)
117 return environment.template_class.from_code(environment, code,
121 class FileSystemLoader(BaseLoader):
122 """Loads templates from the file system. This loader can find templates
123 in folders on the file system and is the preferred way to load them.
125 The loader takes the path to the templates as string, or if multiple
126 locations are wanted a list of them which is then looked up in the
129 >>> loader = FileSystemLoader('/path/to/templates')
130 >>> loader = FileSystemLoader(['/path/to/templates', '/other/path'])
132 Per default the template encoding is ``'utf-8'`` which can be changed
133 by setting the `encoding` parameter to something else.
136 def __init__(self, searchpath, encoding='utf-8'):
137 if isinstance(searchpath, basestring):
138 searchpath = [searchpath]
139 self.searchpath = list(searchpath)
140 self.encoding = encoding
142 def get_source(self, environment, template):
143 pieces = split_template_path(template)
144 for searchpath in self.searchpath:
145 filename = path.join(searchpath, *pieces)
146 f = open_if_exists(filename)
150 contents = f.read().decode(self.encoding)
154 mtime = path.getmtime(filename)
157 return path.getmtime(filename) == mtime
160 return contents, filename, uptodate
161 raise TemplateNotFound(template)
164 class PackageLoader(BaseLoader):
165 """Load templates from python eggs or packages. It is constructed with
166 the name of the python package and the path to the templates in that
169 loader = PackageLoader('mypackage', 'views')
171 If the package path is not given, ``'templates'`` is assumed.
173 Per default the template encoding is ``'utf-8'`` which can be changed
174 by setting the `encoding` parameter to something else. Due to the nature
175 of eggs it's only possible to reload templates if the package was loaded
176 from the file system and not a zip file.
179 def __init__(self, package_name, package_path='templates',
181 from pkg_resources import DefaultProvider, ResourceManager, \
183 provider = get_provider(package_name)
184 self.encoding = encoding
185 self.manager = ResourceManager()
186 self.filesystem_bound = isinstance(provider, DefaultProvider)
187 self.provider = provider
188 self.package_path = package_path
190 def get_source(self, environment, template):
191 pieces = split_template_path(template)
192 p = '/'.join((self.package_path,) + tuple(pieces))
193 if not self.provider.has_resource(p):
194 raise TemplateNotFound(template)
196 filename = uptodate = None
197 if self.filesystem_bound:
198 filename = self.provider.get_resource_filename(self.manager, p)
199 mtime = path.getmtime(filename)
202 return path.getmtime(filename) == mtime
206 source = self.provider.get_resource_string(self.manager, p)
207 return source.decode(self.encoding), filename, uptodate
210 class DictLoader(BaseLoader):
211 """Loads a template from a python dict. It's passed a dict of unicode
212 strings bound to template names. This loader is useful for unittesting:
214 >>> loader = DictLoader({'index.html': 'source here'})
216 Because auto reloading is rarely useful this is disabled per default.
219 def __init__(self, mapping):
220 self.mapping = mapping
222 def get_source(self, environment, template):
223 if template in self.mapping:
224 source = self.mapping[template]
225 return source, None, lambda: source != self.mapping.get(template)
226 raise TemplateNotFound(template)
229 class FunctionLoader(BaseLoader):
230 """A loader that is passed a function which does the loading. The
231 function becomes the name of the template passed and has to return either
232 an unicode string with the template source, a tuple in the form ``(source,
233 filename, uptodatefunc)`` or `None` if the template does not exist.
235 >>> def load_template(name):
236 ... if name == 'index.html':
239 >>> loader = FunctionLoader(load_template)
241 The `uptodatefunc` is a function that is called if autoreload is enabled
242 and has to return `True` if the template is still up to date. For more
243 details have a look at :meth:`BaseLoader.get_source` which has the same
247 def __init__(self, load_func):
248 self.load_func = load_func
250 def get_source(self, environment, template):
251 rv = self.load_func(template)
253 raise TemplateNotFound(template)
254 elif isinstance(rv, basestring):
255 return rv, None, None
259 class PrefixLoader(BaseLoader):
260 """A loader that is passed a dict of loaders where each loader is bound
261 to a prefix. The prefix is delimited from the template by a slash per
262 default, which can be changed by setting the `delimiter` argument to
265 loader = PrefixLoader({
266 'app1': PackageLoader('mypackage.app1'),
267 'app2': PackageLoader('mypackage.app2')
270 By loading ``'app1/index.html'`` the file from the app1 package is loaded,
271 by loading ``'app2/index.html'`` the file from the second.
274 def __init__(self, mapping, delimiter='/'):
275 self.mapping = mapping
276 self.delimiter = delimiter
278 def get_source(self, environment, template):
280 prefix, name = template.split(self.delimiter, 1)
281 loader = self.mapping[prefix]
282 except (ValueError, KeyError):
283 raise TemplateNotFound(template)
285 return loader.get_source(environment, name)
286 except TemplateNotFound:
287 # re-raise the exception with the correct fileame here.
288 # (the one that includes the prefix)
289 raise TemplateNotFound(template)
292 class ChoiceLoader(BaseLoader):
293 """This loader works like the `PrefixLoader` just that no prefix is
294 specified. If a template could not be found by one loader the next one
297 >>> loader = ChoiceLoader([
298 ... FileSystemLoader('/path/to/user/templates'),
299 ... FileSystemLoader('/path/to/system/templates')
302 This is useful if you want to allow users to override builtin templates
303 from a different location.
306 def __init__(self, loaders):
307 self.loaders = loaders
309 def get_source(self, environment, template):
310 for loader in self.loaders:
312 return loader.get_source(environment, template)
313 except TemplateNotFound:
315 raise TemplateNotFound(template)