Armin Ronacher | 07bc684 | 2008-03-31 14:18:49 +0200 | [diff] [blame] | 1 | # -*- coding: utf-8 -*- |
| 2 | """ |
Armin Ronacher | bcb7c53 | 2008-04-11 16:30:34 +0200 | [diff] [blame] | 3 | jinja2.loaders |
| 4 | ~~~~~~~~~~~~~~ |
Armin Ronacher | 07bc684 | 2008-03-31 14:18:49 +0200 | [diff] [blame] | 5 | |
| 6 | Jinja loader classes. |
| 7 | |
Armin Ronacher | bcb7c53 | 2008-04-11 16:30:34 +0200 | [diff] [blame] | 8 | :copyright: 2008 by Armin Ronacher. |
Armin Ronacher | 07bc684 | 2008-03-31 14:18:49 +0200 | [diff] [blame] | 9 | :license: BSD, see LICENSE for more details. |
| 10 | """ |
Armin Ronacher | bcb7c53 | 2008-04-11 16:30:34 +0200 | [diff] [blame] | 11 | from os import path |
| 12 | from jinja2.exceptions import TemplateNotFound |
Armin Ronacher | 203bfcb | 2008-04-24 21:54:44 +0200 | [diff] [blame] | 13 | from jinja2.environment import template_from_code |
Armin Ronacher | 814f6c2 | 2008-04-17 15:52:23 +0200 | [diff] [blame] | 14 | from jinja2.utils import LRUCache |
Armin Ronacher | bcb7c53 | 2008-04-11 16:30:34 +0200 | [diff] [blame] | 15 | |
| 16 | |
Armin Ronacher | 9a82205 | 2008-04-17 18:44:07 +0200 | [diff] [blame] | 17 | def split_template_path(template): |
| 18 | """Split a path into segments and perform a sanity check. If it detects |
| 19 | '..' in the path it will raise a `TemplateNotFound` error. |
| 20 | """ |
| 21 | pieces = [] |
| 22 | for piece in template.split('/'): |
| 23 | if path.sep in piece \ |
| 24 | or (path.altsep and path.altsep in piece) or \ |
| 25 | piece == path.pardir: |
| 26 | raise TemplateNotFound(template) |
| 27 | elif piece != '.': |
| 28 | pieces.append(piece) |
| 29 | return pieces |
| 30 | |
| 31 | |
Armin Ronacher | bcb7c53 | 2008-04-11 16:30:34 +0200 | [diff] [blame] | 32 | class BaseLoader(object): |
Armin Ronacher | 203bfcb | 2008-04-24 21:54:44 +0200 | [diff] [blame] | 33 | """Baseclass for all loaders. Subclass this and override `get_source` to |
Armin Ronacher | d134231 | 2008-04-28 12:20:12 +0200 | [diff] [blame] | 34 | implement a custom loading mechanism. The environment provides a |
| 35 | `get_template` method that calls the loader's `load` method to get the |
| 36 | :class:`Template` object. |
Armin Ronacher | 814f6c2 | 2008-04-17 15:52:23 +0200 | [diff] [blame] | 37 | |
Armin Ronacher | d134231 | 2008-04-28 12:20:12 +0200 | [diff] [blame] | 38 | A very basic example for a loader that looks up templates on the file |
| 39 | system could look like this:: |
| 40 | |
| 41 | from jinja2 import BaseLoader, TemplateNotFound |
| 42 | from os.path import join, exists, getmtime |
| 43 | |
| 44 | class MyLoader(BaseLoader): |
| 45 | |
| 46 | def __init__(self, path, cache_size=50, auto_reload=True): |
| 47 | BaseLoader.__init__(self, cache_size, auto_reload) |
| 48 | self.path = path |
| 49 | |
| 50 | def get_source(self, environment, template): |
| 51 | path = join(self.path, template) |
| 52 | if not exists(path): |
| 53 | raise TemplateNotFound(template) |
| 54 | mtime = getmtime(path) |
| 55 | with file(path) as f: |
| 56 | source = f.read().decode('utf-8') |
| 57 | return source, path, lambda: mtime != getmtime(path) |
Armin Ronacher | 814f6c2 | 2008-04-17 15:52:23 +0200 | [diff] [blame] | 58 | """ |
| 59 | |
| 60 | def __init__(self, cache_size=50, auto_reload=True): |
Armin Ronacher | f41d139 | 2008-04-18 16:41:52 +0200 | [diff] [blame] | 61 | if cache_size == 0: |
Armin Ronacher | 814f6c2 | 2008-04-17 15:52:23 +0200 | [diff] [blame] | 62 | self.cache = None |
Armin Ronacher | f41d139 | 2008-04-18 16:41:52 +0200 | [diff] [blame] | 63 | elif cache_size < 0: |
| 64 | self.cache = {} |
| 65 | else: |
| 66 | self.cache = LRUCache(cache_size) |
Armin Ronacher | 814f6c2 | 2008-04-17 15:52:23 +0200 | [diff] [blame] | 67 | self.auto_reload = auto_reload |
Armin Ronacher | bcb7c53 | 2008-04-11 16:30:34 +0200 | [diff] [blame] | 68 | |
| 69 | def get_source(self, environment, template): |
Armin Ronacher | 814f6c2 | 2008-04-17 15:52:23 +0200 | [diff] [blame] | 70 | """Get the template source, filename and reload helper for a template. |
| 71 | It's passed the environment and template name and has to return a |
| 72 | tuple in the form ``(source, filename, uptodate)`` or raise a |
| 73 | `TemplateNotFound` error if it can't locate the template. |
| 74 | |
| 75 | The source part of the returned tuple must be the source of the |
| 76 | template as unicode string or a ASCII bytestring. The filename should |
| 77 | be the name of the file on the filesystem if it was loaded from there, |
| 78 | otherwise `None`. The filename is used by python for the tracebacks |
| 79 | if no loader extension is used. |
| 80 | |
| 81 | The last item in the tuple is the `uptodate` function. If auto |
| 82 | reloading is enabled it's always called to check if the template |
| 83 | changed. No arguments are passed so the function must store the |
| 84 | old state somewhere (for example in a closure). If it returns `False` |
| 85 | the template will be reloaded. |
| 86 | """ |
| 87 | raise TemplateNotFound(template) |
Armin Ronacher | bcb7c53 | 2008-04-11 16:30:34 +0200 | [diff] [blame] | 88 | |
Armin Ronacher | ba3757b | 2008-04-16 19:43:16 +0200 | [diff] [blame] | 89 | def load(self, environment, name, globals=None): |
Armin Ronacher | d134231 | 2008-04-28 12:20:12 +0200 | [diff] [blame] | 90 | """Loads a template. This method looks up the template in the cache |
| 91 | or loads one by calling :meth:`get_source`. Subclasses should not |
| 92 | override this method as loaders working on collections of other |
| 93 | loaders (such as :class:`PrefixLoader` or :class:`ChoiceLoader`) |
| 94 | will not call this method but `get_source` directly. |
Armin Ronacher | 814f6c2 | 2008-04-17 15:52:23 +0200 | [diff] [blame] | 95 | """ |
| 96 | if globals is None: |
| 97 | globals = {} |
| 98 | |
| 99 | if self.cache is not None: |
| 100 | template = self.cache.get(name) |
| 101 | if template is not None and (not self.auto_reload or \ |
Armin Ronacher | 9a82205 | 2008-04-17 18:44:07 +0200 | [diff] [blame] | 102 | template.is_up_to_date): |
Armin Ronacher | 814f6c2 | 2008-04-17 15:52:23 +0200 | [diff] [blame] | 103 | return template |
| 104 | |
| 105 | source, filename, uptodate = self.get_source(environment, name) |
| 106 | code = environment.compile(source, name, filename, globals) |
Armin Ronacher | 203bfcb | 2008-04-24 21:54:44 +0200 | [diff] [blame] | 107 | template = template_from_code(environment, code, globals, uptodate) |
Armin Ronacher | 814f6c2 | 2008-04-17 15:52:23 +0200 | [diff] [blame] | 108 | if self.cache is not None: |
| 109 | self.cache[name] = template |
| 110 | return template |
Armin Ronacher | bcb7c53 | 2008-04-11 16:30:34 +0200 | [diff] [blame] | 111 | |
| 112 | |
| 113 | class FileSystemLoader(BaseLoader): |
Armin Ronacher | d134231 | 2008-04-28 12:20:12 +0200 | [diff] [blame] | 114 | """Loads templates from the file system. This loader can find templates |
| 115 | in folders on the file system and is the preferred way to load them. |
| 116 | |
| 117 | The loader takes the path to the templates as string, or if multiple |
| 118 | locations are wanted a list of them which is then looked up in the |
| 119 | given order: |
| 120 | |
| 121 | >>> loader = FileSystemLoader('/path/to/templates') |
| 122 | >>> loader = FileSystemLoader(['/path/to/templates', '/other/path']) |
| 123 | |
| 124 | Per default the template encoding is ``'utf-8'`` which can be changed |
| 125 | by setting the `encoding` parameter to something else. |
| 126 | """ |
Armin Ronacher | bcb7c53 | 2008-04-11 16:30:34 +0200 | [diff] [blame] | 127 | |
Armin Ronacher | 814f6c2 | 2008-04-17 15:52:23 +0200 | [diff] [blame] | 128 | def __init__(self, searchpath, encoding='utf-8', cache_size=50, |
| 129 | auto_reload=True): |
| 130 | BaseLoader.__init__(self, cache_size, auto_reload) |
| 131 | if isinstance(searchpath, basestring): |
| 132 | searchpath = [searchpath] |
Armin Ronacher | d134231 | 2008-04-28 12:20:12 +0200 | [diff] [blame] | 133 | self.searchpath = list(searchpath) |
Armin Ronacher | bcb7c53 | 2008-04-11 16:30:34 +0200 | [diff] [blame] | 134 | self.encoding = encoding |
| 135 | |
| 136 | def get_source(self, environment, template): |
Armin Ronacher | 9a82205 | 2008-04-17 18:44:07 +0200 | [diff] [blame] | 137 | pieces = split_template_path(template) |
Armin Ronacher | 814f6c2 | 2008-04-17 15:52:23 +0200 | [diff] [blame] | 138 | for searchpath in self.searchpath: |
| 139 | filename = path.join(searchpath, *pieces) |
Armin Ronacher | 9a82205 | 2008-04-17 18:44:07 +0200 | [diff] [blame] | 140 | if not path.isfile(filename): |
| 141 | continue |
| 142 | f = file(filename) |
| 143 | try: |
| 144 | contents = f.read().decode(self.encoding) |
| 145 | finally: |
| 146 | f.close() |
| 147 | old = path.getmtime(filename) |
| 148 | return contents, filename, lambda: path.getmtime(filename) != old |
Armin Ronacher | 814f6c2 | 2008-04-17 15:52:23 +0200 | [diff] [blame] | 149 | raise TemplateNotFound(template) |
Armin Ronacher | 41ef36f | 2008-04-11 19:55:08 +0200 | [diff] [blame] | 150 | |
| 151 | |
Armin Ronacher | 9a82205 | 2008-04-17 18:44:07 +0200 | [diff] [blame] | 152 | class PackageLoader(BaseLoader): |
Armin Ronacher | d134231 | 2008-04-28 12:20:12 +0200 | [diff] [blame] | 153 | """Load templates from python eggs or packages. It is constructed with |
| 154 | the name of the python package and the path to the templates in that |
| 155 | package: |
Armin Ronacher | 9a82205 | 2008-04-17 18:44:07 +0200 | [diff] [blame] | 156 | |
Armin Ronacher | d134231 | 2008-04-28 12:20:12 +0200 | [diff] [blame] | 157 | >>> loader = PackageLoader('mypackage', 'views') |
| 158 | |
| 159 | If the package path is not given, ``'templates'`` is assumed. |
| 160 | |
| 161 | Per default the template encoding is ``'utf-8'`` which can be changed |
| 162 | by setting the `encoding` parameter to something else. Due to the nature |
| 163 | of eggs it's only possible to reload templates if the package was loaded |
| 164 | from the file system and not a zip file. |
| 165 | """ |
| 166 | |
| 167 | def __init__(self, package_name, package_path='templates', |
| 168 | encoding='utf-8', cache_size=50, auto_reload=True): |
Armin Ronacher | 9a82205 | 2008-04-17 18:44:07 +0200 | [diff] [blame] | 169 | BaseLoader.__init__(self, cache_size, auto_reload) |
Armin Ronacher | d134231 | 2008-04-28 12:20:12 +0200 | [diff] [blame] | 170 | from pkg_resources import DefaultProvider, ResourceManager, get_provider |
| 171 | provider = get_provider(package_name) |
| 172 | self.encoding = encoding |
| 173 | self.manager = ResourceManager() |
| 174 | self.filesystem_bound = isinstance(provider, DefaultProvider) |
| 175 | self.provider = provider |
Armin Ronacher | 9a82205 | 2008-04-17 18:44:07 +0200 | [diff] [blame] | 176 | self.package_path = package_path |
| 177 | |
| 178 | def get_source(self, environment, template): |
Armin Ronacher | 963f97d | 2008-04-25 11:44:59 +0200 | [diff] [blame] | 179 | pieces = split_template_path(template) |
Armin Ronacher | d134231 | 2008-04-28 12:20:12 +0200 | [diff] [blame] | 180 | p = '/'.join((self.package_path,) + tuple(pieces)) |
| 181 | if not self.provider.has_resource(p): |
Armin Ronacher | 9a82205 | 2008-04-17 18:44:07 +0200 | [diff] [blame] | 182 | raise TemplateNotFound(template) |
Armin Ronacher | d134231 | 2008-04-28 12:20:12 +0200 | [diff] [blame] | 183 | |
| 184 | filename = uptodate = None |
| 185 | if self.filesystem_bound: |
| 186 | filename = self.provider.get_resource_filename(self.manager, p) |
| 187 | mtime = path.getmtime(filename) |
| 188 | def uptodate(): |
| 189 | return path.getmtime(filename) != mtime |
| 190 | |
| 191 | source = self.provider.get_resource_string(self.manager, p) |
| 192 | return source.decode(self.encoding), filename, uptodate |
Armin Ronacher | 9a82205 | 2008-04-17 18:44:07 +0200 | [diff] [blame] | 193 | |
| 194 | |
Armin Ronacher | 41ef36f | 2008-04-11 19:55:08 +0200 | [diff] [blame] | 195 | class DictLoader(BaseLoader): |
Armin Ronacher | d134231 | 2008-04-28 12:20:12 +0200 | [diff] [blame] | 196 | """Loads a template from a python dict. It's passed a dict of unicode |
| 197 | strings bound to template names. This loader is useful for unittesting: |
Armin Ronacher | 41ef36f | 2008-04-11 19:55:08 +0200 | [diff] [blame] | 198 | |
Armin Ronacher | d134231 | 2008-04-28 12:20:12 +0200 | [diff] [blame] | 199 | >>> loader = DictLoader({'index.html': 'source here'}) |
| 200 | |
| 201 | Because auto reloading is rarely useful this is disabled per default. |
| 202 | """ |
| 203 | |
| 204 | def __init__(self, mapping, cache_size=50, auto_reload=False): |
| 205 | BaseLoader.__init__(self, cache_size, auto_reload) |
Armin Ronacher | 41ef36f | 2008-04-11 19:55:08 +0200 | [diff] [blame] | 206 | self.mapping = mapping |
| 207 | |
| 208 | def get_source(self, environment, template): |
| 209 | if template in self.mapping: |
Armin Ronacher | d134231 | 2008-04-28 12:20:12 +0200 | [diff] [blame] | 210 | source = self.mapping[template] |
| 211 | return source, None, lambda: source != self.mapping[template] |
Armin Ronacher | 41ef36f | 2008-04-11 19:55:08 +0200 | [diff] [blame] | 212 | raise TemplateNotFound(template) |
Armin Ronacher | 203bfcb | 2008-04-24 21:54:44 +0200 | [diff] [blame] | 213 | |
| 214 | |
| 215 | class FunctionLoader(BaseLoader): |
| 216 | """A loader that is passed a function which does the loading. The |
Armin Ronacher | 963f97d | 2008-04-25 11:44:59 +0200 | [diff] [blame] | 217 | function becomes the name of the template passed and has to return either |
| 218 | an unicode string with the template source, a tuple in the form ``(source, |
| 219 | filename, uptodatefunc)`` or `None` if the template does not exist. |
Armin Ronacher | d134231 | 2008-04-28 12:20:12 +0200 | [diff] [blame] | 220 | |
| 221 | >>> def load_template(name): |
| 222 | ... if name == 'index.html' |
| 223 | ... return '...' |
| 224 | ... |
| 225 | >>> loader = FunctionLoader(load_template) |
| 226 | |
| 227 | The `uptodatefunc` is a function that is called if autoreload is enabled |
| 228 | and has to return `True` if the template is still up to date. For more |
| 229 | details have a look at :meth:`BaseLoader.get_source` which has the same |
| 230 | return value. |
Armin Ronacher | 203bfcb | 2008-04-24 21:54:44 +0200 | [diff] [blame] | 231 | """ |
| 232 | |
| 233 | def __init__(self, load_func, cache_size=50, auto_reload=True): |
| 234 | BaseLoader.__init__(self, cache_size, auto_reload) |
| 235 | self.load_func = load_func |
| 236 | |
| 237 | def get_source(self, environment, template): |
Armin Ronacher | 963f97d | 2008-04-25 11:44:59 +0200 | [diff] [blame] | 238 | rv = self.load_func(template) |
Armin Ronacher | 203bfcb | 2008-04-24 21:54:44 +0200 | [diff] [blame] | 239 | if rv is None: |
| 240 | raise TemplateNotFound(template) |
Armin Ronacher | 963f97d | 2008-04-25 11:44:59 +0200 | [diff] [blame] | 241 | elif isinstance(rv, basestring): |
| 242 | return rv, None, None |
Armin Ronacher | 203bfcb | 2008-04-24 21:54:44 +0200 | [diff] [blame] | 243 | return rv |
| 244 | |
| 245 | |
| 246 | class PrefixLoader(BaseLoader): |
| 247 | """A loader that is passed a dict of loaders where each loader is bound |
| 248 | to a prefix. The caching is independent of the actual loaders so the |
| 249 | per loader cache settings are ignored. The prefix is delimited from the |
Armin Ronacher | d134231 | 2008-04-28 12:20:12 +0200 | [diff] [blame] | 250 | template by a slash: |
| 251 | |
| 252 | >>> loader = PrefixLoader({ |
| 253 | ... 'app1': PackageLoader('mypackage.app1'), |
| 254 | ... 'app2': PackageLoader('mypackage.app2') |
| 255 | ... }) |
| 256 | |
| 257 | By loading ``'app1/index.html'`` the file from the app1 package is loaded, |
| 258 | by loading ``'app2/index.html'`` the file from the second. |
Armin Ronacher | 203bfcb | 2008-04-24 21:54:44 +0200 | [diff] [blame] | 259 | """ |
| 260 | |
| 261 | def __init__(self, mapping, delimiter='/', cache_size=50, |
| 262 | auto_reload=True): |
| 263 | BaseLoader.__init__(self, cache_size, auto_reload) |
| 264 | self.mapping = mapping |
| 265 | self.delimiter = delimiter |
| 266 | |
| 267 | def get_source(self, environment, template): |
| 268 | try: |
| 269 | prefix, template = template.split(self.delimiter, 1) |
| 270 | loader = self.mapping[prefix] |
| 271 | except (ValueError, KeyError): |
| 272 | raise TemplateNotFound(template) |
| 273 | return loader.get_source(environment, template) |
| 274 | |
| 275 | |
| 276 | class ChoiceLoader(BaseLoader): |
| 277 | """This loader works like the `PrefixLoader` just that no prefix is |
| 278 | specified. If a template could not be found by one loader the next one |
| 279 | is tried. Like for the `PrefixLoader` the cache settings of the actual |
| 280 | loaders don't matter as the choice loader does the caching. |
Armin Ronacher | d134231 | 2008-04-28 12:20:12 +0200 | [diff] [blame] | 281 | |
| 282 | >>> loader = ChoiceLoader([ |
| 283 | ... FileSystemLoader('/path/to/user/templates'), |
| 284 | ... PackageLoader('myapplication') |
| 285 | ]) |
| 286 | |
| 287 | This is useful if you want to allow users to override builtin templates |
| 288 | from a different location. |
Armin Ronacher | 203bfcb | 2008-04-24 21:54:44 +0200 | [diff] [blame] | 289 | """ |
| 290 | |
| 291 | def __init__(self, loaders, cache_size=50, auto_reload=True): |
| 292 | BaseLoader.__init__(self, cache_size, auto_reload) |
| 293 | self.loaders = loaders |
| 294 | |
| 295 | def get_source(self, environment, template): |
| 296 | for loader in self.loaders: |
| 297 | try: |
| 298 | return loader.get_source(environment, template) |
| 299 | except TemplateNotFound: |
| 300 | pass |
| 301 | raise TemplateNotFound(template) |