jinja2/runtime.py

   1 # -*- coding: utf-8 -*-
   2 """
   3     jinja2.runtime
   4     ~~~~~~~~~~~~~~
   5
   6     Runtime helpers.
   7
   8     :copyright: Copyright 2008 by Armin Ronacher.
   9     :license: GNU GPL.
  10 """
  11 import sys
  12 from types import FunctionType
  13 from itertools import chain, imap
  14 from jinja2.utils import Markup, partial, soft_unicode, escape, missing, concat
  15 from jinja2.exceptions import UndefinedError, TemplateRuntimeError
  16
  17
  18 # these variables are exported to the template runtime
  19 __all__ = ['LoopContext', 'Context', 'TemplateReference', 'Macro', 'Markup',
  20            'TemplateRuntimeError', 'missing', 'concat', 'escape',
  21            'markup_join', 'unicode_join']
  22
  23
  24 def markup_join(seq):
  25     """Concatenation that escapes if necessary and converts to unicode."""
  26     buf = []
  27     iterator = imap(soft_unicode, seq)
  28     for arg in iterator:
  29         buf.append(arg)
  30         if hasattr(arg, '__html__'):
  31             return Markup(u'').join(chain(buf, iterator))
  32     return concat(buf)
  33
  34
  35 def unicode_join(seq):
  36     """Simple args to unicode conversion and concatenation."""
  37     return concat(imap(unicode, seq))
  38
  39
  40 class Context(object):
  41     """The template context holds the variables of a template.  It stores the
  42     values passed to the template and also the names the template exports.
  43     Creating instances is neither supported nor useful as it's created
  44     automatically at various stages of the template evaluation and should not
  45     be created by hand.
  46
  47     The context is immutable.  Modifications on :attr:`parent` **must not**
  48     happen and modifications on :attr:`vars` are allowed from generated
  49     template code only.  Template filters and global functions marked as
  50     :func:`contextfunction`\s get the active context passed as first argument
  51     and are allowed to access the context read-only.
  52
  53     The template context supports read only dict operations (`get`,
  54     `keys`, `values`, `items`, `iterkeys`, `itervalues`, `iteritems`,
  55     `__getitem__`, `__contains__`).  Additionally there is a :meth:`resolve`
  56     method that doesn't fail with a `KeyError` but returns an
  57     :class:`Undefined` object for missing variables.
  58     """
  59     __slots__ = ('parent', 'vars', 'environment', 'exported_vars', 'name',
  60                  'blocks')
  61
  62     def __init__(self, environment, parent, name, blocks):
  63         self.parent = parent
  64         self.vars = vars = {}
  65         self.environment = environment
  66         self.exported_vars = set()
  67         self.name = name
  68
  69         # bind functions to the context of environment if required
  70         for name, obj in parent.iteritems():
  71             if type(obj) is FunctionType:
  72                 if getattr(obj, 'contextfunction', 0):
  73                     vars[name] = partial(obj, self)
  74                 elif getattr(obj, 'environmentfunction', 0):
  75                     vars[name] = partial(obj, environment)
  76
  77         # create the initial mapping of blocks.  Whenever template inheritance
  78         # takes place the runtime will update this mapping with the new blocks
  79         # from the template.
  80         self.blocks = dict((k, [v]) for k, v in blocks.iteritems())
  81
  82     def super(self, name, current):
  83         """Render a parent block."""
  84         try:
  85             blocks = self.blocks[name]
  86             block = blocks[blocks.index(current) + 1]
  87         except LookupError:
  88             return self.environment.undefined('there is no parent block '
  89                                               'called %r.' % name,
  90                                               name='super')
  91         wrap = self.environment.autoescape and Markup or (lambda x: x)
  92         render = lambda: wrap(concat(block(self)))
  93         render.__name__ = render.name = name
  94         return render
  95
  96     def get(self, key, default=None):
  97         """Returns an item from the template context, if it doesn't exist
  98         `default` is returned.
  99         """
 100         try:
 101             return self[key]
 102         except KeyError:
 103             return default
 104
 105     def resolve(self, key):
 106         """Looks up a variable like `__getitem__` or `get` but returns an
 107         :class:`Undefined` object with the name of the name looked up.
 108         """
 109         if key in self.vars:
 110             return self.vars[key]
 111         if key in self.parent:
 112             return self.parent[key]
 113         return self.environment.undefined(name=key)
 114
 115     def get_exported(self):
 116         """Get a new dict with the exported variables."""
 117         return dict((k, self.vars[k]) for k in self.exported_vars)
 118
 119     def get_all(self):
 120         """Return a copy of the complete context as dict including the
 121         global variables.
 122         """
 123         return dict(self.parent, **self.vars)
 124
 125     def _all(meth):
 126         proxy = lambda self: getattr(self.get_all(), meth)()
 127         proxy.__doc__ = getattr(dict, meth).__doc__
 128         proxy.__name__ = meth
 129         return proxy
 130
 131     keys = _all('keys')
 132     values = _all('values')
 133     items = _all('items')
 134     iterkeys = _all('iterkeys')
 135     itervalues = _all('itervalues')
 136     iteritems = _all('iteritems')
 137     del _all
 138
 139     def __contains__(self, name):
 140         return name in self.vars or name in self.parent
 141
 142     def __getitem__(self, key):
 143         """Lookup a variable or raise `KeyError` if the variable is
 144         undefined.
 145         """
 146         item = self.resolve(key)
 147         if isinstance(item, Undefined):
 148             raise KeyError(key)
 149         return item
 150
 151     def __repr__(self):
 152         return '<%s %s of %r>' % (
 153             self.__class__.__name__,
 154             repr(self.get_all()),
 155             self.name
 156         )
 157
 158
 159 class TemplateReference(object):
 160     """The `self` in templates."""
 161
 162     def __init__(self, context):
 163         self.__context = context
 164
 165     def __getitem__(self, name):
 166         func = self.__context.blocks[name][-1]
 167         wrap = self.__context.environment.autoescape and \
 168                Markup or (lambda x: x)
 169         render = lambda: wrap(concat(func(self.__context)))
 170         render.__name__ = render.name = name
 171         return render
 172
 173     def __repr__(self):
 174         return '<%s %r>' % (
 175             self.__class__.__name__,
 176             self._context.name
 177         )
 178
 179
 180 class LoopContext(object):
 181     """A loop context for dynamic iteration."""
 182
 183     def __init__(self, iterable, enforce_length=False, recurse=None):
 184         self._iterable = iterable
 185         self._next = iter(iterable).next
 186         self._length = None
 187         self._recurse = recurse
 188         self.index0 = -1
 189         if enforce_length:
 190             len(self)
 191
 192     def cycle(self, *args):
 193         """Cycles among the arguments with the current loop index."""
 194         if not args:
 195             raise TypeError('no items for cycling given')
 196         return args[self.index0 % len(args)]
 197
 198     first = property(lambda x: x.index0 == 0)
 199     last = property(lambda x: x.revindex0 == 0)
 200     index = property(lambda x: x.index0 + 1)
 201     revindex = property(lambda x: x.length - x.index0)
 202     revindex0 = property(lambda x: x.length - x.index)
 203
 204     def __len__(self):
 205         return self.length
 206
 207     def __iter__(self):
 208         return LoopContextIterator(self)
 209
 210     def loop(self, iterable):
 211         if self._recurse is None:
 212             raise TypeError('Tried to call non recursive loop.  Maybe you '
 213                             "forgot the 'recursive' modifier.")
 214         return self._recurse(iterable, self._recurse)
 215
 216     # a nifty trick to enhance the error message if someone tried to call
 217     # the the loop without or with too many arguments.
 218     __call__ = loop; del loop
 219
 220     @property
 221     def length(self):
 222         if self._length is None:
 223             try:
 224                 # first try to get the length from the iterable (if the
 225                 # iterable is a sequence)
 226                 length = len(self._iterable)
 227             except TypeError:
 228                 # if that's not possible (ie: iterating over a generator)
 229                 # we have to convert the iterable into a sequence and
 230                 # use the length of that.
 231                 self._iterable = tuple(self._iterable)
 232                 self._next = iter(self._iterable).next
 233                 length = len(tuple(self._iterable)) + self.index0 + 1
 234             self._length = length
 235         return self._length
 236
 237     def __repr__(self):
 238         return '<%s %r/%r>' % (
 239             self.__class__.__name__,
 240             self.index,
 241             self.length
 242         )
 243
 244
 245 class LoopContextIterator(object):
 246     """The iterator for a loop context."""
 247     __slots__ = ('context',)
 248
 249     def __init__(self, context):
 250         self.context = context
 251
 252     def __iter__(self):
 253         return self
 254
 255     def next(self):
 256         ctx = self.context
 257         ctx.index0 += 1
 258         return ctx._next(), ctx
 259
 260
 261 class Macro(object):
 262     """Wraps a macro."""
 263
 264     def __init__(self, environment, func, name, arguments, defaults,
 265                  catch_kwargs, catch_varargs, caller):
 266         self._environment = environment
 267         self._func = func
 268         self._argument_count = len(arguments)
 269         self.name = name
 270         self.arguments = arguments
 271         self.defaults = defaults
 272         self.catch_kwargs = catch_kwargs
 273         self.catch_varargs = catch_varargs
 274         self.caller = caller
 275
 276     def __call__(self, *args, **kwargs):
 277         arguments = []
 278         for idx, name in enumerate(self.arguments):
 279             try:
 280                 value = args[idx]
 281             except:
 282                 try:
 283                     value = kwargs.pop(name)
 284                 except:
 285                     try:
 286                         value = self.defaults[idx - self._argument_count]
 287                     except:
 288                         value = self._environment.undefined(
 289                             'parameter %r was not provided' % name, name=name)
 290             arguments.append(value)
 291
 292         # it's important that the order of these arguments does not change
 293         # if not also changed in the compiler's `function_scoping` method.
 294         # the order is caller, keyword arguments, positional arguments!
 295         if self.caller:
 296             caller = kwargs.pop('caller', None)
 297             if caller is None:
 298                 caller = self._environment.undefined('No caller defined',
 299                                                      name='caller')
 300             arguments.append(caller)
 301         if self.catch_kwargs:
 302             arguments.append(kwargs)
 303         elif kwargs:
 304             raise TypeError('macro %r takes no keyword argument %r' %
 305                             (self.name, iter(kwargs).next()))
 306         if self.catch_varargs:
 307             arguments.append(args[self._argument_count:])
 308         elif len(args) > self._argument_count:
 309             raise TypeError('macro %r takes not more than %d argument(s)' %
 310                             (self.name, len(self.arguments)))
 311         return self._func(*arguments)
 312
 313     def __repr__(self):
 314         return '<%s %s>' % (
 315             self.__class__.__name__,
 316             self.name is None and 'anonymous' or repr(self.name)
 317         )
 318
 319
 320 def fail_with_undefined_error(self, *args, **kwargs):
 321     """Regular callback function for undefined objects that raises an
 322     `UndefinedError` on call.
 323     """
 324     if self._undefined_hint is None:
 325         if self._undefined_obj is None:
 326             hint = '%r is undefined' % self._undefined_name
 327         elif not isinstance(self._undefined_name, basestring):
 328             hint = '%r object has no element %r' % (
 329                 self._undefined_obj.__class__.__name__,
 330                 self._undefined_name
 331             )
 332         else:
 333             hint = '%r object has no attribute %r' % (
 334                 self._undefined_obj.__class__.__name__,
 335                 self._undefined_name
 336             )
 337     else:
 338         hint = self._undefined_hint
 339     raise self._undefined_exception(hint)
 340
 341
 342 class Undefined(object):
 343     """The default undefined type.  This undefined type can be printed and
 344     iterated over, but every other access will raise an :exc:`UndefinedError`:
 345
 346     >>> foo = Undefined(name='foo')
 347     >>> str(foo)
 348     ''
 349     >>> not foo
 350     True
 351     >>> foo + 42
 352     Traceback (most recent call last):
 353       ...
 354     jinja2.exceptions.UndefinedError: 'foo' is undefined
 355     """
 356     __slots__ = ('_undefined_hint', '_undefined_obj', '_undefined_name',
 357                  '_undefined_exception')
 358
 359     def __init__(self, hint=None, obj=None, name=None, exc=UndefinedError):
 360         self._undefined_hint = hint
 361         self._undefined_obj = obj
 362         self._undefined_name = name
 363         self._undefined_exception = exc
 364
 365     __add__ = __radd__ = __mul__ = __rmul__ = __div__ = __rdiv__ = \
 366     __realdiv__ = __rrealdiv__ = __floordiv__ = __rfloordiv__ = \
 367     __mod__ = __rmod__ = __pos__ = __neg__ = __call__ = \
 368     __getattr__ = __getitem__ = __lt__ = __le__ = __gt__ = __ge__ = \
 369         fail_with_undefined_error
 370
 371     def __str__(self):
 372         return self.__unicode__().encode('utf-8')
 373
 374     def __repr__(self):
 375         return 'Undefined'
 376
 377     def __unicode__(self):
 378         return u''
 379
 380     def __len__(self):
 381         return 0
 382
 383     def __iter__(self):
 384         if 0:
 385             yield None
 386
 387     def __nonzero__(self):
 388         return False
 389
 390
 391 class DebugUndefined(Undefined):
 392     """An undefined that returns the debug info when printed.
 393
 394     >>> foo = DebugUndefined(name='foo')
 395     >>> str(foo)
 396     '{{ foo }}'
 397     >>> not foo
 398     True
 399     >>> foo + 42
 400     Traceback (most recent call last):
 401       ...
 402     jinja2.exceptions.UndefinedError: 'foo' is undefined
 403     """
 404     __slots__ = ()
 405
 406     def __unicode__(self):
 407         if self._undefined_hint is None:
 408             if self._undefined_obj is None:
 409                 return u'{{ %s }}' % self._undefined_name
 410             return '{{ no such element: %s[%r] }}' % (
 411                 self._undefined_obj.__class__.__name__,
 412                 self._undefined_name
 413             )
 414         return u'{{ undefined value printed: %s }}' % self._undefined_hint
 415
 416
 417 class StrictUndefined(Undefined):
 418     """An undefined that barks on print and iteration as well as boolean
 419     tests and all kinds of comparisons.  In other words: you can do nothing
 420     with it except checking if it's defined using the `defined` test.
 421
 422     >>> foo = StrictUndefined(name='foo')
 423     >>> str(foo)
 424     Traceback (most recent call last):
 425       ...
 426     jinja2.exceptions.UndefinedError: 'foo' is undefined
 427     >>> not foo
 428     Traceback (most recent call last):
 429       ...
 430     jinja2.exceptions.UndefinedError: 'foo' is undefined
 431     >>> foo + 42
 432     Traceback (most recent call last):
 433       ...
 434     jinja2.exceptions.UndefinedError: 'foo' is undefined
 435     """
 436     __slots__ = ()
 437     __iter__ = __unicode__ = __len__ = __nonzero__ = __eq__ = __ne__ = \
 438         fail_with_undefined_error
 439
 440
 441 # remove remaining slots attributes, after the metaclass did the magic they
 442 # are unneeded and irritating as they contain wrong data for the subclasses.
 443 del Undefined.__slots__, DebugUndefined.__slots__, StrictUndefined.__slots__