jinja2/runtime.py

   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__