Armin Ronacher | 07bc684 | 2008-03-31 14:18:49 +0200 | [diff] [blame] | 1 | # -*- coding: utf-8 -*- |
| 2 | """ |
Armin Ronacher | 82b3f3d | 2008-03-31 20:01:08 +0200 | [diff] [blame] | 3 | jinja2.environment |
| 4 | ~~~~~~~~~~~~~~~~~~ |
Armin Ronacher | 07bc684 | 2008-03-31 14:18:49 +0200 | [diff] [blame] | 5 | |
| 6 | Provides a class that holds runtime and parsing time options. |
| 7 | |
Armin Ronacher | 19cf9c2 | 2008-05-01 12:49:53 +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 | ba3757b | 2008-04-16 19:43:16 +0200 | [diff] [blame] | 11 | import sys |
Armin Ronacher | 7259c76 | 2008-04-30 13:03:59 +0200 | [diff] [blame] | 12 | from jinja2.defaults import * |
Armin Ronacher | 82b3f3d | 2008-03-31 20:01:08 +0200 | [diff] [blame] | 13 | from jinja2.lexer import Lexer |
Armin Ronacher | 0553093 | 2008-04-20 13:27:49 +0200 | [diff] [blame] | 14 | from jinja2.parser import Parser |
Armin Ronacher | bcb7c53 | 2008-04-11 16:30:34 +0200 | [diff] [blame] | 15 | from jinja2.optimizer import optimize |
| 16 | from jinja2.compiler import generate |
Armin Ronacher | 19cf9c2 | 2008-05-01 12:49:53 +0200 | [diff] [blame] | 17 | from jinja2.runtime import Undefined, Context, concat |
Armin Ronacher | aaf010d | 2008-05-01 13:14:30 +0200 | [diff] [blame] | 18 | from jinja2.debug import translate_exception, translate_syntax_error |
| 19 | from jinja2.exceptions import TemplateSyntaxError |
Armin Ronacher | 7259c76 | 2008-04-30 13:03:59 +0200 | [diff] [blame] | 20 | from jinja2.utils import import_string, LRUCache, Markup, missing |
Armin Ronacher | 07bc684 | 2008-03-31 14:18:49 +0200 | [diff] [blame] | 21 | |
| 22 | |
Armin Ronacher | 203bfcb | 2008-04-24 21:54:44 +0200 | [diff] [blame] | 23 | # for direct template usage we have up to ten living environments |
| 24 | _spontaneous_environments = LRUCache(10) |
| 25 | |
| 26 | |
Armin Ronacher | b5124e6 | 2008-04-25 00:36:14 +0200 | [diff] [blame] | 27 | def get_spontaneous_environment(*args): |
Armin Ronacher | 203bfcb | 2008-04-24 21:54:44 +0200 | [diff] [blame] | 28 | """Return a new spontaneus environment. A spontaneus environment is an |
| 29 | unnamed and unaccessable (in theory) environment that is used for |
| 30 | template generated from a string and not from the file system. |
| 31 | """ |
| 32 | try: |
| 33 | env = _spontaneous_environments.get(args) |
| 34 | except TypeError: |
| 35 | return Environment(*args) |
| 36 | if env is not None: |
| 37 | return env |
| 38 | _spontaneous_environments[args] = env = Environment(*args) |
Armin Ronacher | c9705c2 | 2008-04-27 21:28:03 +0200 | [diff] [blame] | 39 | env.shared = True |
Armin Ronacher | 203bfcb | 2008-04-24 21:54:44 +0200 | [diff] [blame] | 40 | return env |
| 41 | |
| 42 | |
Armin Ronacher | 7259c76 | 2008-04-30 13:03:59 +0200 | [diff] [blame] | 43 | def create_cache(size): |
| 44 | """Return the cache class for the given size.""" |
| 45 | if size == 0: |
| 46 | return None |
| 47 | if size < 0: |
| 48 | return {} |
| 49 | return LRUCache(size) |
| 50 | |
| 51 | |
| 52 | def load_extensions(environment, extensions): |
| 53 | """Load the extensions from the list and bind it to the environment. |
| 54 | Returns a new list of instanciated environments. |
Armin Ronacher | 203bfcb | 2008-04-24 21:54:44 +0200 | [diff] [blame] | 55 | """ |
Armin Ronacher | 7259c76 | 2008-04-30 13:03:59 +0200 | [diff] [blame] | 56 | result = [] |
| 57 | for extension in extensions: |
| 58 | if isinstance(extension, basestring): |
| 59 | extension = import_string(extension) |
| 60 | result.append(extension(environment)) |
| 61 | return result |
Armin Ronacher | 203bfcb | 2008-04-24 21:54:44 +0200 | [diff] [blame] | 62 | |
Armin Ronacher | 203bfcb | 2008-04-24 21:54:44 +0200 | [diff] [blame] | 63 | |
Armin Ronacher | 7259c76 | 2008-04-30 13:03:59 +0200 | [diff] [blame] | 64 | def _environment_sanity_check(environment): |
| 65 | """Perform a sanity check on the environment.""" |
| 66 | assert issubclass(environment.undefined, Undefined), 'undefined must ' \ |
| 67 | 'be a subclass of undefined because filters depend on it.' |
| 68 | assert environment.block_start_string != \ |
| 69 | environment.variable_start_string != \ |
| 70 | environment.comment_start_string, 'block, variable and comment ' \ |
| 71 | 'start strings must be different' |
Armin Ronacher | 19cf9c2 | 2008-05-01 12:49:53 +0200 | [diff] [blame] | 72 | return environment |
Armin Ronacher | 203bfcb | 2008-04-24 21:54:44 +0200 | [diff] [blame] | 73 | |
| 74 | |
Armin Ronacher | 07bc684 | 2008-03-31 14:18:49 +0200 | [diff] [blame] | 75 | class Environment(object): |
Armin Ronacher | d134231 | 2008-04-28 12:20:12 +0200 | [diff] [blame] | 76 | """The core component of Jinja is the `Environment`. It contains |
Armin Ronacher | 07bc684 | 2008-03-31 14:18:49 +0200 | [diff] [blame] | 77 | important shared variables like configuration, filters, tests, |
Armin Ronacher | d134231 | 2008-04-28 12:20:12 +0200 | [diff] [blame] | 78 | globals and others. Instances of this class may be modified if |
| 79 | they are not shared and if no template was loaded so far. |
| 80 | Modifications on environments after the first template was loaded |
| 81 | will lead to surprising effects and undefined behavior. |
| 82 | |
| 83 | Here the possible initialization parameters: |
| 84 | |
| 85 | `block_start_string` |
| 86 | The string marking the begin of a block. Defaults to ``'{%'``. |
| 87 | |
| 88 | `block_end_string` |
| 89 | The string marking the end of a block. Defaults to ``'%}'``. |
| 90 | |
| 91 | `variable_start_string` |
| 92 | The string marking the begin of a print statement. |
| 93 | Defaults to ``'{{'``. |
Armin Ronacher | 115de2e | 2008-05-01 22:20:05 +0200 | [diff] [blame] | 94 | |
Lukas Meuser | ad48a2e | 2008-05-01 18:19:57 +0200 | [diff] [blame] | 95 | `variable_stop_string` |
| 96 | The string marking the end of a print statement. Defaults to ``'}}'``. |
Armin Ronacher | d134231 | 2008-04-28 12:20:12 +0200 | [diff] [blame] | 97 | |
| 98 | `comment_start_string` |
| 99 | The string marking the begin of a comment. Defaults to ``'{#'``. |
| 100 | |
| 101 | `comment_end_string` |
| 102 | The string marking the end of a comment. Defaults to ``'#}'``. |
| 103 | |
| 104 | `line_statement_prefix` |
| 105 | If given and a string, this will be used as prefix for line based |
| 106 | statements. |
| 107 | |
| 108 | `trim_blocks` |
| 109 | If this is set to ``True`` the first newline after a block is |
| 110 | removed (block, not variable tag!). Defaults to `False`. |
| 111 | |
| 112 | `extensions` |
| 113 | List of Jinja extensions to use. This can either be import paths |
| 114 | as strings or extension classes. |
| 115 | |
| 116 | `optimized` |
| 117 | should the optimizer be enabled? Default is `True`. |
| 118 | |
| 119 | `undefined` |
| 120 | :class:`Undefined` or a subclass of it that is used to represent |
| 121 | undefined values in the template. |
| 122 | |
| 123 | `finalize` |
| 124 | A callable that finalizes the variable. Per default no finalizing |
| 125 | is applied. |
| 126 | |
| 127 | `autoescape` |
| 128 | If set to true the XML/HTML autoescaping feature is enabled. |
| 129 | |
| 130 | `loader` |
| 131 | The template loader for this environment. |
Armin Ronacher | 7259c76 | 2008-04-30 13:03:59 +0200 | [diff] [blame] | 132 | |
| 133 | `cache_size` |
| 134 | The size of the cache. Per default this is ``50`` which means that if |
| 135 | more than 50 templates are loaded the loader will clean out the least |
| 136 | recently used template. If the cache size is set to ``0`` templates are |
| 137 | recompiled all the time, if the cache size is ``-1`` the cache will not |
| 138 | be cleaned. |
| 139 | |
| 140 | `auto_reload` |
| 141 | Some loaders load templates from locations where the template sources |
| 142 | may change (ie: file system or database). If `auto_reload` is set to |
| 143 | `True` (default) every time a template is requested the loader checks |
| 144 | if the source changed and if yes, it will reload the template. For |
| 145 | higher performance it's possible to disable that. |
Armin Ronacher | 07bc684 | 2008-03-31 14:18:49 +0200 | [diff] [blame] | 146 | """ |
| 147 | |
Armin Ronacher | c63243e | 2008-04-14 22:53:58 +0200 | [diff] [blame] | 148 | #: if this environment is sandboxed. Modifying this variable won't make |
| 149 | #: the environment sandboxed though. For a real sandboxed environment |
| 150 | #: have a look at jinja2.sandbox |
| 151 | sandboxed = False |
| 152 | |
Armin Ronacher | 7259c76 | 2008-04-30 13:03:59 +0200 | [diff] [blame] | 153 | #: True if the environment is just an overlay |
| 154 | overlay = False |
| 155 | |
Armin Ronacher | 19cf9c2 | 2008-05-01 12:49:53 +0200 | [diff] [blame] | 156 | #: the environment this environment is linked to if it is an overlay |
| 157 | linked_to = None |
| 158 | |
Armin Ronacher | c9705c2 | 2008-04-27 21:28:03 +0200 | [diff] [blame] | 159 | #: shared environments have this set to `True`. A shared environment |
| 160 | #: must not be modified |
| 161 | shared = False |
| 162 | |
Armin Ronacher | 07bc684 | 2008-03-31 14:18:49 +0200 | [diff] [blame] | 163 | def __init__(self, |
Armin Ronacher | 7259c76 | 2008-04-30 13:03:59 +0200 | [diff] [blame] | 164 | block_start_string=BLOCK_START_STRING, |
| 165 | block_end_string=BLOCK_END_STRING, |
| 166 | variable_start_string=VARIABLE_START_STRING, |
| 167 | variable_end_string=VARIABLE_END_STRING, |
| 168 | comment_start_string=COMMENT_START_STRING, |
| 169 | comment_end_string=COMMENT_END_STRING, |
| 170 | line_statement_prefix=LINE_STATEMENT_PREFIX, |
Armin Ronacher | 07bc684 | 2008-03-31 14:18:49 +0200 | [diff] [blame] | 171 | trim_blocks=False, |
Armin Ronacher | b5124e6 | 2008-04-25 00:36:14 +0200 | [diff] [blame] | 172 | extensions=(), |
Armin Ronacher | fed44b5 | 2008-04-13 19:42:53 +0200 | [diff] [blame] | 173 | optimized=True, |
Armin Ronacher | c63243e | 2008-04-14 22:53:58 +0200 | [diff] [blame] | 174 | undefined=Undefined, |
Armin Ronacher | d134231 | 2008-04-28 12:20:12 +0200 | [diff] [blame] | 175 | finalize=None, |
| 176 | autoescape=False, |
Armin Ronacher | 7259c76 | 2008-04-30 13:03:59 +0200 | [diff] [blame] | 177 | loader=None, |
| 178 | cache_size=50, |
| 179 | auto_reload=True): |
Armin Ronacher | b5124e6 | 2008-04-25 00:36:14 +0200 | [diff] [blame] | 180 | # !!Important notice!! |
| 181 | # The constructor accepts quite a few arguments that should be |
| 182 | # passed by keyword rather than position. However it's important to |
| 183 | # not change the order of arguments because it's used at least |
| 184 | # internally in those cases: |
| 185 | # - spontaneus environments (i18n extension and Template) |
| 186 | # - unittests |
| 187 | # If parameter changes are required only add parameters at the end |
| 188 | # and don't change the arguments (or the defaults!) of the arguments |
Armin Ronacher | 7259c76 | 2008-04-30 13:03:59 +0200 | [diff] [blame] | 189 | # existing already. |
Armin Ronacher | 07bc684 | 2008-03-31 14:18:49 +0200 | [diff] [blame] | 190 | |
| 191 | # lexer / parser information |
| 192 | self.block_start_string = block_start_string |
| 193 | self.block_end_string = block_end_string |
| 194 | self.variable_start_string = variable_start_string |
| 195 | self.variable_end_string = variable_end_string |
| 196 | self.comment_start_string = comment_start_string |
| 197 | self.comment_end_string = comment_end_string |
Armin Ronacher | bf7c4ad | 2008-04-12 12:02:36 +0200 | [diff] [blame] | 198 | self.line_statement_prefix = line_statement_prefix |
Armin Ronacher | 07bc684 | 2008-03-31 14:18:49 +0200 | [diff] [blame] | 199 | self.trim_blocks = trim_blocks |
Armin Ronacher | 203bfcb | 2008-04-24 21:54:44 +0200 | [diff] [blame] | 200 | |
Armin Ronacher | f59bac2 | 2008-04-20 13:11:43 +0200 | [diff] [blame] | 201 | # runtime information |
Armin Ronacher | c63243e | 2008-04-14 22:53:58 +0200 | [diff] [blame] | 202 | self.undefined = undefined |
Armin Ronacher | fed44b5 | 2008-04-13 19:42:53 +0200 | [diff] [blame] | 203 | self.optimized = optimized |
Armin Ronacher | 18c6ca0 | 2008-04-17 10:03:29 +0200 | [diff] [blame] | 204 | self.finalize = finalize |
Armin Ronacher | d134231 | 2008-04-28 12:20:12 +0200 | [diff] [blame] | 205 | self.autoescape = autoescape |
Armin Ronacher | 07bc684 | 2008-03-31 14:18:49 +0200 | [diff] [blame] | 206 | |
| 207 | # defaults |
| 208 | self.filters = DEFAULT_FILTERS.copy() |
| 209 | self.tests = DEFAULT_TESTS.copy() |
| 210 | self.globals = DEFAULT_NAMESPACE.copy() |
| 211 | |
Armin Ronacher | bcb7c53 | 2008-04-11 16:30:34 +0200 | [diff] [blame] | 212 | # set the loader provided |
| 213 | self.loader = loader |
Armin Ronacher | 7259c76 | 2008-04-30 13:03:59 +0200 | [diff] [blame] | 214 | self.cache = create_cache(cache_size) |
| 215 | self.auto_reload = auto_reload |
Armin Ronacher | 07bc684 | 2008-03-31 14:18:49 +0200 | [diff] [blame] | 216 | |
Armin Ronacher | b5124e6 | 2008-04-25 00:36:14 +0200 | [diff] [blame] | 217 | # load extensions |
Armin Ronacher | 7259c76 | 2008-04-30 13:03:59 +0200 | [diff] [blame] | 218 | self.extensions = load_extensions(self, extensions) |
| 219 | |
| 220 | _environment_sanity_check(self) |
| 221 | |
| 222 | def overlay(self, block_start_string=missing, block_end_string=missing, |
| 223 | variable_start_string=missing, variable_end_string=missing, |
| 224 | comment_start_string=missing, comment_end_string=missing, |
| 225 | line_statement_prefix=missing, trim_blocks=missing, |
| 226 | extensions=missing, optimized=missing, undefined=missing, |
| 227 | finalize=missing, autoescape=missing, loader=missing, |
| 228 | cache_size=missing, auto_reload=missing): |
| 229 | """Create a new overlay environment that shares all the data with the |
| 230 | current environment except of cache and the overriden attributes. |
| 231 | Extensions cannot be removed for a overlayed environment. A overlayed |
| 232 | environment automatically gets all the extensions of the environment it |
| 233 | is linked to plus optional extra extensions. |
| 234 | |
| 235 | Creating overlays should happen after the initial environment was set |
| 236 | up completely. Not all attributes are truly linked, some are just |
| 237 | copied over so modifications on the original environment may not shine |
| 238 | through. |
| 239 | """ |
| 240 | args = dict(locals()) |
| 241 | del args['self'], args['cache_size'], args['extensions'] |
| 242 | |
| 243 | rv = object.__new__(self.__class__) |
| 244 | rv.__dict__.update(self.__dict__) |
| 245 | rv.overlay = True |
| 246 | rv.linked_to = self |
| 247 | |
| 248 | for key, value in args.iteritems(): |
| 249 | if value is not missing: |
| 250 | setattr(rv, key, value) |
| 251 | |
| 252 | if cache_size is not missing: |
| 253 | rv.cache = create_cache(cache_size) |
| 254 | |
| 255 | rv.extensions = [] |
| 256 | for extension in self.extensions: |
| 257 | rv.extensions.append(extension.bind(self)) |
| 258 | if extensions is not missing: |
| 259 | rv.extensions.extend(load_extensions(extensions)) |
| 260 | |
Armin Ronacher | 19cf9c2 | 2008-05-01 12:49:53 +0200 | [diff] [blame] | 261 | return _environment_sanity_check(rv) |
Armin Ronacher | 7259c76 | 2008-04-30 13:03:59 +0200 | [diff] [blame] | 262 | |
| 263 | @property |
| 264 | def lexer(self): |
| 265 | """Return a fresh lexer for the environment.""" |
| 266 | return Lexer(self) |
Armin Ronacher | 203bfcb | 2008-04-24 21:54:44 +0200 | [diff] [blame] | 267 | |
Armin Ronacher | c63243e | 2008-04-14 22:53:58 +0200 | [diff] [blame] | 268 | def subscribe(self, obj, argument): |
| 269 | """Get an item or attribute of an object.""" |
| 270 | try: |
| 271 | return getattr(obj, str(argument)) |
| 272 | except (AttributeError, UnicodeError): |
| 273 | try: |
| 274 | return obj[argument] |
| 275 | except (TypeError, LookupError): |
Armin Ronacher | 9a82205 | 2008-04-17 18:44:07 +0200 | [diff] [blame] | 276 | return self.undefined(obj=obj, name=argument) |
Armin Ronacher | c63243e | 2008-04-14 22:53:58 +0200 | [diff] [blame] | 277 | |
Armin Ronacher | aaf010d | 2008-05-01 13:14:30 +0200 | [diff] [blame] | 278 | def parse(self, source, filename=None): |
Armin Ronacher | d134231 | 2008-04-28 12:20:12 +0200 | [diff] [blame] | 279 | """Parse the sourcecode and return the abstract syntax tree. This |
| 280 | tree of nodes is used by the compiler to convert the template into |
| 281 | executable source- or bytecode. This is useful for debugging or to |
| 282 | extract information from templates. |
Armin Ronacher | 07bc684 | 2008-03-31 14:18:49 +0200 | [diff] [blame] | 283 | """ |
Armin Ronacher | aaf010d | 2008-05-01 13:14:30 +0200 | [diff] [blame] | 284 | try: |
| 285 | return Parser(self, source, filename).parse() |
| 286 | except TemplateSyntaxError, e: |
| 287 | exc_type, exc_value, tb = translate_syntax_error(e) |
| 288 | raise exc_type, exc_value, tb |
Armin Ronacher | 07bc684 | 2008-03-31 14:18:49 +0200 | [diff] [blame] | 289 | |
Armin Ronacher | ba3757b | 2008-04-16 19:43:16 +0200 | [diff] [blame] | 290 | def lex(self, source, name=None): |
Armin Ronacher | d134231 | 2008-04-28 12:20:12 +0200 | [diff] [blame] | 291 | """Lex the given sourcecode and return a generator that yields |
| 292 | tokens as tuples in the form ``(lineno, token_type, value)``. |
Armin Ronacher | 07bc684 | 2008-03-31 14:18:49 +0200 | [diff] [blame] | 293 | """ |
Armin Ronacher | ba3757b | 2008-04-16 19:43:16 +0200 | [diff] [blame] | 294 | return self.lexer.tokeniter(source, name) |
Armin Ronacher | bcb7c53 | 2008-04-11 16:30:34 +0200 | [diff] [blame] | 295 | |
Armin Ronacher | 814f6c2 | 2008-04-17 15:52:23 +0200 | [diff] [blame] | 296 | def compile(self, source, name=None, filename=None, globals=None, |
| 297 | raw=False): |
Armin Ronacher | d134231 | 2008-04-28 12:20:12 +0200 | [diff] [blame] | 298 | """Compile a node or template source code. The `name` parameter is |
| 299 | the load name of the template after it was joined using |
| 300 | :meth:`join_path` if necessary, not the filename on the file system. |
| 301 | the `filename` parameter is the estimated filename of the template on |
| 302 | the file system. If the template came from a database or memory this |
| 303 | can be omitted. The `globals` parameter can be used to provide extra |
| 304 | variables at compile time for the template. In the future the |
| 305 | optimizer will be able to evaluate parts of the template at compile |
| 306 | time based on those variables. |
| 307 | |
| 308 | The return value of this method is a python code object. If the `raw` |
| 309 | parameter is `True` the return value will be a string with python |
| 310 | code equivalent to the bytecode returned otherwise. This method is |
| 311 | mainly used internally. |
Armin Ronacher | 68f7767 | 2008-04-17 11:50:39 +0200 | [diff] [blame] | 312 | """ |
Armin Ronacher | bcb7c53 | 2008-04-11 16:30:34 +0200 | [diff] [blame] | 313 | if isinstance(source, basestring): |
Armin Ronacher | aaf010d | 2008-05-01 13:14:30 +0200 | [diff] [blame] | 314 | source = self.parse(source, filename) |
Armin Ronacher | fed44b5 | 2008-04-13 19:42:53 +0200 | [diff] [blame] | 315 | if self.optimized: |
| 316 | node = optimize(source, self, globals or {}) |
Armin Ronacher | 8e8d071 | 2008-04-16 23:10:49 +0200 | [diff] [blame] | 317 | source = generate(node, self, name, filename) |
Armin Ronacher | bcb7c53 | 2008-04-11 16:30:34 +0200 | [diff] [blame] | 318 | if raw: |
| 319 | return source |
Armin Ronacher | 2e9396b | 2008-04-16 14:21:57 +0200 | [diff] [blame] | 320 | if filename is None: |
Armin Ronacher | 68f7767 | 2008-04-17 11:50:39 +0200 | [diff] [blame] | 321 | filename = '<template>' |
Armin Ronacher | 2e9396b | 2008-04-16 14:21:57 +0200 | [diff] [blame] | 322 | elif isinstance(filename, unicode): |
Armin Ronacher | bcb7c53 | 2008-04-11 16:30:34 +0200 | [diff] [blame] | 323 | filename = filename.encode('utf-8') |
| 324 | return compile(source, filename, 'exec') |
| 325 | |
| 326 | def join_path(self, template, parent): |
| 327 | """Join a template with the parent. By default all the lookups are |
Armin Ronacher | d134231 | 2008-04-28 12:20:12 +0200 | [diff] [blame] | 328 | relative to the loader root so this method returns the `template` |
| 329 | parameter unchanged, but if the paths should be relative to the |
| 330 | parent template, this function can be used to calculate the real |
| 331 | template name. |
| 332 | |
| 333 | Subclasses may override this method and implement template path |
| 334 | joining here. |
| 335 | """ |
Armin Ronacher | bcb7c53 | 2008-04-11 16:30:34 +0200 | [diff] [blame] | 336 | return template |
| 337 | |
Armin Ronacher | fed44b5 | 2008-04-13 19:42:53 +0200 | [diff] [blame] | 338 | def get_template(self, name, parent=None, globals=None): |
Armin Ronacher | d134231 | 2008-04-28 12:20:12 +0200 | [diff] [blame] | 339 | """Load a template from the loader. If a loader is configured this |
| 340 | method ask the loader for the template and returns a :class:`Template`. |
| 341 | If the `parent` parameter is not `None`, :meth:`join_path` is called |
| 342 | to get the real template name before loading. |
| 343 | |
| 344 | The `globals` parameter can be used to provide compile-time globals. |
| 345 | In the future this will allow the optimizer to render parts of the |
| 346 | templates at compile-time. |
| 347 | |
| 348 | If the template does not exist a :exc:`TemplateNotFound` exception is |
| 349 | raised. |
| 350 | """ |
Armin Ronacher | bcb7c53 | 2008-04-11 16:30:34 +0200 | [diff] [blame] | 351 | if self.loader is None: |
| 352 | raise TypeError('no loader for this environment specified') |
| 353 | if parent is not None: |
| 354 | name = self.join_path(name, parent) |
Armin Ronacher | 7259c76 | 2008-04-30 13:03:59 +0200 | [diff] [blame] | 355 | |
| 356 | if self.cache is not None: |
| 357 | template = self.cache.get(name) |
| 358 | if template is not None and (not self.auto_reload or \ |
| 359 | template.is_up_to_date): |
| 360 | return template |
| 361 | |
| 362 | template = self.loader.load(self, name, self.make_globals(globals)) |
| 363 | if self.cache is not None: |
| 364 | self.cache[name] = template |
| 365 | return template |
Armin Ronacher | bcb7c53 | 2008-04-11 16:30:34 +0200 | [diff] [blame] | 366 | |
Armin Ronacher | 203bfcb | 2008-04-24 21:54:44 +0200 | [diff] [blame] | 367 | def from_string(self, source, globals=None, template_class=None): |
Armin Ronacher | d134231 | 2008-04-28 12:20:12 +0200 | [diff] [blame] | 368 | """Load a template from a string. This parses the source given and |
| 369 | returns a :class:`Template` object. |
| 370 | """ |
Armin Ronacher | fed44b5 | 2008-04-13 19:42:53 +0200 | [diff] [blame] | 371 | globals = self.make_globals(globals) |
Armin Ronacher | 7259c76 | 2008-04-30 13:03:59 +0200 | [diff] [blame] | 372 | cls = template_class or self.template_class |
| 373 | return cls.from_code(self, self.compile(source, globals=globals), |
| 374 | globals, None) |
Armin Ronacher | fed44b5 | 2008-04-13 19:42:53 +0200 | [diff] [blame] | 375 | |
| 376 | def make_globals(self, d): |
| 377 | """Return a dict for the globals.""" |
| 378 | if d is None: |
| 379 | return self.globals |
| 380 | return dict(self.globals, **d) |
Armin Ronacher | 46f5f98 | 2008-04-11 16:40:09 +0200 | [diff] [blame] | 381 | |
Armin Ronacher | bcb7c53 | 2008-04-11 16:30:34 +0200 | [diff] [blame] | 382 | |
| 383 | class Template(object): |
Armin Ronacher | 203bfcb | 2008-04-24 21:54:44 +0200 | [diff] [blame] | 384 | """The central template object. This class represents a compiled template |
| 385 | and is used to evaluate it. |
Armin Ronacher | bcb7c53 | 2008-04-11 16:30:34 +0200 | [diff] [blame] | 386 | |
Armin Ronacher | d134231 | 2008-04-28 12:20:12 +0200 | [diff] [blame] | 387 | Normally the template object is generated from an :class:`Environment` but |
| 388 | it also has a constructor that makes it possible to create a template |
Armin Ronacher | 203bfcb | 2008-04-24 21:54:44 +0200 | [diff] [blame] | 389 | instance directly using the constructor. It takes the same arguments as |
| 390 | the environment constructor but it's not possible to specify a loader. |
Armin Ronacher | bcb7c53 | 2008-04-11 16:30:34 +0200 | [diff] [blame] | 391 | |
Armin Ronacher | 203bfcb | 2008-04-24 21:54:44 +0200 | [diff] [blame] | 392 | Every template object has a few methods and members that are guaranteed |
| 393 | to exist. However it's important that a template object should be |
| 394 | considered immutable. Modifications on the object are not supported. |
| 395 | |
| 396 | Template objects created from the constructor rather than an environment |
| 397 | do have an `environment` attribute that points to a temporary environment |
| 398 | that is probably shared with other templates created with the constructor |
| 399 | and compatible settings. |
| 400 | |
| 401 | >>> template = Template('Hello {{ name }}!') |
| 402 | >>> template.render(name='John Doe') |
| 403 | u'Hello John Doe!' |
| 404 | |
| 405 | >>> stream = template.stream(name='John Doe') |
| 406 | >>> stream.next() |
| 407 | u'Hello John Doe!' |
| 408 | >>> stream.next() |
| 409 | Traceback (most recent call last): |
| 410 | ... |
| 411 | StopIteration |
| 412 | """ |
| 413 | |
| 414 | def __new__(cls, source, |
| 415 | block_start_string='{%', |
| 416 | block_end_string='%}', |
| 417 | variable_start_string='{{', |
| 418 | variable_end_string='}}', |
| 419 | comment_start_string='{#', |
| 420 | comment_end_string='#}', |
| 421 | line_statement_prefix=None, |
| 422 | trim_blocks=False, |
Armin Ronacher | b5124e6 | 2008-04-25 00:36:14 +0200 | [diff] [blame] | 423 | extensions=(), |
Armin Ronacher | 203bfcb | 2008-04-24 21:54:44 +0200 | [diff] [blame] | 424 | optimized=True, |
| 425 | undefined=Undefined, |
Armin Ronacher | d134231 | 2008-04-28 12:20:12 +0200 | [diff] [blame] | 426 | finalize=None, |
| 427 | autoescape=False): |
Armin Ronacher | b5124e6 | 2008-04-25 00:36:14 +0200 | [diff] [blame] | 428 | env = get_spontaneous_environment( |
Armin Ronacher | 203bfcb | 2008-04-24 21:54:44 +0200 | [diff] [blame] | 429 | block_start_string, block_end_string, variable_start_string, |
| 430 | variable_end_string, comment_start_string, comment_end_string, |
Armin Ronacher | b5124e6 | 2008-04-25 00:36:14 +0200 | [diff] [blame] | 431 | line_statement_prefix, trim_blocks, tuple(extensions), optimized, |
Armin Ronacher | 7259c76 | 2008-04-30 13:03:59 +0200 | [diff] [blame] | 432 | undefined, finalize, autoescape, None, 0, False) |
Armin Ronacher | 203bfcb | 2008-04-24 21:54:44 +0200 | [diff] [blame] | 433 | return env.from_string(source, template_class=cls) |
Armin Ronacher | ba3757b | 2008-04-16 19:43:16 +0200 | [diff] [blame] | 434 | |
Armin Ronacher | 7259c76 | 2008-04-30 13:03:59 +0200 | [diff] [blame] | 435 | @classmethod |
| 436 | def from_code(cls, environment, code, globals, uptodate=None): |
| 437 | """Creates a template object from compiled code and the globals. This |
| 438 | is used by the loaders and environment to create a template object. |
| 439 | """ |
| 440 | t = object.__new__(cls) |
| 441 | namespace = { |
| 442 | 'environment': environment, |
| 443 | '__jinja_template__': t |
| 444 | } |
| 445 | exec code in namespace |
| 446 | t.environment = environment |
| 447 | t.name = namespace['name'] |
| 448 | t.filename = code.co_filename |
| 449 | t.root_render_func = namespace['root'] |
| 450 | t.blocks = namespace['blocks'] |
| 451 | t.globals = globals |
| 452 | |
| 453 | # debug and loader helpers |
| 454 | t._debug_info = namespace['debug_info'] |
| 455 | t._uptodate = uptodate |
| 456 | |
| 457 | return t |
| 458 | |
Armin Ronacher | bcb7c53 | 2008-04-11 16:30:34 +0200 | [diff] [blame] | 459 | def render(self, *args, **kwargs): |
Armin Ronacher | d134231 | 2008-04-28 12:20:12 +0200 | [diff] [blame] | 460 | """This method accepts the same arguments as the `dict` constructor: |
| 461 | A dict, a dict subclass or some keyword arguments. If no arguments |
| 462 | are given the context will be empty. These two calls do the same:: |
| 463 | |
| 464 | template.render(knights='that say nih') |
| 465 | template.render({'knights': 'that say nih'}) |
| 466 | |
| 467 | This will return the rendered template as unicode string. |
| 468 | """ |
Armin Ronacher | f41d139 | 2008-04-18 16:41:52 +0200 | [diff] [blame] | 469 | try: |
Armin Ronacher | 19cf9c2 | 2008-05-01 12:49:53 +0200 | [diff] [blame] | 470 | return concat(self._generate(*args, **kwargs)) |
Armin Ronacher | f41d139 | 2008-04-18 16:41:52 +0200 | [diff] [blame] | 471 | except: |
Armin Ronacher | 19cf9c2 | 2008-05-01 12:49:53 +0200 | [diff] [blame] | 472 | exc_type, exc_value, tb = translate_exception(sys.exc_info()) |
| 473 | raise exc_type, exc_value, tb |
Armin Ronacher | bcb7c53 | 2008-04-11 16:30:34 +0200 | [diff] [blame] | 474 | |
| 475 | def stream(self, *args, **kwargs): |
Armin Ronacher | d134231 | 2008-04-28 12:20:12 +0200 | [diff] [blame] | 476 | """Works exactly like :meth:`generate` but returns a |
| 477 | :class:`TemplateStream`. |
| 478 | """ |
Armin Ronacher | 19cf9c2 | 2008-05-01 12:49:53 +0200 | [diff] [blame] | 479 | return TemplateStream(self.generate(*args, **kwargs)) |
Armin Ronacher | fed44b5 | 2008-04-13 19:42:53 +0200 | [diff] [blame] | 480 | |
| 481 | def generate(self, *args, **kwargs): |
Armin Ronacher | d134231 | 2008-04-28 12:20:12 +0200 | [diff] [blame] | 482 | """For very large templates it can be useful to not render the whole |
| 483 | template at once but evaluate each statement after another and yield |
| 484 | piece for piece. This method basically does exactly that and returns |
| 485 | a generator that yields one item after another as unicode strings. |
| 486 | |
| 487 | It accepts the same arguments as :meth:`render`. |
| 488 | """ |
Armin Ronacher | 19cf9c2 | 2008-05-01 12:49:53 +0200 | [diff] [blame] | 489 | try: |
| 490 | for item in self._generate(*args, **kwargs): |
| 491 | yield item |
| 492 | except: |
| 493 | exc_type, exc_value, tb = translate_exception(sys.exc_info()) |
| 494 | raise exc_type, exc_value, tb |
| 495 | |
| 496 | def _generate(self, *args, **kwargs): |
Armin Ronacher | fed44b5 | 2008-04-13 19:42:53 +0200 | [diff] [blame] | 497 | # assemble the context |
Armin Ronacher | 2e9396b | 2008-04-16 14:21:57 +0200 | [diff] [blame] | 498 | context = dict(*args, **kwargs) |
Armin Ronacher | fed44b5 | 2008-04-13 19:42:53 +0200 | [diff] [blame] | 499 | |
| 500 | # if the environment is using the optimizer locals may never |
| 501 | # override globals as optimizations might have happened |
| 502 | # depending on values of certain globals. This assertion goes |
| 503 | # away if the python interpreter is started with -O |
| 504 | if __debug__ and self.environment.optimized: |
Armin Ronacher | 2e9396b | 2008-04-16 14:21:57 +0200 | [diff] [blame] | 505 | overrides = set(context) & set(self.globals) |
Armin Ronacher | fed44b5 | 2008-04-13 19:42:53 +0200 | [diff] [blame] | 506 | if overrides: |
| 507 | plural = len(overrides) != 1 and 's' or '' |
| 508 | raise AssertionError('the per template variable%s %s ' |
| 509 | 'override%s global variable%s. ' |
| 510 | 'With an enabled optimizer this ' |
| 511 | 'will lead to unexpected results.' % |
| 512 | (plural, ', '.join(overrides), plural or ' a', plural)) |
Armin Ronacher | ba3757b | 2008-04-16 19:43:16 +0200 | [diff] [blame] | 513 | |
Armin Ronacher | 19cf9c2 | 2008-05-01 12:49:53 +0200 | [diff] [blame] | 514 | return self.root_render_func(self.new_context(context)) |
Armin Ronacher | 203bfcb | 2008-04-24 21:54:44 +0200 | [diff] [blame] | 515 | |
Armin Ronacher | c9705c2 | 2008-04-27 21:28:03 +0200 | [diff] [blame] | 516 | def new_context(self, vars=None, shared=False): |
| 517 | """Create a new template context for this template. The vars |
| 518 | provided will be passed to the template. Per default the globals |
| 519 | are added to the context, if shared is set to `True` the data |
| 520 | provided is used as parent namespace. This is used to share the |
| 521 | same globals in multiple contexts without consuming more memory. |
| 522 | (This works because the context does not modify the parent dict) |
| 523 | """ |
| 524 | if vars is None: |
| 525 | vars = {} |
| 526 | if shared: |
| 527 | parent = vars |
| 528 | else: |
| 529 | parent = dict(self.globals, **vars) |
Armin Ronacher | 19cf9c2 | 2008-05-01 12:49:53 +0200 | [diff] [blame] | 530 | return Context(self.environment, parent, self.name, self.blocks) |
Armin Ronacher | ba3757b | 2008-04-16 19:43:16 +0200 | [diff] [blame] | 531 | |
Armin Ronacher | ea847c5 | 2008-05-02 20:04:32 +0200 | [diff] [blame^] | 532 | def make_module(self, vars=None, shared=False): |
| 533 | """Like the `module` property but always reevaluates the template |
| 534 | and it's possible to provide a context. |
| 535 | """ |
| 536 | return TemplateModule(self, self.new_context(vars, shared)) |
| 537 | |
Armin Ronacher | d84ec46 | 2008-04-29 13:43:16 +0200 | [diff] [blame] | 538 | @property |
| 539 | def module(self): |
| 540 | """The template as module. This is used for imports in the |
| 541 | template runtime but is also useful if one wants to access |
| 542 | exported template variables from the Python layer: |
Armin Ronacher | d134231 | 2008-04-28 12:20:12 +0200 | [diff] [blame] | 543 | |
Armin Ronacher | d84ec46 | 2008-04-29 13:43:16 +0200 | [diff] [blame] | 544 | >>> t = Template('{% macro foo() %}42{% endmacro %}23') |
| 545 | >>> unicode(t.module) |
| 546 | u'23' |
| 547 | >>> t.module.foo() |
Armin Ronacher | d134231 | 2008-04-28 12:20:12 +0200 | [diff] [blame] | 548 | u'42' |
Armin Ronacher | 6ce170c | 2008-04-25 12:32:36 +0200 | [diff] [blame] | 549 | """ |
Armin Ronacher | d84ec46 | 2008-04-29 13:43:16 +0200 | [diff] [blame] | 550 | if hasattr(self, '_module'): |
| 551 | return self._module |
Armin Ronacher | ea847c5 | 2008-05-02 20:04:32 +0200 | [diff] [blame^] | 552 | self._module = rv = self.make_module() |
Armin Ronacher | d84ec46 | 2008-04-29 13:43:16 +0200 | [diff] [blame] | 553 | return rv |
Armin Ronacher | 963f97d | 2008-04-25 11:44:59 +0200 | [diff] [blame] | 554 | |
Armin Ronacher | ba3757b | 2008-04-16 19:43:16 +0200 | [diff] [blame] | 555 | def get_corresponding_lineno(self, lineno): |
| 556 | """Return the source line number of a line number in the |
| 557 | generated bytecode as they are not in sync. |
| 558 | """ |
Armin Ronacher | 203bfcb | 2008-04-24 21:54:44 +0200 | [diff] [blame] | 559 | for template_line, code_line in reversed(self.debug_info): |
Armin Ronacher | ba3757b | 2008-04-16 19:43:16 +0200 | [diff] [blame] | 560 | if code_line <= lineno: |
| 561 | return template_line |
| 562 | return 1 |
Armin Ronacher | c63243e | 2008-04-14 22:53:58 +0200 | [diff] [blame] | 563 | |
Armin Ronacher | 9a82205 | 2008-04-17 18:44:07 +0200 | [diff] [blame] | 564 | @property |
Armin Ronacher | 814f6c2 | 2008-04-17 15:52:23 +0200 | [diff] [blame] | 565 | def is_up_to_date(self): |
Armin Ronacher | 203bfcb | 2008-04-24 21:54:44 +0200 | [diff] [blame] | 566 | """If this variable is `False` there is a newer version available.""" |
Armin Ronacher | 814f6c2 | 2008-04-17 15:52:23 +0200 | [diff] [blame] | 567 | if self._uptodate is None: |
| 568 | return True |
| 569 | return self._uptodate() |
| 570 | |
Armin Ronacher | 203bfcb | 2008-04-24 21:54:44 +0200 | [diff] [blame] | 571 | @property |
| 572 | def debug_info(self): |
| 573 | """The debug info mapping.""" |
| 574 | return [tuple(map(int, x.split('='))) for x in |
| 575 | self._debug_info.split('&')] |
| 576 | |
Armin Ronacher | c63243e | 2008-04-14 22:53:58 +0200 | [diff] [blame] | 577 | def __repr__(self): |
Armin Ronacher | 5304229 | 2008-04-26 18:30:19 +0200 | [diff] [blame] | 578 | if self.name is None: |
| 579 | name = 'memory:%x' % id(self) |
| 580 | else: |
| 581 | name = repr(self.name) |
| 582 | return '<%s %s>' % (self.__class__.__name__, name) |
Armin Ronacher | c63243e | 2008-04-14 22:53:58 +0200 | [diff] [blame] | 583 | |
| 584 | |
Armin Ronacher | d84ec46 | 2008-04-29 13:43:16 +0200 | [diff] [blame] | 585 | class TemplateModule(object): |
| 586 | """Represents an imported template. All the exported names of the |
Armin Ronacher | 5304229 | 2008-04-26 18:30:19 +0200 | [diff] [blame] | 587 | template are available as attributes on this object. Additionally |
| 588 | converting it into an unicode- or bytestrings renders the contents. |
| 589 | """ |
Armin Ronacher | 963f97d | 2008-04-25 11:44:59 +0200 | [diff] [blame] | 590 | |
| 591 | def __init__(self, template, context): |
Armin Ronacher | ea847c5 | 2008-05-02 20:04:32 +0200 | [diff] [blame^] | 592 | # don't alter this attribute unless you change it in the |
| 593 | # compiler too. The Include without context passing directly |
| 594 | # uses the mangled name. The reason why we use a mangled one |
| 595 | # is to avoid name clashes with macros with those names. |
Armin Ronacher | 5304229 | 2008-04-26 18:30:19 +0200 | [diff] [blame] | 596 | self.__body_stream = tuple(template.root_render_func(context)) |
Armin Ronacher | 6ce170c | 2008-04-25 12:32:36 +0200 | [diff] [blame] | 597 | self.__dict__.update(context.get_exported()) |
Armin Ronacher | 2feed1d | 2008-04-26 16:26:52 +0200 | [diff] [blame] | 598 | self.__name__ = template.name |
Armin Ronacher | 963f97d | 2008-04-25 11:44:59 +0200 | [diff] [blame] | 599 | |
Armin Ronacher | 5304229 | 2008-04-26 18:30:19 +0200 | [diff] [blame] | 600 | __html__ = lambda x: Markup(concat(x.__body_stream)) |
| 601 | __unicode__ = lambda x: unicode(concat(x.__body_stream)) |
Armin Ronacher | 6ce170c | 2008-04-25 12:32:36 +0200 | [diff] [blame] | 602 | |
| 603 | def __str__(self): |
Armin Ronacher | 2feed1d | 2008-04-26 16:26:52 +0200 | [diff] [blame] | 604 | return unicode(self).encode('utf-8') |
Armin Ronacher | 963f97d | 2008-04-25 11:44:59 +0200 | [diff] [blame] | 605 | |
| 606 | def __repr__(self): |
Armin Ronacher | 5304229 | 2008-04-26 18:30:19 +0200 | [diff] [blame] | 607 | if self.__name__ is None: |
| 608 | name = 'memory:%x' % id(self) |
| 609 | else: |
| 610 | name = repr(self.name) |
| 611 | return '<%s %s>' % (self.__class__.__name__, name) |
Armin Ronacher | 963f97d | 2008-04-25 11:44:59 +0200 | [diff] [blame] | 612 | |
| 613 | |
Armin Ronacher | c63243e | 2008-04-14 22:53:58 +0200 | [diff] [blame] | 614 | class TemplateStream(object): |
Armin Ronacher | d134231 | 2008-04-28 12:20:12 +0200 | [diff] [blame] | 615 | """A template stream works pretty much like an ordinary python generator |
| 616 | but it can buffer multiple items to reduce the number of total iterations. |
| 617 | Per default the output is unbuffered which means that for every unbuffered |
| 618 | instruction in the template one unicode string is yielded. |
| 619 | |
| 620 | If buffering is enabled with a buffer size of 5, five items are combined |
| 621 | into a new unicode string. This is mainly useful if you are streaming |
| 622 | big templates to a client via WSGI which flushes after each iteration. |
Armin Ronacher | 203bfcb | 2008-04-24 21:54:44 +0200 | [diff] [blame] | 623 | """ |
Armin Ronacher | c63243e | 2008-04-14 22:53:58 +0200 | [diff] [blame] | 624 | |
| 625 | def __init__(self, gen): |
| 626 | self._gen = gen |
| 627 | self._next = gen.next |
| 628 | self.buffered = False |
| 629 | |
| 630 | def disable_buffering(self): |
| 631 | """Disable the output buffering.""" |
| 632 | self._next = self._gen.next |
| 633 | self.buffered = False |
| 634 | |
| 635 | def enable_buffering(self, size=5): |
Armin Ronacher | d134231 | 2008-04-28 12:20:12 +0200 | [diff] [blame] | 636 | """Enable buffering. Buffer `size` items before yielding them.""" |
Armin Ronacher | c63243e | 2008-04-14 22:53:58 +0200 | [diff] [blame] | 637 | if size <= 1: |
| 638 | raise ValueError('buffer size too small') |
Armin Ronacher | c63243e | 2008-04-14 22:53:58 +0200 | [diff] [blame] | 639 | |
Armin Ronacher | 203bfcb | 2008-04-24 21:54:44 +0200 | [diff] [blame] | 640 | def generator(): |
Armin Ronacher | c63243e | 2008-04-14 22:53:58 +0200 | [diff] [blame] | 641 | buf = [] |
| 642 | c_size = 0 |
| 643 | push = buf.append |
| 644 | next = self._gen.next |
| 645 | |
Armin Ronacher | 203bfcb | 2008-04-24 21:54:44 +0200 | [diff] [blame] | 646 | while 1: |
| 647 | try: |
Armin Ronacher | b5124e6 | 2008-04-25 00:36:14 +0200 | [diff] [blame] | 648 | while c_size < size: |
Armin Ronacher | 203bfcb | 2008-04-24 21:54:44 +0200 | [diff] [blame] | 649 | push(next()) |
Armin Ronacher | c63243e | 2008-04-14 22:53:58 +0200 | [diff] [blame] | 650 | c_size += 1 |
Armin Ronacher | 203bfcb | 2008-04-24 21:54:44 +0200 | [diff] [blame] | 651 | except StopIteration: |
| 652 | if not c_size: |
Armin Ronacher | d84ec46 | 2008-04-29 13:43:16 +0200 | [diff] [blame] | 653 | return |
Armin Ronacher | de6bf71 | 2008-04-26 01:44:14 +0200 | [diff] [blame] | 654 | yield concat(buf) |
Armin Ronacher | 203bfcb | 2008-04-24 21:54:44 +0200 | [diff] [blame] | 655 | del buf[:] |
| 656 | c_size = 0 |
Armin Ronacher | c63243e | 2008-04-14 22:53:58 +0200 | [diff] [blame] | 657 | |
Armin Ronacher | 203bfcb | 2008-04-24 21:54:44 +0200 | [diff] [blame] | 658 | self.buffered = True |
| 659 | self._next = generator().next |
Armin Ronacher | c63243e | 2008-04-14 22:53:58 +0200 | [diff] [blame] | 660 | |
| 661 | def __iter__(self): |
| 662 | return self |
| 663 | |
| 664 | def next(self): |
| 665 | return self._next() |
Armin Ronacher | 203bfcb | 2008-04-24 21:54:44 +0200 | [diff] [blame] | 666 | |
| 667 | |
| 668 | # hook in default template class. if anyone reads this comment: ignore that |
| 669 | # it's possible to use custom templates ;-) |
| 670 | Environment.template_class = Template |