jinja2.visitor
API for traversing the AST nodes. Implemented by the compiler and meta introspection.
1"""API for traversing the AST nodes. Implemented by the compiler and 2meta introspection. 3""" 4 5import typing as t 6 7from .nodes import Node 8 9if t.TYPE_CHECKING: 10 import typing_extensions as te 11 12 class VisitCallable(te.Protocol): 13 def __call__(self, node: Node, *args: t.Any, **kwargs: t.Any) -> t.Any: ... 14 15 16class NodeVisitor: 17 """Walks the abstract syntax tree and call visitor functions for every 18 node found. The visitor functions may return values which will be 19 forwarded by the `visit` method. 20 21 Per default the visitor functions for the nodes are ``'visit_'`` + 22 class name of the node. So a `TryFinally` node visit function would 23 be `visit_TryFinally`. This behavior can be changed by overriding 24 the `get_visitor` function. If no visitor function exists for a node 25 (return value `None`) the `generic_visit` visitor is used instead. 26 """ 27 28 def get_visitor(self, node: Node) -> "t.Optional[VisitCallable]": 29 """Return the visitor function for this node or `None` if no visitor 30 exists for this node. In that case the generic visit function is 31 used instead. 32 """ 33 return getattr(self, f"visit_{type(node).__name__}", None) 34 35 def visit(self, node: Node, *args: t.Any, **kwargs: t.Any) -> t.Any: 36 """Visit a node.""" 37 f = self.get_visitor(node) 38 39 if f is not None: 40 return f(node, *args, **kwargs) 41 42 return self.generic_visit(node, *args, **kwargs) 43 44 def generic_visit(self, node: Node, *args: t.Any, **kwargs: t.Any) -> t.Any: 45 """Called if no explicit visitor function exists for a node.""" 46 for child_node in node.iter_child_nodes(): 47 self.visit(child_node, *args, **kwargs) 48 49 50class NodeTransformer(NodeVisitor): 51 """Walks the abstract syntax tree and allows modifications of nodes. 52 53 The `NodeTransformer` will walk the AST and use the return value of the 54 visitor functions to replace or remove the old node. If the return 55 value of the visitor function is `None` the node will be removed 56 from the previous location otherwise it's replaced with the return 57 value. The return value may be the original node in which case no 58 replacement takes place. 59 """ 60 61 def generic_visit(self, node: Node, *args: t.Any, **kwargs: t.Any) -> Node: 62 for field, old_value in node.iter_fields(): 63 if isinstance(old_value, list): 64 new_values = [] 65 for value in old_value: 66 if isinstance(value, Node): 67 value = self.visit(value, *args, **kwargs) 68 if value is None: 69 continue 70 elif not isinstance(value, Node): 71 new_values.extend(value) 72 continue 73 new_values.append(value) 74 old_value[:] = new_values 75 elif isinstance(old_value, Node): 76 new_node = self.visit(old_value, *args, **kwargs) 77 if new_node is None: 78 delattr(node, field) 79 else: 80 setattr(node, field, new_node) 81 return node 82 83 def visit_list(self, node: Node, *args: t.Any, **kwargs: t.Any) -> t.List[Node]: 84 """As transformers may return lists in some places this method 85 can be used to enforce a list as return value. 86 """ 87 rv = self.visit(node, *args, **kwargs) 88 89 if not isinstance(rv, list): 90 return [rv] 91 92 return rv
17class NodeVisitor: 18 """Walks the abstract syntax tree and call visitor functions for every 19 node found. The visitor functions may return values which will be 20 forwarded by the `visit` method. 21 22 Per default the visitor functions for the nodes are ``'visit_'`` + 23 class name of the node. So a `TryFinally` node visit function would 24 be `visit_TryFinally`. This behavior can be changed by overriding 25 the `get_visitor` function. If no visitor function exists for a node 26 (return value `None`) the `generic_visit` visitor is used instead. 27 """ 28 29 def get_visitor(self, node: Node) -> "t.Optional[VisitCallable]": 30 """Return the visitor function for this node or `None` if no visitor 31 exists for this node. In that case the generic visit function is 32 used instead. 33 """ 34 return getattr(self, f"visit_{type(node).__name__}", None) 35 36 def visit(self, node: Node, *args: t.Any, **kwargs: t.Any) -> t.Any: 37 """Visit a node.""" 38 f = self.get_visitor(node) 39 40 if f is not None: 41 return f(node, *args, **kwargs) 42 43 return self.generic_visit(node, *args, **kwargs) 44 45 def generic_visit(self, node: Node, *args: t.Any, **kwargs: t.Any) -> t.Any: 46 """Called if no explicit visitor function exists for a node.""" 47 for child_node in node.iter_child_nodes(): 48 self.visit(child_node, *args, **kwargs)
Walks the abstract syntax tree and call visitor functions for every
node found. The visitor functions may return values which will be
forwarded by the visit
method.
Per default the visitor functions for the nodes are 'visit_'
+
class name of the node. So a TryFinally
node visit function would
be visit_TryFinally
. This behavior can be changed by overriding
the get_visitor
function. If no visitor function exists for a node
(return value None
) the generic_visit
visitor is used instead.
29 def get_visitor(self, node: Node) -> "t.Optional[VisitCallable]": 30 """Return the visitor function for this node or `None` if no visitor 31 exists for this node. In that case the generic visit function is 32 used instead. 33 """ 34 return getattr(self, f"visit_{type(node).__name__}", None)
Return the visitor function for this node or None
if no visitor
exists for this node. In that case the generic visit function is
used instead.
36 def visit(self, node: Node, *args: t.Any, **kwargs: t.Any) -> t.Any: 37 """Visit a node.""" 38 f = self.get_visitor(node) 39 40 if f is not None: 41 return f(node, *args, **kwargs) 42 43 return self.generic_visit(node, *args, **kwargs)
Visit a node.
51class NodeTransformer(NodeVisitor): 52 """Walks the abstract syntax tree and allows modifications of nodes. 53 54 The `NodeTransformer` will walk the AST and use the return value of the 55 visitor functions to replace or remove the old node. If the return 56 value of the visitor function is `None` the node will be removed 57 from the previous location otherwise it's replaced with the return 58 value. The return value may be the original node in which case no 59 replacement takes place. 60 """ 61 62 def generic_visit(self, node: Node, *args: t.Any, **kwargs: t.Any) -> Node: 63 for field, old_value in node.iter_fields(): 64 if isinstance(old_value, list): 65 new_values = [] 66 for value in old_value: 67 if isinstance(value, Node): 68 value = self.visit(value, *args, **kwargs) 69 if value is None: 70 continue 71 elif not isinstance(value, Node): 72 new_values.extend(value) 73 continue 74 new_values.append(value) 75 old_value[:] = new_values 76 elif isinstance(old_value, Node): 77 new_node = self.visit(old_value, *args, **kwargs) 78 if new_node is None: 79 delattr(node, field) 80 else: 81 setattr(node, field, new_node) 82 return node 83 84 def visit_list(self, node: Node, *args: t.Any, **kwargs: t.Any) -> t.List[Node]: 85 """As transformers may return lists in some places this method 86 can be used to enforce a list as return value. 87 """ 88 rv = self.visit(node, *args, **kwargs) 89 90 if not isinstance(rv, list): 91 return [rv] 92 93 return rv
Walks the abstract syntax tree and allows modifications of nodes.
The NodeTransformer
will walk the AST and use the return value of the
visitor functions to replace or remove the old node. If the return
value of the visitor function is None
the node will be removed
from the previous location otherwise it's replaced with the return
value. The return value may be the original node in which case no
replacement takes place.
62 def generic_visit(self, node: Node, *args: t.Any, **kwargs: t.Any) -> Node: 63 for field, old_value in node.iter_fields(): 64 if isinstance(old_value, list): 65 new_values = [] 66 for value in old_value: 67 if isinstance(value, Node): 68 value = self.visit(value, *args, **kwargs) 69 if value is None: 70 continue 71 elif not isinstance(value, Node): 72 new_values.extend(value) 73 continue 74 new_values.append(value) 75 old_value[:] = new_values 76 elif isinstance(old_value, Node): 77 new_node = self.visit(old_value, *args, **kwargs) 78 if new_node is None: 79 delattr(node, field) 80 else: 81 setattr(node, field, new_node) 82 return node
Called if no explicit visitor function exists for a node.
84 def visit_list(self, node: Node, *args: t.Any, **kwargs: t.Any) -> t.List[Node]: 85 """As transformers may return lists in some places this method 86 can be used to enforce a list as return value. 87 """ 88 rv = self.visit(node, *args, **kwargs) 89 90 if not isinstance(rv, list): 91 return [rv] 92 93 return rv
As transformers may return lists in some places this method can be used to enforce a list as return value.