OLD | NEW |
(Empty) | |
| 1 # -*- coding: utf-8 -*- |
| 2 """ |
| 3 jinja2.runtime |
| 4 ~~~~~~~~~~~~~~ |
| 5 |
| 6 Runtime helpers. |
| 7 |
| 8 :copyright: (c) 2010 by the Jinja Team. |
| 9 :license: BSD. |
| 10 """ |
| 11 from itertools import chain, imap |
| 12 from jinja2.nodes import EvalContext, _context_function_types |
| 13 from jinja2.utils import Markup, partial, soft_unicode, escape, missing, \ |
| 14 concat, internalcode, next, object_type_repr |
| 15 from jinja2.exceptions import UndefinedError, TemplateRuntimeError, \ |
| 16 TemplateNotFound |
| 17 |
| 18 |
| 19 # these variables are exported to the template runtime |
| 20 __all__ = ['LoopContext', 'TemplateReference', 'Macro', 'Markup', |
| 21 'TemplateRuntimeError', 'missing', 'concat', 'escape', |
| 22 'markup_join', 'unicode_join', 'to_string', 'identity', |
| 23 'TemplateNotFound'] |
| 24 |
| 25 #: the name of the function that is used to convert something into |
| 26 #: a string. 2to3 will adopt that automatically and the generated |
| 27 #: code can take advantage of it. |
| 28 to_string = unicode |
| 29 |
| 30 #: the identity function. Useful for certain things in the environment |
| 31 identity = lambda x: x |
| 32 |
| 33 |
| 34 def markup_join(seq): |
| 35 """Concatenation that escapes if necessary and converts to unicode.""" |
| 36 buf = [] |
| 37 iterator = imap(soft_unicode, seq) |
| 38 for arg in iterator: |
| 39 buf.append(arg) |
| 40 if hasattr(arg, '__html__'): |
| 41 return Markup(u'').join(chain(buf, iterator)) |
| 42 return concat(buf) |
| 43 |
| 44 |
| 45 def unicode_join(seq): |
| 46 """Simple args to unicode conversion and concatenation.""" |
| 47 return concat(imap(unicode, seq)) |
| 48 |
| 49 |
| 50 def new_context(environment, template_name, blocks, vars=None, |
| 51 shared=None, globals=None, locals=None): |
| 52 """Internal helper to for context creation.""" |
| 53 if vars is None: |
| 54 vars = {} |
| 55 if shared: |
| 56 parent = vars |
| 57 else: |
| 58 parent = dict(globals or (), **vars) |
| 59 if locals: |
| 60 # if the parent is shared a copy should be created because |
| 61 # we don't want to modify the dict passed |
| 62 if shared: |
| 63 parent = dict(parent) |
| 64 for key, value in locals.iteritems(): |
| 65 if key[:2] == 'l_' and value is not missing: |
| 66 parent[key[2:]] = value |
| 67 return Context(environment, parent, template_name, blocks) |
| 68 |
| 69 |
| 70 class TemplateReference(object): |
| 71 """The `self` in templates.""" |
| 72 |
| 73 def __init__(self, context): |
| 74 self.__context = context |
| 75 |
| 76 def __getitem__(self, name): |
| 77 blocks = self.__context.blocks[name] |
| 78 return BlockReference(name, self.__context, blocks, 0) |
| 79 |
| 80 def __repr__(self): |
| 81 return '<%s %r>' % ( |
| 82 self.__class__.__name__, |
| 83 self.__context.name |
| 84 ) |
| 85 |
| 86 |
| 87 class Context(object): |
| 88 """The template context holds the variables of a template. It stores the |
| 89 values passed to the template and also the names the template exports. |
| 90 Creating instances is neither supported nor useful as it's created |
| 91 automatically at various stages of the template evaluation and should not |
| 92 be created by hand. |
| 93 |
| 94 The context is immutable. Modifications on :attr:`parent` **must not** |
| 95 happen and modifications on :attr:`vars` are allowed from generated |
| 96 template code only. Template filters and global functions marked as |
| 97 :func:`contextfunction`\s get the active context passed as first argument |
| 98 and are allowed to access the context read-only. |
| 99 |
| 100 The template context supports read only dict operations (`get`, |
| 101 `keys`, `values`, `items`, `iterkeys`, `itervalues`, `iteritems`, |
| 102 `__getitem__`, `__contains__`). Additionally there is a :meth:`resolve` |
| 103 method that doesn't fail with a `KeyError` but returns an |
| 104 :class:`Undefined` object for missing variables. |
| 105 """ |
| 106 __slots__ = ('parent', 'vars', 'environment', 'eval_ctx', 'exported_vars', |
| 107 'name', 'blocks', '__weakref__') |
| 108 |
| 109 def __init__(self, environment, parent, name, blocks): |
| 110 self.parent = parent |
| 111 self.vars = {} |
| 112 self.environment = environment |
| 113 self.eval_ctx = EvalContext(self.environment, name) |
| 114 self.exported_vars = set() |
| 115 self.name = name |
| 116 |
| 117 # create the initial mapping of blocks. Whenever template inheritance |
| 118 # takes place the runtime will update this mapping with the new blocks |
| 119 # from the template. |
| 120 self.blocks = dict((k, [v]) for k, v in blocks.iteritems()) |
| 121 |
| 122 def super(self, name, current): |
| 123 """Render a parent block.""" |
| 124 try: |
| 125 blocks = self.blocks[name] |
| 126 index = blocks.index(current) + 1 |
| 127 blocks[index] |
| 128 except LookupError: |
| 129 return self.environment.undefined('there is no parent block ' |
| 130 'called %r.' % name, |
| 131 name='super') |
| 132 return BlockReference(name, self, blocks, index) |
| 133 |
| 134 def get(self, key, default=None): |
| 135 """Returns an item from the template context, if it doesn't exist |
| 136 `default` is returned. |
| 137 """ |
| 138 try: |
| 139 return self[key] |
| 140 except KeyError: |
| 141 return default |
| 142 |
| 143 def resolve(self, key): |
| 144 """Looks up a variable like `__getitem__` or `get` but returns an |
| 145 :class:`Undefined` object with the name of the name looked up. |
| 146 """ |
| 147 if key in self.vars: |
| 148 return self.vars[key] |
| 149 if key in self.parent: |
| 150 return self.parent[key] |
| 151 return self.environment.undefined(name=key) |
| 152 |
| 153 def get_exported(self): |
| 154 """Get a new dict with the exported variables.""" |
| 155 return dict((k, self.vars[k]) for k in self.exported_vars) |
| 156 |
| 157 def get_all(self): |
| 158 """Return a copy of the complete context as dict including the |
| 159 exported variables. |
| 160 """ |
| 161 return dict(self.parent, **self.vars) |
| 162 |
| 163 @internalcode |
| 164 def call(__self, __obj, *args, **kwargs): |
| 165 """Call the callable with the arguments and keyword arguments |
| 166 provided but inject the active context or environment as first |
| 167 argument if the callable is a :func:`contextfunction` or |
| 168 :func:`environmentfunction`. |
| 169 """ |
| 170 if __debug__: |
| 171 __traceback_hide__ = True |
| 172 if isinstance(__obj, _context_function_types): |
| 173 if getattr(__obj, 'contextfunction', 0): |
| 174 args = (__self,) + args |
| 175 elif getattr(__obj, 'evalcontextfunction', 0): |
| 176 args = (__self.eval_ctx,) + args |
| 177 elif getattr(__obj, 'environmentfunction', 0): |
| 178 args = (__self.environment,) + args |
| 179 try: |
| 180 return __obj(*args, **kwargs) |
| 181 except StopIteration: |
| 182 return __self.environment.undefined('value was undefined because ' |
| 183 'a callable raised a ' |
| 184 'StopIteration exception') |
| 185 |
| 186 def derived(self, locals=None): |
| 187 """Internal helper function to create a derived context.""" |
| 188 context = new_context(self.environment, self.name, {}, |
| 189 self.parent, True, None, locals) |
| 190 context.vars.update(self.vars) |
| 191 context.eval_ctx = self.eval_ctx |
| 192 context.blocks.update((k, list(v)) for k, v in self.blocks.iteritems()) |
| 193 return context |
| 194 |
| 195 def _all(meth): |
| 196 proxy = lambda self: getattr(self.get_all(), meth)() |
| 197 proxy.__doc__ = getattr(dict, meth).__doc__ |
| 198 proxy.__name__ = meth |
| 199 return proxy |
| 200 |
| 201 keys = _all('keys') |
| 202 values = _all('values') |
| 203 items = _all('items') |
| 204 |
| 205 # not available on python 3 |
| 206 if hasattr(dict, 'iterkeys'): |
| 207 iterkeys = _all('iterkeys') |
| 208 itervalues = _all('itervalues') |
| 209 iteritems = _all('iteritems') |
| 210 del _all |
| 211 |
| 212 def __contains__(self, name): |
| 213 return name in self.vars or name in self.parent |
| 214 |
| 215 def __getitem__(self, key): |
| 216 """Lookup a variable or raise `KeyError` if the variable is |
| 217 undefined. |
| 218 """ |
| 219 item = self.resolve(key) |
| 220 if isinstance(item, Undefined): |
| 221 raise KeyError(key) |
| 222 return item |
| 223 |
| 224 def __repr__(self): |
| 225 return '<%s %s of %r>' % ( |
| 226 self.__class__.__name__, |
| 227 repr(self.get_all()), |
| 228 self.name |
| 229 ) |
| 230 |
| 231 |
| 232 # register the context as mapping if possible |
| 233 try: |
| 234 from collections import Mapping |
| 235 Mapping.register(Context) |
| 236 except ImportError: |
| 237 pass |
| 238 |
| 239 |
| 240 class BlockReference(object): |
| 241 """One block on a template reference.""" |
| 242 |
| 243 def __init__(self, name, context, stack, depth): |
| 244 self.name = name |
| 245 self._context = context |
| 246 self._stack = stack |
| 247 self._depth = depth |
| 248 |
| 249 @property |
| 250 def super(self): |
| 251 """Super the block.""" |
| 252 if self._depth + 1 >= len(self._stack): |
| 253 return self._context.environment. \ |
| 254 undefined('there is no parent block called %r.' % |
| 255 self.name, name='super') |
| 256 return BlockReference(self.name, self._context, self._stack, |
| 257 self._depth + 1) |
| 258 |
| 259 @internalcode |
| 260 def __call__(self): |
| 261 rv = concat(self._stack[self._depth](self._context)) |
| 262 if self._context.eval_ctx.autoescape: |
| 263 rv = Markup(rv) |
| 264 return rv |
| 265 |
| 266 |
| 267 class LoopContext(object): |
| 268 """A loop context for dynamic iteration.""" |
| 269 |
| 270 def __init__(self, iterable, recurse=None): |
| 271 self._iterator = iter(iterable) |
| 272 self._recurse = recurse |
| 273 self.index0 = -1 |
| 274 |
| 275 # try to get the length of the iterable early. This must be done |
| 276 # here because there are some broken iterators around where there |
| 277 # __len__ is the number of iterations left (i'm looking at your |
| 278 # listreverseiterator!). |
| 279 try: |
| 280 self._length = len(iterable) |
| 281 except (TypeError, AttributeError): |
| 282 self._length = None |
| 283 |
| 284 def cycle(self, *args): |
| 285 """Cycles among the arguments with the current loop index.""" |
| 286 if not args: |
| 287 raise TypeError('no items for cycling given') |
| 288 return args[self.index0 % len(args)] |
| 289 |
| 290 first = property(lambda x: x.index0 == 0) |
| 291 last = property(lambda x: x.index0 + 1 == x.length) |
| 292 index = property(lambda x: x.index0 + 1) |
| 293 revindex = property(lambda x: x.length - x.index0) |
| 294 revindex0 = property(lambda x: x.length - x.index) |
| 295 |
| 296 def __len__(self): |
| 297 return self.length |
| 298 |
| 299 def __iter__(self): |
| 300 return LoopContextIterator(self) |
| 301 |
| 302 @internalcode |
| 303 def loop(self, iterable): |
| 304 if self._recurse is None: |
| 305 raise TypeError('Tried to call non recursive loop. Maybe you ' |
| 306 "forgot the 'recursive' modifier.") |
| 307 return self._recurse(iterable, self._recurse) |
| 308 |
| 309 # a nifty trick to enhance the error message if someone tried to call |
| 310 # the the loop without or with too many arguments. |
| 311 __call__ = loop |
| 312 del loop |
| 313 |
| 314 @property |
| 315 def length(self): |
| 316 if self._length is None: |
| 317 # if was not possible to get the length of the iterator when |
| 318 # the loop context was created (ie: iterating over a generator) |
| 319 # we have to convert the iterable into a sequence and use the |
| 320 # length of that. |
| 321 iterable = tuple(self._iterator) |
| 322 self._iterator = iter(iterable) |
| 323 self._length = len(iterable) + self.index0 + 1 |
| 324 return self._length |
| 325 |
| 326 def __repr__(self): |
| 327 return '<%s %r/%r>' % ( |
| 328 self.__class__.__name__, |
| 329 self.index, |
| 330 self.length |
| 331 ) |
| 332 |
| 333 |
| 334 class LoopContextIterator(object): |
| 335 """The iterator for a loop context.""" |
| 336 __slots__ = ('context',) |
| 337 |
| 338 def __init__(self, context): |
| 339 self.context = context |
| 340 |
| 341 def __iter__(self): |
| 342 return self |
| 343 |
| 344 def next(self): |
| 345 ctx = self.context |
| 346 ctx.index0 += 1 |
| 347 return next(ctx._iterator), ctx |
| 348 |
| 349 |
| 350 class Macro(object): |
| 351 """Wraps a macro function.""" |
| 352 |
| 353 def __init__(self, environment, func, name, arguments, defaults, |
| 354 catch_kwargs, catch_varargs, caller): |
| 355 self._environment = environment |
| 356 self._func = func |
| 357 self._argument_count = len(arguments) |
| 358 self.name = name |
| 359 self.arguments = arguments |
| 360 self.defaults = defaults |
| 361 self.catch_kwargs = catch_kwargs |
| 362 self.catch_varargs = catch_varargs |
| 363 self.caller = caller |
| 364 |
| 365 @internalcode |
| 366 def __call__(self, *args, **kwargs): |
| 367 # try to consume the positional arguments |
| 368 arguments = list(args[:self._argument_count]) |
| 369 off = len(arguments) |
| 370 |
| 371 # if the number of arguments consumed is not the number of |
| 372 # arguments expected we start filling in keyword arguments |
| 373 # and defaults. |
| 374 if off != self._argument_count: |
| 375 for idx, name in enumerate(self.arguments[len(arguments):]): |
| 376 try: |
| 377 value = kwargs.pop(name) |
| 378 except KeyError: |
| 379 try: |
| 380 value = self.defaults[idx - self._argument_count + off] |
| 381 except IndexError: |
| 382 value = self._environment.undefined( |
| 383 'parameter %r was not provided' % name, name=name) |
| 384 arguments.append(value) |
| 385 |
| 386 # it's important that the order of these arguments does not change |
| 387 # if not also changed in the compiler's `function_scoping` method. |
| 388 # the order is caller, keyword arguments, positional arguments! |
| 389 if self.caller: |
| 390 caller = kwargs.pop('caller', None) |
| 391 if caller is None: |
| 392 caller = self._environment.undefined('No caller defined', |
| 393 name='caller') |
| 394 arguments.append(caller) |
| 395 if self.catch_kwargs: |
| 396 arguments.append(kwargs) |
| 397 elif kwargs: |
| 398 raise TypeError('macro %r takes no keyword argument %r' % |
| 399 (self.name, next(iter(kwargs)))) |
| 400 if self.catch_varargs: |
| 401 arguments.append(args[self._argument_count:]) |
| 402 elif len(args) > self._argument_count: |
| 403 raise TypeError('macro %r takes not more than %d argument(s)' % |
| 404 (self.name, len(self.arguments))) |
| 405 return self._func(*arguments) |
| 406 |
| 407 def __repr__(self): |
| 408 return '<%s %s>' % ( |
| 409 self.__class__.__name__, |
| 410 self.name is None and 'anonymous' or repr(self.name) |
| 411 ) |
| 412 |
| 413 |
| 414 class Undefined(object): |
| 415 """The default undefined type. This undefined type can be printed and |
| 416 iterated over, but every other access will raise an :exc:`UndefinedError`: |
| 417 |
| 418 >>> foo = Undefined(name='foo') |
| 419 >>> str(foo) |
| 420 '' |
| 421 >>> not foo |
| 422 True |
| 423 >>> foo + 42 |
| 424 Traceback (most recent call last): |
| 425 ... |
| 426 UndefinedError: 'foo' is undefined |
| 427 """ |
| 428 __slots__ = ('_undefined_hint', '_undefined_obj', '_undefined_name', |
| 429 '_undefined_exception') |
| 430 |
| 431 def __init__(self, hint=None, obj=missing, name=None, exc=UndefinedError): |
| 432 self._undefined_hint = hint |
| 433 self._undefined_obj = obj |
| 434 self._undefined_name = name |
| 435 self._undefined_exception = exc |
| 436 |
| 437 @internalcode |
| 438 def _fail_with_undefined_error(self, *args, **kwargs): |
| 439 """Regular callback function for undefined objects that raises an |
| 440 `UndefinedError` on call. |
| 441 """ |
| 442 if self._undefined_hint is None: |
| 443 if self._undefined_obj is missing: |
| 444 hint = '%r is undefined' % self._undefined_name |
| 445 elif not isinstance(self._undefined_name, basestring): |
| 446 hint = '%s has no element %r' % ( |
| 447 object_type_repr(self._undefined_obj), |
| 448 self._undefined_name |
| 449 ) |
| 450 else: |
| 451 hint = '%r has no attribute %r' % ( |
| 452 object_type_repr(self._undefined_obj), |
| 453 self._undefined_name |
| 454 ) |
| 455 else: |
| 456 hint = self._undefined_hint |
| 457 raise self._undefined_exception(hint) |
| 458 |
| 459 @internalcode |
| 460 def __getattr__(self, name): |
| 461 if name[:2] == '__': |
| 462 raise AttributeError(name) |
| 463 return self._fail_with_undefined_error() |
| 464 |
| 465 __add__ = __radd__ = __mul__ = __rmul__ = __div__ = __rdiv__ = \ |
| 466 __truediv__ = __rtruediv__ = __floordiv__ = __rfloordiv__ = \ |
| 467 __mod__ = __rmod__ = __pos__ = __neg__ = __call__ = \ |
| 468 __getitem__ = __lt__ = __le__ = __gt__ = __ge__ = __int__ = \ |
| 469 __float__ = __complex__ = __pow__ = __rpow__ = \ |
| 470 _fail_with_undefined_error |
| 471 |
| 472 def __str__(self): |
| 473 return unicode(self).encode('utf-8') |
| 474 |
| 475 # unicode goes after __str__ because we configured 2to3 to rename |
| 476 # __unicode__ to __str__. because the 2to3 tree is not designed to |
| 477 # remove nodes from it, we leave the above __str__ around and let |
| 478 # it override at runtime. |
| 479 def __unicode__(self): |
| 480 return u'' |
| 481 |
| 482 def __len__(self): |
| 483 return 0 |
| 484 |
| 485 def __iter__(self): |
| 486 if 0: |
| 487 yield None |
| 488 |
| 489 def __nonzero__(self): |
| 490 return False |
| 491 |
| 492 def __repr__(self): |
| 493 return 'Undefined' |
| 494 |
| 495 |
| 496 class DebugUndefined(Undefined): |
| 497 """An undefined that returns the debug info when printed. |
| 498 |
| 499 >>> foo = DebugUndefined(name='foo') |
| 500 >>> str(foo) |
| 501 '{{ foo }}' |
| 502 >>> not foo |
| 503 True |
| 504 >>> foo + 42 |
| 505 Traceback (most recent call last): |
| 506 ... |
| 507 UndefinedError: 'foo' is undefined |
| 508 """ |
| 509 __slots__ = () |
| 510 |
| 511 def __unicode__(self): |
| 512 if self._undefined_hint is None: |
| 513 if self._undefined_obj is missing: |
| 514 return u'{{ %s }}' % self._undefined_name |
| 515 return '{{ no such element: %s[%r] }}' % ( |
| 516 object_type_repr(self._undefined_obj), |
| 517 self._undefined_name |
| 518 ) |
| 519 return u'{{ undefined value printed: %s }}' % self._undefined_hint |
| 520 |
| 521 |
| 522 class StrictUndefined(Undefined): |
| 523 """An undefined that barks on print and iteration as well as boolean |
| 524 tests and all kinds of comparisons. In other words: you can do nothing |
| 525 with it except checking if it's defined using the `defined` test. |
| 526 |
| 527 >>> foo = StrictUndefined(name='foo') |
| 528 >>> str(foo) |
| 529 Traceback (most recent call last): |
| 530 ... |
| 531 UndefinedError: 'foo' is undefined |
| 532 >>> not foo |
| 533 Traceback (most recent call last): |
| 534 ... |
| 535 UndefinedError: 'foo' is undefined |
| 536 >>> foo + 42 |
| 537 Traceback (most recent call last): |
| 538 ... |
| 539 UndefinedError: 'foo' is undefined |
| 540 """ |
| 541 __slots__ = () |
| 542 __iter__ = __unicode__ = __str__ = __len__ = __nonzero__ = __eq__ = \ |
| 543 __ne__ = __bool__ = Undefined._fail_with_undefined_error |
| 544 |
| 545 |
| 546 # remove remaining slots attributes, after the metaclass did the magic they |
| 547 # are unneeded and irritating as they contain wrong data for the subclasses. |
| 548 del Undefined.__slots__, DebugUndefined.__slots__, StrictUndefined.__slots__ |
OLD | NEW |