From: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com>
Date: Sun, 12 Jan 2020 20:44:22 +0000 (-0800)
Subject: bpo-3530: Add advice on when to correctly use fix_missing_locations in the AST docs... 
X-Git-Tag: v3.7.7rc1~94
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=e222b4c69f99953a14ded52497a9909e34fc3893;p=thirdparty%2FPython%2Fcpython.git

bpo-3530: Add advice on when to correctly use fix_missing_locations in the AST docs (GH-17172)


Co-authored-by: Pablo Galindo <Pablogsal@gmail.com>
(cherry picked from commit 6680f4a9f5d15ab82b2ab6266c6f917cb78c919a)

Co-authored-by: Batuhan Taşkaya <47358913+isidentical@users.noreply.github.com>
---

diff --git a/Doc/library/ast.rst b/Doc/library/ast.rst
index 699ad0456a02..6d6ae6de78a0 100644
--- a/Doc/library/ast.rst
+++ b/Doc/library/ast.rst
@@ -240,7 +240,7 @@ and classes for traversing abstract syntax trees:
       class RewriteName(NodeTransformer):
 
           def visit_Name(self, node):
-              return copy_location(Subscript(
+              return Subscript(
                   value=Name(id='data', ctx=Load()),
                   slice=Index(value=Str(s=node.id)),
                   ctx=node.ctx
@@ -254,6 +254,14 @@ and classes for traversing abstract syntax trees:
    statement nodes), the visitor may also return a list of nodes rather than
    just a single node.
 
+   If :class:`NodeTransformer` introduces new nodes (that weren't part of
+   original tree) without giving them location information (such as
+   :attr:`lineno`), :func:`fix_missing_locations` should be called with
+   the new sub-tree to recalculate the location information::
+
+      tree = ast.parse('foo', mode='eval')
+      new_tree = fix_missing_locations(RewriteName().visit(tree))
+
    Usually you use the transformer like this::
 
       node = YourTransformer().visit(node)
diff --git a/Misc/NEWS.d/next/Documentation/2019-11-17-11-53-10.bpo-3530.8zFUMc.rst b/Misc/NEWS.d/next/Documentation/2019-11-17-11-53-10.bpo-3530.8zFUMc.rst
new file mode 100644
index 000000000000..65f1a6d156a1
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2019-11-17-11-53-10.bpo-3530.8zFUMc.rst
@@ -0,0 +1,2 @@
+In the :mod:`ast` module documentation, fix a misleading ``NodeTransformer`` example and add
+advice on when to use the ``fix_missing_locations`` function.