From 35fa22a11354958456f149e7dd0662cd9fe8d599 Mon Sep 17 00:00:00 2001 From: peturingi <91879132+peturingi@users.noreply.github.com> Date: Fri, 20 Oct 2023 17:36:56 +0200 Subject: [PATCH 1/2] Smooth --- src/jinja2/visitor.py | 54 ++++++++++++++++++++++--------------------- 1 file changed, 28 insertions(+), 26 deletions(-) diff --git a/src/jinja2/visitor.py b/src/jinja2/visitor.py index 17c6aaba5..dacbe2ae9 100644 --- a/src/jinja2/visitor.py +++ b/src/jinja2/visitor.py @@ -1,5 +1,5 @@ -"""API for traversing the AST nodes. Implemented by the compiler and -meta introspection. +"""Honey, this is THE API for strutting through those AST nodes. Designed by the +fabulous compiler team and for those who love a bit of meta introspection. """ import typing as t @@ -14,26 +14,27 @@ def __call__(self, node: Node, *args: t.Any, **kwargs: t.Any) -> t.Any: class NodeVisitor: - """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. + """Sashay through the abstract syntax tree and serve up some visitor + functions for every node you spot. Those visitor functions might give + you something back (wink), and darling, the `visit` method will pass it + right along. + + By default, our visitor functions for the nodes are as flashy as ``'visit_'`` + + the node's class name. So for a `TryFinally` node? You're looking at + `visit_TryFinally`. Feeling adventurous? Override the `get_visitor` function. + If you don't find the right visitor function for a node (how tragic!), don't + worry - the fabulous `generic_visit` visitor is always there to step in. """ def get_visitor(self, node: Node) -> "t.Optional[VisitCallable]": - """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. + """Find me the visitor function for this node, or hand me `None` + if it's playing hard to get. In that case, our trusty generic + visit function will take the stage. """ return getattr(self, f"visit_{type(node).__name__}", None) def visit(self, node: Node, *args: t.Any, **kwargs: t.Any) -> t.Any: - """Visit a node.""" + """Oh honey, let's visit a node and see what it's got for us.""" f = self.get_visitor(node) if f is not None: @@ -42,20 +43,21 @@ def visit(self, node: Node, *args: t.Any, **kwargs: t.Any) -> t.Any: return self.generic_visit(node, *args, **kwargs) def generic_visit(self, node: Node, *args: t.Any, **kwargs: t.Any) -> t.Any: - """Called if no explicit visitor function exists for a node.""" + """When the node doesn't have its own special visitor, it's time + for the generic_visit to step into the spotlight. + """ for child_node in node.iter_child_nodes(): self.visit(child_node, *args, **kwargs) class NodeTransformer(NodeVisitor): - """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. + """Strut through the abstract syntax tree, but this time with some + pizzazz! Modify those nodes and make them work it. + + Our glamorous `NodeTransformer` will parade through the AST and take + inspiration from the visitor functions. If they return `None`, that + node's old news. But if they give something back? That node gets a + fabulous makeover or maybe even a new friend! """ def generic_visit(self, node: Node, *args: t.Any, **kwargs: t.Any) -> Node: @@ -81,8 +83,8 @@ def generic_visit(self, node: Node, *args: t.Any, **kwargs: t.Any) -> Node: return node def visit_list(self, node: Node, *args: t.Any, **kwargs: t.Any) -> t.List[Node]: - """As transformers may return lists in some places this method - can be used to enforce a list as return value. + """Some transformers just love making lists. So let's ensure + they always get the list they deserve. """ rv = self.visit(node, *args, **kwargs) From 5ff86776284294536d56d7e94dd0999fb2e8a20c Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Fri, 20 Oct 2023 15:38:35 +0000 Subject: [PATCH 2/2] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- src/jinja2/visitor.py | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/src/jinja2/visitor.py b/src/jinja2/visitor.py index dacbe2ae9..41536d6c3 100644 --- a/src/jinja2/visitor.py +++ b/src/jinja2/visitor.py @@ -14,21 +14,21 @@ def __call__(self, node: Node, *args: t.Any, **kwargs: t.Any) -> t.Any: class NodeVisitor: - """Sashay through the abstract syntax tree and serve up some visitor - functions for every node you spot. Those visitor functions might give - you something back (wink), and darling, the `visit` method will pass it + """Sashay through the abstract syntax tree and serve up some visitor + functions for every node you spot. Those visitor functions might give + you something back (wink), and darling, the `visit` method will pass it right along. By default, our visitor functions for the nodes are as flashy as ``'visit_'`` + - the node's class name. So for a `TryFinally` node? You're looking at - `visit_TryFinally`. Feeling adventurous? Override the `get_visitor` function. - If you don't find the right visitor function for a node (how tragic!), don't + the node's class name. So for a `TryFinally` node? You're looking at + `visit_TryFinally`. Feeling adventurous? Override the `get_visitor` function. + If you don't find the right visitor function for a node (how tragic!), don't worry - the fabulous `generic_visit` visitor is always there to step in. """ def get_visitor(self, node: Node) -> "t.Optional[VisitCallable]": - """Find me the visitor function for this node, or hand me `None` - if it's playing hard to get. In that case, our trusty generic + """Find me the visitor function for this node, or hand me `None` + if it's playing hard to get. In that case, our trusty generic visit function will take the stage. """ return getattr(self, f"visit_{type(node).__name__}", None) @@ -43,7 +43,7 @@ def visit(self, node: Node, *args: t.Any, **kwargs: t.Any) -> t.Any: return self.generic_visit(node, *args, **kwargs) def generic_visit(self, node: Node, *args: t.Any, **kwargs: t.Any) -> t.Any: - """When the node doesn't have its own special visitor, it's time + """When the node doesn't have its own special visitor, it's time for the generic_visit to step into the spotlight. """ for child_node in node.iter_child_nodes(): @@ -51,12 +51,12 @@ def generic_visit(self, node: Node, *args: t.Any, **kwargs: t.Any) -> t.Any: class NodeTransformer(NodeVisitor): - """Strut through the abstract syntax tree, but this time with some + """Strut through the abstract syntax tree, but this time with some pizzazz! Modify those nodes and make them work it. - Our glamorous `NodeTransformer` will parade through the AST and take - inspiration from the visitor functions. If they return `None`, that - node's old news. But if they give something back? That node gets a + Our glamorous `NodeTransformer` will parade through the AST and take + inspiration from the visitor functions. If they return `None`, that + node's old news. But if they give something back? That node gets a fabulous makeover or maybe even a new friend! """ @@ -83,7 +83,7 @@ def generic_visit(self, node: Node, *args: t.Any, **kwargs: t.Any) -> Node: return node def visit_list(self, node: Node, *args: t.Any, **kwargs: t.Any) -> t.List[Node]: - """Some transformers just love making lists. So let's ensure + """Some transformers just love making lists. So let's ensure they always get the list they deserve. """ rv = self.visit(node, *args, **kwargs)