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: (c) 2010 by the Jinja Team.
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. If the type is a tuple,
150 the check is performed for any of the tuple items.
152 for child in self.iter_child_nodes():
153 if isinstance(child, node_type):
155 for result in child.find_all(node_type):
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.
166 node = todo.popleft()
167 if 'ctx' in node.fields:
169 todo.extend(node.iter_child_nodes())
172 def set_lineno(self, lineno, override=False):
173 """Set the line numbers of the node and children."""
176 node = todo.popleft()
177 if 'lineno' in node.attributes:
178 if node.lineno is None or override:
180 todo.extend(node.iter_child_nodes())
183 def set_environment(self, environment):
184 """Set the environment for all nodes."""
187 node = todo.popleft()
188 node.environment = environment
189 todo.extend(node.iter_child_nodes())
192 def __eq__(self, other):
193 return type(self) is type(other) and \
194 tuple(self.iter_fields()) == tuple(other.iter_fields())
196 def __ne__(self, other):
197 return not self.__eq__(other)
201 self.__class__.__name__,
202 ', '.join('%s=%r' % (arg, getattr(self, arg, None)) for
208 """Base node for all statements."""
213 """Nodes that exist in a specific context only."""
217 class Template(Node):
218 """Node that represents a template. This must be the outermost node that
219 is passed to the compiler.
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.
232 """Represents an extends statement."""
233 fields = ('template',)
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.
242 For filtered nodes an expression can be stored as `test`, otherwise `None`.
244 fields = ('target', 'iter', 'body', 'else_', 'test', 'recursive')
248 """If `test` is true, `body` is rendered, else `else_`."""
249 fields = ('test', 'body', 'else_')
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.
257 fields = ('name', 'args', 'defaults', 'body')
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.
264 fields = ('call', 'args', 'defaults', 'body')
267 class FilterBlock(Stmt):
268 """Node for filter sections."""
269 fields = ('body', 'filter')
273 """A node that represents a block."""
274 fields = ('name', 'body', 'scoped')
278 """A node that represents the include tag."""
279 fields = ('template', 'with_context', 'ignore_missing')
283 """A node that represents the import tag."""
284 fields = ('template', 'target', 'with_context')
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.
296 The list of names may contain tuples if aliases are wanted.
298 fields = ('template', 'names', 'with_context')
301 class ExprStmt(Stmt):
302 """A statement that evaluates an expression and discards the result."""
307 """Assigns an expression to a target."""
308 fields = ('target', 'node')
312 """Baseclass for all expressions."""
316 """Return the value of the expression as constant or raise
317 :exc:`Impossible` if this was not possible:
319 >>> Add(Const(23), Const(42)).as_const()
321 >>> Add(Const(23), Name('var', 'load')).as_const()
322 Traceback (most recent call last):
326 This requires the `environment` attribute of all nodes to be
327 set to the environment that created the nodes.
331 def can_assign(self):
332 """Check if it's possible to assign something to this node."""
337 """Baseclass for all binary expressions."""
338 fields = ('left', 'right')
343 f = _binop_to_func[self.operator]
345 return f(self.left.as_const(), self.right.as_const())
350 class UnaryExpr(Expr):
351 """Baseclass for all unary expressions."""
357 f = _uaop_to_func[self.operator]
359 return f(self.node.as_const())
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:
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.
372 fields = ('name', 'ctx')
374 def can_assign(self):
375 return self.name not in ('true', 'false', 'none',
376 'True', 'False', 'None')
380 """Baseclass for literals."""
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).
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.
401 from compiler import has_safe_repr
402 if not has_safe_repr(value):
404 return cls(value, lineno=lineno, environment=environment)
407 class TemplateData(Literal):
408 """A constant template string."""
412 if self.environment.autoescape:
413 return Markup(self.data)
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.
422 fields = ('items', 'ctx')
425 return tuple(x.as_const() for x in self.items)
427 def can_assign(self):
428 for item in self.items:
429 if not item.can_assign():
435 """Any list literal such as ``[1, 2, 3]``"""
439 return [x.as_const() for x in self.items]
443 """Any dict literal such as ``{1: 2, 3: 4}``. The items must be a list of
449 return dict(x.as_const() for x in self.items)
453 """A key, value pair for dicts."""
454 fields = ('key', 'value')
457 return self.key.as_const(), self.value.as_const()
460 class Keyword(Helper):
461 """A key, value pair for keyword arguments where key is a string."""
462 fields = ('key', 'value')
465 return self.key, self.value.as_const()
468 class CondExpr(Expr):
469 """A conditional expression (inline if expression). (``{{
470 foo if bar else baz }}``)
472 fields = ('test', 'expr1', 'expr2')
475 if self.test.as_const():
476 return self.expr1.as_const()
478 # if we evaluate to an undefined object, we better do that at runtime
479 if self.expr2 is None:
482 return self.expr2.as_const()
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`.
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.
492 fields = ('node', 'name', 'args', 'kwargs', 'dyn_args', 'dyn_kwargs')
494 def as_const(self, obj=None):
495 if self.node is obj is None:
497 # we have to be careful here because we call filter_ below.
498 # if this variable would be called filter, 2to3 would wrap the
499 # call in a list beause it is assuming we are talking about the
500 # builtin filter function here which no longer returns a list in
501 # python 3. because of that, do not rename filter_ to filter!
502 filter_ = self.environment.filters.get(self.name)
503 if filter_ is None or getattr(filter_, 'contextfilter', False):
506 obj = self.node.as_const()
507 args = [x.as_const() for x in self.args]
508 if getattr(filter_, 'environmentfilter', False):
509 args.insert(0, self.environment)
510 kwargs = dict(x.as_const() for x in self.kwargs)
511 if self.dyn_args is not None:
513 args.extend(self.dyn_args.as_const())
516 if self.dyn_kwargs is not None:
518 kwargs.update(self.dyn_kwargs.as_const())
522 return filter_(obj, *args, **kwargs)
528 """Applies a test on an expression. `name` is the name of the test, the
529 rest of the fields are the same as for :class:`Call`.
531 fields = ('node', 'name', 'args', 'kwargs', 'dyn_args', 'dyn_kwargs')
535 """Calls an expression. `args` is a list of arguments, `kwargs` a list
536 of keyword arguments (list of :class:`Keyword` nodes), and `dyn_args`
537 and `dyn_kwargs` has to be either `None` or a node that is used as
538 node for dynamic positional (``*args``) or keyword (``**kwargs``)
541 fields = ('node', 'args', 'kwargs', 'dyn_args', 'dyn_kwargs')
544 obj = self.node.as_const()
546 # don't evaluate context functions
547 args = [x.as_const() for x in self.args]
548 if getattr(obj, 'contextfunction', False):
550 elif getattr(obj, 'environmentfunction', False):
551 args.insert(0, self.environment)
553 kwargs = dict(x.as_const() for x in self.kwargs)
554 if self.dyn_args is not None:
556 args.extend(self.dyn_args.as_const())
559 if self.dyn_kwargs is not None:
561 kwargs.update(self.dyn_kwargs.as_const())
565 return obj(*args, **kwargs)
571 """Get an attribute or item from an expression and prefer the item."""
572 fields = ('node', 'arg', 'ctx')
575 if self.ctx != 'load':
578 return self.environment.getitem(self.node.as_const(),
583 def can_assign(self):
588 """Get an attribute or item from an expression that is a ascii-only
589 bytestring and prefer the attribute.
591 fields = ('node', 'attr', 'ctx')
594 if self.ctx != 'load':
597 return self.environment.getattr(self.node.as_const(), arg)
601 def can_assign(self):
606 """Represents a slice object. This must only be used as argument for
609 fields = ('start', 'stop', 'step')
615 return obj.as_const()
616 return slice(const(self.start), const(self.stop), const(self.step))
620 """Concatenates the list of expressions provided after converting them to
626 return ''.join(unicode(x.as_const()) for x in self.nodes)
630 """Compares an expression with some other expressions. `ops` must be a
631 list of :class:`Operand`\s.
633 fields = ('expr', 'ops')
636 result = value = self.expr.as_const()
639 new_value = op.expr.as_const()
640 result = _cmpop_to_func[op.op](value, new_value)
647 class Operand(Helper):
648 """Holds an operator and an expression."""
649 fields = ('op', 'expr')
652 Operand.__doc__ += '\nThe following operators are available: ' + \
653 ', '.join(sorted('``%s``' % x for x in set(_binop_to_func) |
654 set(_uaop_to_func) | set(_cmpop_to_func)))
658 """Multiplies the left with the right node."""
663 """Divides the left by the right node."""
667 class FloorDiv(BinExpr):
668 """Divides the left by the right node and truncates conver the
669 result into an integer by truncating.
675 """Add the left to the right node."""
680 """Substract the right from the left node."""
685 """Left modulo right."""
690 """Left to the power of right."""
695 """Short circuited AND."""
699 return self.left.as_const() and self.right.as_const()
703 """Short circuited OR."""
707 return self.left.as_const() or self.right.as_const()
710 class Not(UnaryExpr):
711 """Negate the expression."""
715 class Neg(UnaryExpr):
716 """Make the expression negative."""
720 class Pos(UnaryExpr):
721 """Make the expression positive (noop for most expressions)"""
725 # Helpers for extensions
728 class EnvironmentAttribute(Expr):
729 """Loads an attribute from the environment object. This is useful for
730 extensions that want to call a callback stored on the environment.
735 class ExtensionAttribute(Expr):
736 """Returns the attribute of an extension bound to the environment.
737 The identifier is the identifier of the :class:`Extension`.
739 This node is usually constructed by calling the
740 :meth:`~jinja2.ext.Extension.attr` method on an extension.
742 fields = ('identifier', 'name')
745 class ImportedName(Expr):
746 """If created with an import name the import name is returned on node
747 access. For example ``ImportedName('cgi.escape')`` returns the `escape`
748 function from the cgi module on evaluation. Imports are optimized by the
749 compiler so there is no need to assign them to local variables.
751 fields = ('importname',)
754 class InternalName(Expr):
755 """An internal name in the compiler. You cannot create these nodes
756 yourself but the parser provides a
757 :meth:`~jinja2.parser.Parser.free_identifier` method that creates
758 a new identifier for you. This identifier is not available from the
759 template and is not threated specially by the compiler.
764 raise TypeError('Can\'t create internal names. Use the '
765 '`free_identifier` method on a parser.')
768 class MarkSafe(Expr):
769 """Mark the wrapped expression as safe (wrap it as `Markup`)."""
773 return Markup(self.expr.as_const())
776 class ContextReference(Expr):
777 """Returns the current template context."""
780 class Continue(Stmt):
781 """Continue a loop."""
789 """An artificial scope."""
793 # make sure nobody creates custom nodes
794 def _failing_new(*args, **kwargs):
795 raise TypeError('can\'t create custom node types')
796 NodeType.__new__ = staticmethod(_failing_new); del _failing_new