1 # -*- coding: utf-8 -*-
6 This module implements additional nodes derived from the ast base node.
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.
12 :copyright: 2008 by Armin Ronacher.
13 :license: BSD, see LICENSE for more details.
16 from itertools import chain, izip
17 from collections import deque
18 from jinja2.utils import Markup
23 '/': operator.truediv,
24 '//': operator.floordiv,
44 'in': lambda a, b: a in b,
45 'notin': lambda a, b: a not in b
49 class Impossible(Exception):
50 """Raised if the node could not perform a requested action."""
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."""
58 def __new__(cls, name, bases, d):
59 for attr in 'fields', 'attributes':
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)
71 """Baseclass for all Jinja2 nodes. There are a number of nodes available
72 of different types. There are three major types:
74 - :class:`Stmt`: statements
75 - :class:`Expr`: expressions
76 - :class:`Helper`: helper nodes
77 - :class:`Template`: the outermost wrapper node
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.
86 __metaclass__ = NodeType
88 attributes = ('lineno', 'environment')
91 def __init__(self, *fields, **attributes):
93 raise TypeError('abstract nodes are not instanciable')
95 if len(fields) != len(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__,
102 len(self.fields) != 1 and 's' or ''
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))
109 raise TypeError('unknown attribute %r' %
110 iter(attributes).next())
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.
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):
124 yield name, getattr(self, name)
125 except AttributeError:
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.
133 for field, item in self.iter_fields(exclude, only):
134 if isinstance(item, list):
136 if isinstance(n, Node):
138 elif isinstance(item, Node):
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`.
145 for result in self.find_all(node_type):
148 def find_all(self, node_type):
149 """Find all the nodes of a given type."""
150 for child in self.iter_child_nodes():
151 if isinstance(child, node_type):
153 for result in child.find_all(node_type):
156 def set_ctx(self, ctx):
157 """Reset the context of a node and all child nodes. Per default the
158 parser will all generate nodes that have a 'load' context as it's the
159 most common one. This method is used in the parser to set assignment
160 targets and other nodes to a store context.
164 node = todo.popleft()
165 if 'ctx' in node.fields:
167 todo.extend(node.iter_child_nodes())
170 def set_lineno(self, lineno, override=False):
171 """Set the line numbers of the node and children."""
174 node = todo.popleft()
175 if 'lineno' in node.attributes:
176 if node.lineno is None or override:
178 todo.extend(node.iter_child_nodes())
181 def set_environment(self, environment):
182 """Set the environment for all nodes."""
185 node = todo.popleft()
186 node.environment = environment
187 todo.extend(node.iter_child_nodes())
190 def __eq__(self, other):
191 return type(self) is type(other) and \
192 tuple(self.iter_fields()) == tuple(other.iter_fields())
194 def __ne__(self, other):
195 return not self.__eq__(other)
199 self.__class__.__name__,
200 ', '.join('%s=%r' % (arg, getattr(self, arg, None)) for
206 """Base node for all statements."""
211 """Nodes that exist in a specific context only."""
215 class Template(Node):
216 """Node that represents a template. This must be the outermost node that
217 is passed to the compiler.
223 """A node that holds multiple expressions which are then printed out.
224 This is used both for the `print` statement and the regular template data.
230 """Represents an extends statement."""
231 fields = ('template',)
235 """The for loop. `target` is the target for the iteration (usually a
236 :class:`Name` or :class:`Tuple`), `iter` the iterable. `body` is a list
237 of nodes that are used as loop-body, and `else_` a list of nodes for the
238 `else` block. If no else node exists it has to be an empty list.
240 For filtered nodes an expression can be stored as `test`, otherwise `None`.
242 fields = ('target', 'iter', 'body', 'else_', 'test', 'recursive')
246 """If `test` is true, `body` is rendered, else `else_`."""
247 fields = ('test', 'body', 'else_')
251 """A macro definition. `name` is the name of the macro, `args` a list of
252 arguments and `defaults` a list of defaults if there are any. `body` is
253 a list of nodes for the macro body.
255 fields = ('name', 'args', 'defaults', 'body')
258 class CallBlock(Stmt):
259 """Like a macro without a name but a call instead. `call` is called with
260 the unnamed macro as `caller` argument this node holds.
262 fields = ('call', 'args', 'defaults', 'body')
265 class FilterBlock(Stmt):
266 """Node for filter sections."""
267 fields = ('body', 'filter')
271 """A node that represents a block."""
272 fields = ('name', 'body')
276 """A node that represents the include tag."""
277 fields = ('template', 'with_context')
281 """A node that represents the import tag."""
282 fields = ('template', 'target', 'with_context')
285 class FromImport(Stmt):
286 """A node that represents the from import tag. It's important to not
287 pass unsafe names to the name attribute. The compiler translates the
288 attribute lookups directly into getattr calls and does *not* use the
289 subscript callback of the interface. As exported variables may not
290 start with double underscores (which the parser asserts) this is not a
291 problem for regular Jinja code, but if this node is used in an extension
292 extra care must be taken.
294 The list of names may contain tuples if aliases are wanted.
296 fields = ('template', 'names', 'with_context')
299 class ExprStmt(Stmt):
300 """A statement that evaluates an expression and discards the result."""
305 """Assigns an expression to a target."""
306 fields = ('target', 'node')
310 """Baseclass for all expressions."""
314 """Return the value of the expression as constant or raise
315 :exc:`Impossible` if this was not possible:
317 >>> Add(Const(23), Const(42)).as_const()
319 >>> Add(Const(23), Name('var', 'load')).as_const()
320 Traceback (most recent call last):
324 This requires the `environment` attribute of all nodes to be
325 set to the environment that created the nodes.
329 def can_assign(self):
330 """Check if it's possible to assign something to this node."""
335 """Baseclass for all binary expressions."""
336 fields = ('left', 'right')
341 f = _binop_to_func[self.operator]
343 return f(self.left.as_const(), self.right.as_const())
348 class UnaryExpr(Expr):
349 """Baseclass for all unary expressions."""
355 f = _uaop_to_func[self.operator]
357 return f(self.node.as_const())
363 """Looks up a name or stores a value in a name.
364 The `ctx` of the node can be one of the following values:
366 - `store`: store a value in the name
367 - `load`: load that name
368 - `param`: like `store` but if the name was defined as function parameter.
370 fields = ('name', 'ctx')
372 def can_assign(self):
373 return self.name not in ('true', 'false', 'none',
374 'True', 'False', 'None')
378 """Baseclass for literals."""
382 class Const(Literal):
383 """All constant values. The parser will return this node for simple
384 constants such as ``42`` or ``"foo"`` but it can be used to store more
385 complex values such as lists too. Only constants with a safe
386 representation (objects where ``eval(repr(x)) == x`` is true).
394 def from_untrusted(cls, value, lineno=None, environment=None):
395 """Return a const object if the value is representable as
396 constant value in the generated code, otherwise it will raise
397 an `Impossible` exception.
399 from compiler import has_safe_repr
400 if not has_safe_repr(value):
402 return cls(value, lineno=lineno, environment=environment)
405 class TemplateData(Literal):
406 """A constant template string."""
410 if self.environment.autoescape:
411 return Markup(self.data)
415 class Tuple(Literal):
416 """For loop unpacking and some other things like multiple arguments
417 for subscripts. Like for :class:`Name` `ctx` specifies if the tuple
418 is used for loading the names or storing.
420 fields = ('items', 'ctx')
423 return tuple(x.as_const() for x in self.items)
425 def can_assign(self):
426 for item in self.items:
427 if not item.can_assign():
433 """Any list literal such as ``[1, 2, 3]``"""
437 return [x.as_const() for x in self.items]
441 """Any dict literal such as ``{1: 2, 3: 4}``. The items must be a list of
447 return dict(x.as_const() for x in self.items)
451 """A key, value pair for dicts."""
452 fields = ('key', 'value')
455 return self.key.as_const(), self.value.as_const()
458 class Keyword(Helper):
459 """A key, value pair for keyword arguments where key is a string."""
460 fields = ('key', 'value')
463 return self.key, self.value.as_const()
466 class CondExpr(Expr):
467 """A conditional expression (inline if expression). (``{{
468 foo if bar else baz }}``)
470 fields = ('test', 'expr1', 'expr2')
473 if self.test.as_const():
474 return self.expr1.as_const()
476 # if we evaluate to an undefined object, we better do that at runtime
477 if self.expr2 is None:
480 return self.expr2.as_const()
484 """This node applies a filter on an expression. `name` is the name of
485 the filter, the rest of the fields are the same as for :class:`Call`.
487 If the `node` of a filter is `None` the contents of the last buffer are
488 filtered. Buffers are created by macros and filter blocks.
490 fields = ('node', 'name', 'args', 'kwargs', 'dyn_args', 'dyn_kwargs')
492 def as_const(self, obj=None):
493 if self.node is obj is None:
495 filter = self.environment.filters.get(self.name)
496 if filter is None or getattr(filter, 'contextfilter', False):
499 obj = self.node.as_const()
500 args = [x.as_const() for x in self.args]
501 if getattr(filter, 'environmentfilter', False):
502 args.insert(0, self.environment)
503 kwargs = dict(x.as_const() for x in self.kwargs)
504 if self.dyn_args is not None:
506 args.extend(self.dyn_args.as_const())
509 if self.dyn_kwargs is not None:
511 kwargs.update(self.dyn_kwargs.as_const())
515 return filter(obj, *args, **kwargs)
521 """Applies a test on an expression. `name` is the name of the test, the
522 rest of the fields are the same as for :class:`Call`.
524 fields = ('node', 'name', 'args', 'kwargs', 'dyn_args', 'dyn_kwargs')
528 """Calls an expression. `args` is a list of arguments, `kwargs` a list
529 of keyword arguments (list of :class:`Keyword` nodes), and `dyn_args`
530 and `dyn_kwargs` has to be either `None` or a node that is used as
531 node for dynamic positional (``*args``) or keyword (``**kwargs``)
534 fields = ('node', 'args', 'kwargs', 'dyn_args', 'dyn_kwargs')
537 obj = self.node.as_const()
539 # don't evaluate context functions
540 args = [x.as_const() for x in self.args]
541 if getattr(obj, 'contextfunction', False):
543 elif getattr(obj, 'environmentfunction', False):
544 args.insert(0, self.environment)
546 kwargs = dict(x.as_const() for x in self.kwargs)
547 if self.dyn_args is not None:
549 args.extend(self.dyn_args.as_const())
552 if self.dyn_kwargs is not None:
554 kwargs.update(self.dyn_kwargs.as_const())
558 return obj(*args, **kwargs)
564 """Get an attribute or item from an expression and prefer the item."""
565 fields = ('node', 'arg', 'ctx')
568 if self.ctx != 'load':
571 return self.environment.getitem(self.node.as_const(),
576 def can_assign(self):
581 """Get an attribute or item from an expression that is a ascii-only
582 bytestring and prefer the attribute.
584 fields = ('node', 'attr', 'ctx')
587 if self.ctx != 'load':
590 return self.environment.getattr(self.node.as_const(), arg)
594 def can_assign(self):
599 """Represents a slice object. This must only be used as argument for
602 fields = ('start', 'stop', 'step')
608 return obj.as_const()
609 return slice(const(self.start), const(self.stop), const(self.step))
613 """Concatenates the list of expressions provided after converting them to
619 return ''.join(unicode(x.as_const()) for x in self.nodes)
623 """Compares an expression with some other expressions. `ops` must be a
624 list of :class:`Operand`\s.
626 fields = ('expr', 'ops')
629 result = value = self.expr.as_const()
632 new_value = op.expr.as_const()
633 result = _cmpop_to_func[op.op](value, new_value)
640 class Operand(Helper):
641 """Holds an operator and an expression."""
642 fields = ('op', 'expr')
645 Operand.__doc__ += '\nThe following operators are available: ' + \
646 ', '.join(sorted('``%s``' % x for x in set(_binop_to_func) |
647 set(_uaop_to_func) | set(_cmpop_to_func)))
651 """Multiplies the left with the right node."""
656 """Divides the left by the right node."""
660 class FloorDiv(BinExpr):
661 """Divides the left by the right node and truncates conver the
662 result into an integer by truncating.
668 """Add the left to the right node."""
673 """Substract the right from the left node."""
678 """Left modulo right."""
683 """Left to the power of right."""
688 """Short circuited AND."""
692 return self.left.as_const() and self.right.as_const()
696 """Short circuited OR."""
700 return self.left.as_const() or self.right.as_const()
703 class Not(UnaryExpr):
704 """Negate the expression."""
708 class Neg(UnaryExpr):
709 """Make the expression negative."""
713 class Pos(UnaryExpr):
714 """Make the expression positive (noop for most expressions)"""
718 # Helpers for extensions
721 class EnvironmentAttribute(Expr):
722 """Loads an attribute from the environment object. This is useful for
723 extensions that want to call a callback stored on the environment.
728 class ExtensionAttribute(Expr):
729 """Returns the attribute of an extension bound to the environment.
730 The identifier is the identifier of the :class:`Extension`.
732 This node is usually constructed by calling the
733 :meth:`~jinja2.ext.Extension.attr` method on an extension.
735 fields = ('identifier', 'name')
738 class ImportedName(Expr):
739 """If created with an import name the import name is returned on node
740 access. For example ``ImportedName('cgi.escape')`` returns the `escape`
741 function from the cgi module on evaluation. Imports are optimized by the
742 compiler so there is no need to assign them to local variables.
744 fields = ('importname',)
747 class InternalName(Expr):
748 """An internal name in the compiler. You cannot create these nodes
749 yourself but the parser provides a
750 :meth:`~jinja2.parser.Parser.free_identifier` method that creates
751 a new identifier for you. This identifier is not available from the
752 template and is not threated specially by the compiler.
757 raise TypeError('Can\'t create internal names. Use the '
758 '`free_identifier` method on a parser.')
761 class MarkSafe(Expr):
762 """Mark the wrapped expression as safe (wrap it as `Markup`)."""
766 return Markup(self.expr.as_const())
769 class ContextReference(Expr):
770 """Returns the current template context."""
773 class Continue(Stmt):
774 """Continue a loop."""
781 # make sure nobody creates custom nodes
782 def _failing_new(*args, **kwargs):
783 raise TypeError('can\'t create custom node types')
784 NodeType.__new__ = staticmethod(_failing_new); del _failing_new