jinja2/nodes.py

   1 # -*- coding: utf-8 -*-
   2 """
   3     jinja2.nodes
   4     ~~~~~~~~~~~~
   5
   6     This module implements additional nodes derived from the ast base node.
   7
   8     It also provides some node tree helper functions like `in_lineno` and
   9     `get_nodes` used by the parser and translator in order to normalize
  10     python and jinja nodes.
  11
  12     :copyright: (c) 2009 by the Jinja Team.
  13     :license: BSD, see LICENSE for more details.
  14 """
  15 import operator
  16 from itertools import chain, izip
  17 from collections import deque
  18 from jinja2.utils import Markup
  19
  20
  21 _binop_to_func = {
  22     '*':        operator.mul,
  23     '/':        operator.truediv,
  24     '//':       operator.floordiv,
  25     '**':       operator.pow,
  26     '%':        operator.mod,
  27     '+':        operator.add,
  28     '-':        operator.sub
  29 }
  30
  31 _uaop_to_func = {
  32     'not':      operator.not_,
  33     '+':        operator.pos,
  34     '-':        operator.neg
  35 }
  36
  37 _cmpop_to_func = {
  38     'eq':       operator.eq,
  39     'ne':       operator.ne,
  40     'gt':       operator.gt,
  41     'gteq':     operator.ge,
  42     'lt':       operator.lt,
  43     'lteq':     operator.le,
  44     'in':       lambda a, b: a in b,
  45     'notin':    lambda a, b: a not in b
  46 }
  47
  48
  49 class Impossible(Exception):
  50     """Raised if the node could not perform a requested action."""
  51
  52
  53 class NodeType(type):
  54     """A metaclass for nodes that handles the field and attribute
  55     inheritance.  fields and attributes from the parent class are
  56     automatically forwarded to the child."""
  57
  58     def __new__(cls, name, bases, d):
  59         for attr in 'fields', 'attributes':
  60             storage = []
  61             storage.extend(getattr(bases[0], attr, ()))
  62             storage.extend(d.get(attr, ()))
  63             assert len(bases) == 1, 'multiple inheritance not allowed'
  64             assert len(storage) == len(set(storage)), 'layout conflict'
  65             d[attr] = tuple(storage)
  66         d.setdefault('abstract', False)
  67         return type.__new__(cls, name, bases, d)
  68
  69
  70 class Node(object):
  71     """Baseclass for all Jinja2 nodes.  There are a number of nodes available
  72     of different types.  There are three major types:
  73
  74     -   :class:`Stmt`: statements
  75     -   :class:`Expr`: expressions
  76     -   :class:`Helper`: helper nodes
  77     -   :class:`Template`: the outermost wrapper node
  78
  79     All nodes have fields and attributes.  Fields may be other nodes, lists,
  80     or arbitrary values.  Fields are passed to the constructor as regular
  81     positional arguments, attributes as keyword arguments.  Each node has
  82     two attributes: `lineno` (the line number of the node) and `environment`.
  83     The `environment` attribute is set at the end of the parsing process for
  84     all nodes automatically.
  85     """
  86     __metaclass__ = NodeType
  87     fields = ()
  88     attributes = ('lineno', 'environment')
  89     abstract = True
  90
  91     def __init__(self, *fields, **attributes):
  92         if self.abstract:
  93             raise TypeError('abstract nodes are not instanciable')
  94         if fields:
  95             if len(fields) != len(self.fields):
  96                 if not self.fields:
  97                     raise TypeError('%r takes 0 arguments' %
  98                                     self.__class__.__name__)
  99                 raise TypeError('%r takes 0 or %d argument%s' % (
 100                     self.__class__.__name__,
 101                     len(self.fields),
 102                     len(self.fields) != 1 and 's' or ''
 103                 ))
 104             for name, arg in izip(self.fields, fields):
 105                 setattr(self, name, arg)
 106         for attr in self.attributes:
 107             setattr(self, attr, attributes.pop(attr, None))
 108         if attributes:
 109             raise TypeError('unknown attribute %r' %
 110                             iter(attributes).next())
 111
 112     def iter_fields(self, exclude=None, only=None):
 113         """This method iterates over all fields that are defined and yields
 114         ``(key, value)`` tuples.  Per default all fields are returned, but
 115         it's possible to limit that to some fields by providing the `only`
 116         parameter or to exclude some using the `exclude` parameter.  Both
 117         should be sets or tuples of field names.
 118         """
 119         for name in self.fields:
 120             if (exclude is only is None) or \
 121                (exclude is not None and name not in exclude) or \
 122                (only is not None and name in only):
 123                 try:
 124                     yield name, getattr(self, name)
 125                 except AttributeError:
 126                     pass
 127
 128     def iter_child_nodes(self, exclude=None, only=None):
 129         """Iterates over all direct child nodes of the node.  This iterates
 130         over all fields and yields the values of they are nodes.  If the value
 131         of a field is a list all the nodes in that list are returned.
 132         """
 133         for field, item in self.iter_fields(exclude, only):
 134             if isinstance(item, list):
 135                 for n in item:
 136                     if isinstance(n, Node):
 137                         yield n
 138             elif isinstance(item, Node):
 139                 yield item
 140
 141     def find(self, node_type):
 142         """Find the first node of a given type.  If no such node exists the
 143         return value is `None`.
 144         """
 145         for result in self.find_all(node_type):
 146             return result
 147
 148     def find_all(self, node_type):
 149         """Find all the nodes of a given type.  If the type is a tuple,
 150         the check is performed for any of the tuple items.
 151         """
 152         for child in self.iter_child_nodes():
 153             if isinstance(child, node_type):
 154                 yield child
 155             for result in child.find_all(node_type):
 156                 yield result
 157
 158     def set_ctx(self, ctx):
 159         """Reset the context of a node and all child nodes.  Per default the
 160         parser will all generate nodes that have a 'load' context as it's the
 161         most common one.  This method is used in the parser to set assignment
 162         targets and other nodes to a store context.
 163         """
 164         todo = deque([self])
 165         while todo:
 166             node = todo.popleft()
 167             if 'ctx' in node.fields:
 168                 node.ctx = ctx
 169             todo.extend(node.iter_child_nodes())
 170         return self
 171
 172     def set_lineno(self, lineno, override=False):
 173         """Set the line numbers of the node and children."""
 174         todo = deque([self])
 175         while todo:
 176             node = todo.popleft()
 177             if 'lineno' in node.attributes:
 178                 if node.lineno is None or override:
 179                     node.lineno = lineno
 180             todo.extend(node.iter_child_nodes())
 181         return self
 182
 183     def set_environment(self, environment):
 184         """Set the environment for all nodes."""
 185         todo = deque([self])
 186         while todo:
 187             node = todo.popleft()
 188             node.environment = environment
 189             todo.extend(node.iter_child_nodes())
 190         return self
 191
 192     def __eq__(self, other):
 193         return type(self) is type(other) and \
 194                tuple(self.iter_fields()) == tuple(other.iter_fields())
 195
 196     def __ne__(self, other):
 197         return not self.__eq__(other)
 198
 199     def __repr__(self):
 200         return '%s(%s)' % (
 201             self.__class__.__name__,
 202             ', '.join('%s=%r' % (arg, getattr(self, arg, None)) for
 203                       arg in self.fields)
 204         )
 205
 206
 207 class Stmt(Node):
 208     """Base node for all statements."""
 209     abstract = True
 210
 211
 212 class Helper(Node):
 213     """Nodes that exist in a specific context only."""
 214     abstract = True
 215
 216
 217 class Template(Node):
 218     """Node that represents a template.  This must be the outermost node that
 219     is passed to the compiler.
 220     """
 221     fields = ('body',)
 222
 223
 224 class Output(Stmt):
 225     """A node that holds multiple expressions which are then printed out.
 226     This is used both for the `print` statement and the regular template data.
 227     """
 228     fields = ('nodes',)
 229
 230
 231 class Extends(Stmt):
 232     """Represents an extends statement."""
 233     fields = ('template',)
 234
 235
 236 class For(Stmt):
 237     """The for loop.  `target` is the target for the iteration (usually a
 238     :class:`Name` or :class:`Tuple`), `iter` the iterable.  `body` is a list
 239     of nodes that are used as loop-body, and `else_` a list of nodes for the
 240     `else` block.  If no else node exists it has to be an empty list.
 241
 242     For filtered nodes an expression can be stored as `test`, otherwise `None`.
 243     """
 244     fields = ('target', 'iter', 'body', 'else_', 'test', 'recursive')
 245
 246
 247 class If(Stmt):
 248     """If `test` is true, `body` is rendered, else `else_`."""
 249     fields = ('test', 'body', 'else_')
 250
 251
 252 class Macro(Stmt):
 253     """A macro definition.  `name` is the name of the macro, `args` a list of
 254     arguments and `defaults` a list of defaults if there are any.  `body` is
 255     a list of nodes for the macro body.
 256     """
 257     fields = ('name', 'args', 'defaults', 'body')
 258
 259
 260 class CallBlock(Stmt):
 261     """Like a macro without a name but a call instead.  `call` is called with
 262     the unnamed macro as `caller` argument this node holds.
 263     """
 264     fields = ('call', 'args', 'defaults', 'body')
 265
 266
 267 class FilterBlock(Stmt):
 268     """Node for filter sections."""
 269     fields = ('body', 'filter')
 270
 271
 272 class Block(Stmt):
 273     """A node that represents a block."""
 274     fields = ('name', 'body', 'scoped')
 275
 276
 277 class Include(Stmt):
 278     """A node that represents the include tag."""
 279     fields = ('template', 'with_context', 'ignore_missing')
 280
 281
 282 class Import(Stmt):
 283     """A node that represents the import tag."""
 284     fields = ('template', 'target', 'with_context')
 285
 286
 287 class FromImport(Stmt):
 288     """A node that represents the from import tag.  It's important to not
 289     pass unsafe names to the name attribute.  The compiler translates the
 290     attribute lookups directly into getattr calls and does *not* use the
 291     subscript callback of the interface.  As exported variables may not
 292     start with double underscores (which the parser asserts) this is not a
 293     problem for regular Jinja code, but if this node is used in an extension
 294     extra care must be taken.
 295
 296     The list of names may contain tuples if aliases are wanted.
 297     """
 298     fields = ('template', 'names', 'with_context')
 299
 300
 301 class ExprStmt(Stmt):
 302     """A statement that evaluates an expression and discards the result."""
 303     fields = ('node',)
 304
 305
 306 class Assign(Stmt):
 307     """Assigns an expression to a target."""
 308     fields = ('target', 'node')
 309
 310
 311 class Expr(Node):
 312     """Baseclass for all expressions."""
 313     abstract = True
 314
 315     def as_const(self):
 316         """Return the value of the expression as constant or raise
 317         :exc:`Impossible` if this was not possible:
 318
 319         >>> Add(Const(23), Const(42)).as_const()
 320         65
 321         >>> Add(Const(23), Name('var', 'load')).as_const()
 322         Traceback (most recent call last):
 323           ...
 324         Impossible
 325
 326         This requires the `environment` attribute of all nodes to be
 327         set to the environment that created the nodes.
 328         """
 329         raise Impossible()
 330
 331     def can_assign(self):
 332         """Check if it's possible to assign something to this node."""
 333         return False
 334
 335
 336 class BinExpr(Expr):
 337     """Baseclass for all binary expressions."""
 338     fields = ('left', 'right')
 339     operator = None
 340     abstract = True
 341
 342     def as_const(self):
 343         f = _binop_to_func[self.operator]
 344         try:
 345             return f(self.left.as_const(), self.right.as_const())
 346         except:
 347             raise Impossible()
 348
 349
 350 class UnaryExpr(Expr):
 351     """Baseclass for all unary expressions."""
 352     fields = ('node',)
 353     operator = None
 354     abstract = True
 355
 356     def as_const(self):
 357         f = _uaop_to_func[self.operator]
 358         try:
 359             return f(self.node.as_const())
 360         except:
 361             raise Impossible()
 362
 363
 364 class Name(Expr):
 365     """Looks up a name or stores a value in a name.
 366     The `ctx` of the node can be one of the following values:
 367
 368     -   `store`: store a value in the name
 369     -   `load`: load that name
 370     -   `param`: like `store` but if the name was defined as function parameter.
 371     """
 372     fields = ('name', 'ctx')
 373
 374     def can_assign(self):
 375         return self.name not in ('true', 'false', 'none',
 376                                  'True', 'False', 'None')
 377
 378
 379 class Literal(Expr):
 380     """Baseclass for literals."""
 381     abstract = True
 382
 383
 384 class Const(Literal):
 385     """All constant values.  The parser will return this node for simple
 386     constants such as ``42`` or ``"foo"`` but it can be used to store more
 387     complex values such as lists too.  Only constants with a safe
 388     representation (objects where ``eval(repr(x)) == x`` is true).
 389     """
 390     fields = ('value',)
 391
 392     def as_const(self):
 393         return self.value
 394
 395     @classmethod
 396     def from_untrusted(cls, value, lineno=None, environment=None):
 397         """Return a const object if the value is representable as
 398         constant value in the generated code, otherwise it will raise
 399         an `Impossible` exception.
 400         """
 401         from compiler import has_safe_repr
 402         if not has_safe_repr(value):
 403             raise Impossible()
 404         return cls(value, lineno=lineno, environment=environment)
 405
 406
 407 class TemplateData(Literal):
 408     """A constant template string."""
 409     fields = ('data',)
 410
 411     def as_const(self):
 412         if self.environment.autoescape:
 413             return Markup(self.data)
 414         return self.data
 415
 416
 417 class Tuple(Literal):
 418     """For loop unpacking and some other things like multiple arguments
 419     for subscripts.  Like for :class:`Name` `ctx` specifies if the tuple
 420     is used for loading the names or storing.
 421     """
 422     fields = ('items', 'ctx')
 423
 424     def as_const(self):
 425         return tuple(x.as_const() for x in self.items)
 426
 427     def can_assign(self):
 428         for item in self.items:
 429             if not item.can_assign():
 430                 return False
 431         return True
 432
 433
 434 class List(Literal):
 435     """Any list literal such as ``[1, 2, 3]``"""
 436     fields = ('items',)
 437
 438     def as_const(self):
 439         return [x.as_const() for x in self.items]
 440
 441
 442 class Dict(Literal):
 443     """Any dict literal such as ``{1: 2, 3: 4}``.  The items must be a list of
 444     :class:`Pair` nodes.
 445     """
 446     fields = ('items',)
 447
 448     def as_const(self):
 449         return dict(x.as_const() for x in self.items)
 450
 451
 452 class Pair(Helper):
 453     """A key, value pair for dicts."""
 454     fields = ('key', 'value')
 455
 456     def as_const(self):
 457         return self.key.as_const(), self.value.as_const()
 458
 459
 460 class Keyword(Helper):
 461     """A key, value pair for keyword arguments where key is a string."""
 462     fields = ('key', 'value')
 463
 464     def as_const(self):
 465         return self.key, self.value.as_const()
 466
 467
 468 class CondExpr(Expr):
 469     """A conditional expression (inline if expression).  (``{{
 470     foo if bar else baz }}``)
 471     """
 472     fields = ('test', 'expr1', 'expr2')
 473
 474     def as_const(self):
 475         if self.test.as_const():
 476             return self.expr1.as_const()
 477
 478         # if we evaluate to an undefined object, we better do that at runtime
 479         if self.expr2 is None:
 480             raise Impossible()
 481
 482         return self.expr2.as_const()
 483
 484
 485 class Filter(Expr):
 486     """This node applies a filter on an expression.  `name` is the name of
 487     the filter, the rest of the fields are the same as for :class:`Call`.
 488
 489     If the `node` of a filter is `None` the contents of the last buffer are
 490     filtered.  Buffers are created by macros and filter blocks.
 491     """
 492     fields = ('node', 'name', 'args', 'kwargs', 'dyn_args', 'dyn_kwargs')
 493
 494     def as_const(self, obj=None):
 495         if self.node is obj is None:
 496             raise Impossible()
 497         filter = self.environment.filters.get(self.name)
 498         if filter is None or getattr(filter, 'contextfilter', False):
 499             raise Impossible()
 500         if obj is None:
 501             obj = self.node.as_const()
 502         args = [x.as_const() for x in self.args]
 503         if getattr(filter, 'environmentfilter', False):
 504             args.insert(0, self.environment)
 505         kwargs = dict(x.as_const() for x in self.kwargs)
 506         if self.dyn_args is not None:
 507             try:
 508                 args.extend(self.dyn_args.as_const())
 509             except:
 510                 raise Impossible()
 511         if self.dyn_kwargs is not None:
 512             try:
 513                 kwargs.update(self.dyn_kwargs.as_const())
 514             except:
 515                 raise Impossible()
 516         try:
 517             return filter(obj, *args, **kwargs)
 518         except:
 519             raise Impossible()
 520
 521
 522 class Test(Expr):
 523     """Applies a test on an expression.  `name` is the name of the test, the
 524     rest of the fields are the same as for :class:`Call`.
 525     """
 526     fields = ('node', 'name', 'args', 'kwargs', 'dyn_args', 'dyn_kwargs')
 527
 528
 529 class Call(Expr):
 530     """Calls an expression.  `args` is a list of arguments, `kwargs` a list
 531     of keyword arguments (list of :class:`Keyword` nodes), and `dyn_args`
 532     and `dyn_kwargs` has to be either `None` or a node that is used as
 533     node for dynamic positional (``*args``) or keyword (``**kwargs``)
 534     arguments.
 535     """
 536     fields = ('node', 'args', 'kwargs', 'dyn_args', 'dyn_kwargs')
 537
 538     def as_const(self):
 539         obj = self.node.as_const()
 540
 541         # don't evaluate context functions
 542         args = [x.as_const() for x in self.args]
 543         if getattr(obj, 'contextfunction', False):
 544             raise Impossible()
 545         elif getattr(obj, 'environmentfunction', False):
 546             args.insert(0, self.environment)
 547
 548         kwargs = dict(x.as_const() for x in self.kwargs)
 549         if self.dyn_args is not None:
 550             try:
 551                 args.extend(self.dyn_args.as_const())
 552             except:
 553                 raise Impossible()
 554         if self.dyn_kwargs is not None:
 555             try:
 556                 kwargs.update(self.dyn_kwargs.as_const())
 557             except:
 558                 raise Impossible()
 559         try:
 560             return obj(*args, **kwargs)
 561         except:
 562             raise Impossible()
 563
 564
 565 class Getitem(Expr):
 566     """Get an attribute or item from an expression and prefer the item."""
 567     fields = ('node', 'arg', 'ctx')
 568
 569     def as_const(self):
 570         if self.ctx != 'load':
 571             raise Impossible()
 572         try:
 573             return self.environment.getitem(self.node.as_const(),
 574                                             self.arg.as_const())
 575         except:
 576             raise Impossible()
 577
 578     def can_assign(self):
 579         return False
 580
 581
 582 class Getattr(Expr):
 583     """Get an attribute or item from an expression that is a ascii-only
 584     bytestring and prefer the attribute.
 585     """
 586     fields = ('node', 'attr', 'ctx')
 587
 588     def as_const(self):
 589         if self.ctx != 'load':
 590             raise Impossible()
 591         try:
 592             return self.environment.getattr(self.node.as_const(), arg)
 593         except:
 594             raise Impossible()
 595
 596     def can_assign(self):
 597         return False
 598
 599
 600 class Slice(Expr):
 601     """Represents a slice object.  This must only be used as argument for
 602     :class:`Subscript`.
 603     """
 604     fields = ('start', 'stop', 'step')
 605
 606     def as_const(self):
 607         def const(obj):
 608             if obj is None:
 609                 return obj
 610             return obj.as_const()
 611         return slice(const(self.start), const(self.stop), const(self.step))
 612
 613
 614 class Concat(Expr):
 615     """Concatenates the list of expressions provided after converting them to
 616     unicode.
 617     """
 618     fields = ('nodes',)
 619
 620     def as_const(self):
 621         return ''.join(unicode(x.as_const()) for x in self.nodes)
 622
 623
 624 class Compare(Expr):
 625     """Compares an expression with some other expressions.  `ops` must be a
 626     list of :class:`Operand`\s.
 627     """
 628     fields = ('expr', 'ops')
 629
 630     def as_const(self):
 631         result = value = self.expr.as_const()
 632         try:
 633             for op in self.ops:
 634                 new_value = op.expr.as_const()
 635                 result = _cmpop_to_func[op.op](value, new_value)
 636                 value = new_value
 637         except:
 638             raise Impossible()
 639         return result
 640
 641
 642 class Operand(Helper):
 643     """Holds an operator and an expression."""
 644     fields = ('op', 'expr')
 645
 646 if __debug__:
 647     Operand.__doc__ += '\nThe following operators are available: ' + \
 648         ', '.join(sorted('``%s``' % x for x in set(_binop_to_func) |
 649                   set(_uaop_to_func) | set(_cmpop_to_func)))
 650
 651
 652 class Mul(BinExpr):
 653     """Multiplies the left with the right node."""
 654     operator = '*'
 655
 656
 657 class Div(BinExpr):
 658     """Divides the left by the right node."""
 659     operator = '/'
 660
 661
 662 class FloorDiv(BinExpr):
 663     """Divides the left by the right node and truncates conver the
 664     result into an integer by truncating.
 665     """
 666     operator = '//'
 667
 668
 669 class Add(BinExpr):
 670     """Add the left to the right node."""
 671     operator = '+'
 672
 673
 674 class Sub(BinExpr):
 675     """Substract the right from the left node."""
 676     operator = '-'
 677
 678
 679 class Mod(BinExpr):
 680     """Left modulo right."""
 681     operator = '%'
 682
 683
 684 class Pow(BinExpr):
 685     """Left to the power of right."""
 686     operator = '**'
 687
 688
 689 class And(BinExpr):
 690     """Short circuited AND."""
 691     operator = 'and'
 692
 693     def as_const(self):
 694         return self.left.as_const() and self.right.as_const()
 695
 696
 697 class Or(BinExpr):
 698     """Short circuited OR."""
 699     operator = 'or'
 700
 701     def as_const(self):
 702         return self.left.as_const() or self.right.as_const()
 703
 704
 705 class Not(UnaryExpr):
 706     """Negate the expression."""
 707     operator = 'not'
 708
 709
 710 class Neg(UnaryExpr):
 711     """Make the expression negative."""
 712     operator = '-'
 713
 714
 715 class Pos(UnaryExpr):
 716     """Make the expression positive (noop for most expressions)"""
 717     operator = '+'
 718
 719
 720 # Helpers for extensions
 721
 722
 723 class EnvironmentAttribute(Expr):
 724     """Loads an attribute from the environment object.  This is useful for
 725     extensions that want to call a callback stored on the environment.
 726     """
 727     fields = ('name',)
 728
 729
 730 class ExtensionAttribute(Expr):
 731     """Returns the attribute of an extension bound to the environment.
 732     The identifier is the identifier of the :class:`Extension`.
 733
 734     This node is usually constructed by calling the
 735     :meth:`~jinja2.ext.Extension.attr` method on an extension.
 736     """
 737     fields = ('identifier', 'name')
 738
 739
 740 class ImportedName(Expr):
 741     """If created with an import name the import name is returned on node
 742     access.  For example ``ImportedName('cgi.escape')`` returns the `escape`
 743     function from the cgi module on evaluation.  Imports are optimized by the
 744     compiler so there is no need to assign them to local variables.
 745     """
 746     fields = ('importname',)
 747
 748
 749 class InternalName(Expr):
 750     """An internal name in the compiler.  You cannot create these nodes
 751     yourself but the parser provides a
 752     :meth:`~jinja2.parser.Parser.free_identifier` method that creates
 753     a new identifier for you.  This identifier is not available from the
 754     template and is not threated specially by the compiler.
 755     """
 756     fields = ('name',)
 757
 758     def __init__(self):
 759         raise TypeError('Can\'t create internal names.  Use the '
 760                         '`free_identifier` method on a parser.')
 761
 762
 763 class MarkSafe(Expr):
 764     """Mark the wrapped expression as safe (wrap it as `Markup`)."""
 765     fields = ('expr',)
 766
 767     def as_const(self):
 768         return Markup(self.expr.as_const())
 769
 770
 771 class ContextReference(Expr):
 772     """Returns the current template context."""
 773
 774
 775 class Continue(Stmt):
 776     """Continue a loop."""
 777
 778
 779 class Break(Stmt):
 780     """Break a loop."""
 781
 782
 783 class Scope(Stmt):
 784     """An artificial scope."""
 785     fields = ('body',)
 786
 787
 788 # make sure nobody creates custom nodes
 789 def _failing_new(*args, **kwargs):
 790     raise TypeError('can\'t create custom node types')
 791 NodeType.__new__ = staticmethod(_failing_new); del _failing_new