1 # -*- coding: utf-8 -*- 2 """ 3 jinja2.loaders 4 ~~~~~~~~~~~~~~ 5 6 Jinja loader classes. 7 8 :copyright: (c) 2010 by the Jinja Team. 9 :license: BSD, see LICENSE for more details. 10 """ 11 import os 12 import sys 13 import weakref 14 from types import ModuleType 15 from os import path 16 from hashlib import sha1 17 from jinja2.exceptions import TemplateNotFound 18 from jinja2.utils import open_if_exists, internalcode 19 from jinja2._compat import string_types, iteritems 20 21 22 def split_template_path(template): 23 """Split a path into segments and perform a sanity check. If it detects 24 '..' in the path it will raise a `TemplateNotFound` error. 25 """ 26 pieces = [] 27 for piece in template.split('/'): 28 if path.sep in piece \ 29 or (path.altsep and path.altsep in piece) or \ 30 piece == path.pardir: 31 raise TemplateNotFound(template) 32 elif piece and piece != '.': 33 pieces.append(piece) 34 return pieces 35 36 37 class BaseLoader(object): 38 """Baseclass for all loaders. Subclass this and override `get_source` to 39 implement a custom loading mechanism. The environment provides a 40 `get_template` method that calls the loader's `load` method to get the 41 :class:`Template` object. 42 43 A very basic example for a loader that looks up templates on the file 44 system could look like this:: 45 46 from jinja2 import BaseLoader, TemplateNotFound 47 from os.path import join, exists, getmtime 48 49 class MyLoader(BaseLoader): 50 51 def __init__(self, path): 52 self.path = path 53 54 def get_source(self, environment, template): 55 path = join(self.path, template) 56 if not exists(path): 57 raise TemplateNotFound(template) 58 mtime = getmtime(path) 59 with file(path) as f: 60 source = f.read().decode('utf-8') 61 return source, path, lambda: mtime == getmtime(path) 62 """ 63 64 #: if set to `False` it indicates that the loader cannot provide access 65 #: to the source of templates. 66 #: 67 #: .. versionadded:: 2.4 68 has_source_access = True 69 70 def get_source(self, environment, template): 71 """Get the template source, filename and reload helper for a template. 72 It's passed the environment and template name and has to return a 73 tuple in the form ``(source, filename, uptodate)`` or raise a 74 `TemplateNotFound` error if it can't locate the template. 75 76 The source part of the returned tuple must be the source of the 77 template as unicode string or a ASCII bytestring. The filename should 78 be the name of the file on the filesystem if it was loaded from there, 79 otherwise `None`. The filename is used by python for the tracebacks 80 if no loader extension is used. 81 82 The last item in the tuple is the `uptodate` function. If auto 83 reloading is enabled it's always called to check if the template 84 changed. No arguments are passed so the function must store the 85 old state somewhere (for example in a closure). If it returns `False` 86 the template will be reloaded. 87 """ 88 if not self.has_source_access: 89 raise RuntimeError('%s cannot provide access to the source' % 90 self.__class__.__name__) 91 raise TemplateNotFound(template) 92 93 def list_templates(self): 94 """Iterates over all templates. If the loader does not support that 95 it should raise a :exc:`TypeError` which is the default behavior. 96 """ 97 raise TypeError('this loader cannot iterate over all templates') 98 99 @internalcode 100 def load(self, environment, name, globals=None): 101 """Loads a template. This method looks up the template in the cache 102 or loads one by calling :meth:`get_source`. Subclasses should not 103 override this method as loaders working on collections of other 104 loaders (such as :class:`PrefixLoader` or :class:`ChoiceLoader`) 105 will not call this method but `get_source` directly. 106 """ 107 code = None 108 if globals is None: 109 globals = {} 110 111 # first we try to get the source for this template together 112 # with the filename and the uptodate function. 113 source, filename, uptodate = self.get_source(environment, name) 114 115 # try to load the code from the bytecode cache if there is a 116 # bytecode cache configured. 117 bcc = environment.bytecode_cache 118 if bcc is not None: 119 bucket = bcc.get_bucket(environment, name, filename, source) 120 code = bucket.code 121 122 # if we don't have code so far (not cached, no longer up to 123 # date) etc. we compile the template 124 if code is None: 125 code = environment.compile(source, name, filename) 126 127 # if the bytecode cache is available and the bucket doesn't 128 # have a code so far, we give the bucket the new code and put 129 # it back to the bytecode cache. 130 if bcc is not None and bucket.code is None: 131 bucket.code = code 132 bcc.set_bucket(bucket) 133 134 return environment.template_class.from_code(environment, code, 135 globals, uptodate) 136 137 138 class FileSystemLoader(BaseLoader): 139 """Loads templates from the file system. This loader can find templates 140 in folders on the file system and is the preferred way to load them. 141 142 The loader takes the path to the templates as string, or if multiple 143 locations are wanted a list of them which is then looked up in the 144 given order: 145 146 >>> loader = FileSystemLoader('/path/to/templates') 147 >>> loader = FileSystemLoader(['/path/to/templates', '/other/path']) 148 149 Per default the template encoding is ``'utf-8'`` which can be changed 150 by setting the `encoding` parameter to something else. 151 """ 152 153 def __init__(self, searchpath, encoding='utf-8'): 154 if isinstance(searchpath, string_types): 155 searchpath = [searchpath] 156 self.searchpath = list(searchpath) 157 self.encoding = encoding 158 159 def get_source(self, environment, template): 160 pieces = split_template_path(template) 161 for searchpath in self.searchpath: 162 filename = path.join(searchpath, *pieces) 163 f = open_if_exists(filename) 164 if f is None: 165 continue 166 try: 167 contents = f.read().decode(self.encoding) 168 finally: 169 f.close() 170 171 mtime = path.getmtime(filename) 172 def uptodate(): 173 try: 174 return path.getmtime(filename) == mtime 175 except OSError: 176 return False 177 return contents, filename, uptodate 178 raise TemplateNotFound(template) 179 180 def list_templates(self): 181 found = set() 182 for searchpath in self.searchpath: 183 for dirpath, dirnames, filenames in os.walk(searchpath): 184 for filename in filenames: 185 template = os.path.join(dirpath, filename) \ 186 [len(searchpath):].strip(os.path.sep) \ 187 .replace(os.path.sep, '/') 188 if template[:2] == './': 189 template = template[2:] 190 if template not in found: 191 found.add(template) 192 return sorted(found) 193 194 195 class PackageLoader(BaseLoader): 196 """Load templates from python eggs or packages. It is constructed with 197 the name of the python package and the path to the templates in that 198 package:: 199 200 loader = PackageLoader('mypackage', 'views') 201 202 If the package path is not given, ``'templates'`` is assumed. 203 204 Per default the template encoding is ``'utf-8'`` which can be changed 205 by setting the `encoding` parameter to something else. Due to the nature 206 of eggs it's only possible to reload templates if the package was loaded 207 from the file system and not a zip file. 208 """ 209 210 def __init__(self, package_name, package_path='templates', 211 encoding='utf-8'): 212 from pkg_resources import DefaultProvider, ResourceManager, \ 213 get_provider 214 provider = get_provider(package_name) 215 self.encoding = encoding 216 self.manager = ResourceManager() 217 self.filesystem_bound = isinstance(provider, DefaultProvider) 218 self.provider = provider 219 self.package_path = package_path 220 221 def get_source(self, environment, template): 222 pieces = split_template_path(template) 223 p = '/'.join((self.package_path,) + tuple(pieces)) 224 if not self.provider.has_resource(p): 225 raise TemplateNotFound(template) 226 227 filename = uptodate = None 228 if self.filesystem_bound: 229 filename = self.provider.get_resource_filename(self.manager, p) 230 mtime = path.getmtime(filename) 231 def uptodate(): 232 try: 233 return path.getmtime(filename) == mtime 234 except OSError: 235 return False 236 237 source = self.provider.get_resource_string(self.manager, p) 238 return source.decode(self.encoding), filename, uptodate 239 240 def list_templates(self): 241 path = self.package_path 242 if path[:2] == './': 243 path = path[2:] 244 elif path == '.': 245 path = '' 246 offset = len(path) 247 results = [] 248 def _walk(path): 249 for filename in self.provider.resource_listdir(path): 250 fullname = path + '/' + filename 251 if self.provider.resource_isdir(fullname): 252 _walk(fullname) 253 else: 254 results.append(fullname[offset:].lstrip('/')) 255 _walk(path) 256 results.sort() 257 return results 258 259 260 class DictLoader(BaseLoader): 261 """Loads a template from a python dict. It's passed a dict of unicode 262 strings bound to template names. This loader is useful for unittesting: 263 264 >>> loader = DictLoader({'index.html': 'source here'}) 265 266 Because auto reloading is rarely useful this is disabled per default. 267 """ 268 269 def __init__(self, mapping): 270 self.mapping = mapping 271 272 def get_source(self, environment, template): 273 if template in self.mapping: 274 source = self.mapping[template] 275 return source, None, lambda: source == self.mapping.get(template) 276 raise TemplateNotFound(template) 277 278 def list_templates(self): 279 return sorted(self.mapping) 280 281 282 class FunctionLoader(BaseLoader): 283 """A loader that is passed a function which does the loading. The 284 function becomes the name of the template passed and has to return either 285 an unicode string with the template source, a tuple in the form ``(source, 286 filename, uptodatefunc)`` or `None` if the template does not exist. 287 288 >>> def load_template(name): 289 ... if name == 'index.html': 290 ... return '...' 291 ... 292 >>> loader = FunctionLoader(load_template) 293 294 The `uptodatefunc` is a function that is called if autoreload is enabled 295 and has to return `True` if the template is still up to date. For more 296 details have a look at :meth:`BaseLoader.get_source` which has the same 297 return value. 298 """ 299 300 def __init__(self, load_func): 301 self.load_func = load_func 302 303 def get_source(self, environment, template): 304 rv = self.load_func(template) 305 if rv is None: 306 raise TemplateNotFound(template) 307 elif isinstance(rv, string_types): 308 return rv, None, None 309 return rv 310 311 312 class PrefixLoader(BaseLoader): 313 """A loader that is passed a dict of loaders where each loader is bound 314 to a prefix. The prefix is delimited from the template by a slash per 315 default, which can be changed by setting the `delimiter` argument to 316 something else:: 317 318 loader = PrefixLoader({ 319 'app1': PackageLoader('mypackage.app1'), 320 'app2': PackageLoader('mypackage.app2') 321 }) 322 323 By loading ``'app1/index.html'`` the file from the app1 package is loaded, 324 by loading ``'app2/index.html'`` the file from the second. 325 """ 326 327 def __init__(self, mapping, delimiter='/'): 328 self.mapping = mapping 329 self.delimiter = delimiter 330 331 def get_loader(self, template): 332 try: 333 prefix, name = template.split(self.delimiter, 1) 334 loader = self.mapping[prefix] 335 except (ValueError, KeyError): 336 raise TemplateNotFound(template) 337 return loader, name 338 339 def get_source(self, environment, template): 340 loader, name = self.get_loader(template) 341 try: 342 return loader.get_source(environment, name) 343 except TemplateNotFound: 344 # re-raise the exception with the correct fileame here. 345 # (the one that includes the prefix) 346 raise TemplateNotFound(template) 347 348 @internalcode 349 def load(self, environment, name, globals=None): 350 loader, local_name = self.get_loader(name) 351 try: 352 return loader.load(environment, local_name) 353 except TemplateNotFound: 354 # re-raise the exception with the correct fileame here. 355 # (the one that includes the prefix) 356 raise TemplateNotFound(name) 357 358 def list_templates(self): 359 result = [] 360 for prefix, loader in iteritems(self.mapping): 361 for template in loader.list_templates(): 362 result.append(prefix + self.delimiter + template) 363 return result 364 365 366 class ChoiceLoader(BaseLoader): 367 """This loader works like the `PrefixLoader` just that no prefix is 368 specified. If a template could not be found by one loader the next one 369 is tried. 370 371 >>> loader = ChoiceLoader([ 372 ... FileSystemLoader('/path/to/user/templates'), 373 ... FileSystemLoader('/path/to/system/templates') 374 ... ]) 375 376 This is useful if you want to allow users to override builtin templates 377 from a different location. 378 """ 379 380 def __init__(self, loaders): 381 self.loaders = loaders 382 383 def get_source(self, environment, template): 384 for loader in self.loaders: 385 try: 386 return loader.get_source(environment, template) 387 except TemplateNotFound: 388 pass 389 raise TemplateNotFound(template) 390 391 @internalcode 392 def load(self, environment, name, globals=None): 393 for loader in self.loaders: 394 try: 395 return loader.load(environment, name, globals) 396 except TemplateNotFound: 397 pass 398 raise TemplateNotFound(name) 399 400 def list_templates(self): 401 found = set() 402 for loader in self.loaders: 403 found.update(loader.list_templates()) 404 return sorted(found) 405 406 407 class _TemplateModule(ModuleType): 408 """Like a normal module but with support for weak references""" 409 410 411 class ModuleLoader(BaseLoader): 412 """This loader loads templates from precompiled templates. 413 414 Example usage: 415 416 >>> loader = ChoiceLoader([ 417 ... ModuleLoader('/path/to/compiled/templates'), 418 ... FileSystemLoader('/path/to/templates') 419 ... ]) 420 421 Templates can be precompiled with :meth:`Environment.compile_templates`. 422 """ 423 424 has_source_access = False 425 426 def __init__(self, path): 427 package_name = '_jinja2_module_templates_%x' % id(self) 428 429 # create a fake module that looks for the templates in the 430 # path given. 431 mod = _TemplateModule(package_name) 432 if isinstance(path, string_types): 433 path = [path] 434 else: 435 path = list(path) 436 mod.__path__ = path 437 438 sys.modules[package_name] = weakref.proxy(mod, 439 lambda x: sys.modules.pop(package_name, None)) 440 441 # the only strong reference, the sys.modules entry is weak 442 # so that the garbage collector can remove it once the 443 # loader that created it goes out of business. 444 self.module = mod 445 self.package_name = package_name 446 447 @staticmethod 448 def get_template_key(name): 449 return 'tmpl_' + sha1(name.encode('utf-8')).hexdigest() 450 451 @staticmethod 452 def get_module_filename(name): 453 return ModuleLoader.get_template_key(name) + '.py' 454 455 @internalcode 456 def load(self, environment, name, globals=None): 457 key = self.get_template_key(name) 458 module = '%s.%s' % (self.package_name, key) 459 mod = getattr(self.module, module, None) 460 if mod is None: 461 try: 462 mod = __import__(module, None, None, ['root']) 463 except ImportError: 464 raise TemplateNotFound(name) 465 466 # remove the entry from sys.modules, we only want the attribute 467 # on the module object we have stored on the loader. 468 sys.modules.pop(module, None) 469 470 return environment.template_class.from_module_dict( 471 environment, mod.__dict__, globals) 472
