bpo-39999: Improve compatibility of the ast module. (GH-19056)

serhiy-storchaka · web-flow · commit bace59d8b8e3 · 2020-03-22T20:33:34.000+02:00
* Re-add removed classes Suite, slice, Param, AugLoad and AugStore.
* Add docstrings for dummy classes.
* Add docstrings for attribute aliases.
* Set __module__ to "ast" instead of "_ast".
diff --git a/Doc/whatsnew/3.9.rst b/Doc/whatsnew/3.9.rst
@@ -593,12 +593,19 @@ Deprecated
 
   (Contributed by Victor Stinner in :issue:`39353`.)
 
-* :mod:`ast` classes ``Index`` and ``ExtSlice`` are considered deprecated
+* :mod:`ast` classes ``slice``, ``Index`` and ``ExtSlice`` are considered deprecated
   and will be removed in future Python versions.  ``value`` itself should be
   used instead of ``Index(value)``.  ``Tuple(slices, Load())`` should be
   used instead of ``ExtSlice(slices)``.
   (Contributed by Serhiy Storchaka in :issue:`32892`.)
 
+* :mod:`ast` classes ``Suite``, ``Param``, ``AugLoad`` and ``AugStore``
+  are considered deprecated and will be removed in future Python versions.
+  They were not generated by the parser and not accepted by the code
+  generator in Python 3.
+  (Contributed by Batuhan Taskaya in :issue:`39639` and :issue:`39969`
+  and Serhiy Storchaka in :issue:`39988`.)
+
 * The :c:func:`PyEval_InitThreads` and :c:func:`PyEval_ThreadsInitialized`
   functions are now deprecated and will be removed in Python 3.11. Calling
   :c:func:`PyEval_InitThreads` now does nothing. The :term:`GIL` is initialized
@@ -704,11 +711,6 @@ Removed
   defining ``COUNT_ALLOCS`` macro.
   (Contributed by Victor Stinner in :issue:`39489`.)
 
-* The ``ast.Suite``, ``ast.Param``, ``ast.AugLoad`` and ``ast.AugStore``
-  node classes have been removed due to no longer being needed.
-  (Contributed by Batuhan Taskaya in :issue:`39639` and :issue:`39969`
-  and Serhiy Storchaka in :issue:`39988`.)
-
 
 Porting to Python 3.9
 =====================
diff --git a/Lib/ast.py b/Lib/ast.py
@@ -489,6 +489,7 @@ def generic_visit(self, node):
 # It will be removed in future.
 
 def _getter(self):
+    """Deprecated. Use value instead."""
     return self.value
 
 def _setter(self, value):
@@ -499,6 +500,9 @@ def _setter(self, value):
 
 class _ABC(type):
 
+    def __init__(cls, *args):
+        cls.__doc__ = """Deprecated AST node class. Use ast.Constant instead"""
+
     def __instancecheck__(cls, inst):
         if not isinstance(inst, Constant):
             return False
@@ -564,22 +568,40 @@ def __new__(cls, *args, **kwargs):
     type(...): 'Ellipsis',
 }
 
-class Index(AST):
+class slice(AST):
+    """Deprecated AST node class."""
+
+class Index(slice):
+    """Deprecated AST node class. Use the index value directly instead."""
     def __new__(cls, value, **kwargs):
         return value
 
-class ExtSlice(AST):
+class ExtSlice(slice):
+    """Deprecated AST node class. Use ast.Tuple instead."""
     def __new__(cls, dims=(), **kwargs):
         return Tuple(list(dims), Load(), **kwargs)
 
 def _dims_getter(self):
+    """Deprecated. Use elts instead."""
     return self.elts
 
 def _dims_setter(self, value):
     self.elts = value
 
 Tuple.dims = property(_dims_getter, _dims_setter)
 
+class Suite(mod):
+    """Deprecated AST node class.  Unused in Python 3."""
+
+class AugLoad(expr_context):
+    """Deprecated AST node class.  Unused in Python 3."""
+
+class AugStore(expr_context):
+    """Deprecated AST node class.  Unused in Python 3."""
+
+class Param(expr_context):
+    """Deprecated AST node class.  Unused in Python 3."""
+
 
 # Large float and imaginary literals get turned into infinities in the AST.
 # We unparse those infinities to INFSTR.
diff --git a/Lib/test/test_ast.py b/Lib/test/test_ast.py
@@ -283,7 +283,7 @@ def test_AST_objects(self):
             x.vararg
 
         with self.assertRaises(TypeError):
-            # "_ast.AST constructor takes 0 positional arguments"
+            # "ast.AST constructor takes 0 positional arguments"
             ast.AST(2)
 
     def test_AST_garbage_collection(self):
@@ -573,7 +573,7 @@ def test_invalid_sum(self):
         m = ast.Module([ast.Expr(ast.expr(**pos), **pos)], [])
         with self.assertRaises(TypeError) as cm:
             compile(m, "<test>", "exec")
-        self.assertIn("but got <_ast.expr", str(cm.exception))
+        self.assertIn("but got <ast.expr", str(cm.exception))
 
     def test_invalid_identifier(self):
         m = ast.Module([ast.Expr(ast.Name(42, ast.Load()))], [])
diff --git a/Misc/NEWS.d/next/Core and Builtins/2020-02-15-15-29-34.bpo-39639.3mqJjm.rst b/Misc/NEWS.d/next/Core and Builtins/2020-02-15-15-29-34.bpo-39639.3mqJjm.rst
diff --git a/Misc/NEWS.d/next/Library/2020-02-15-15-29-34.bpo-39639.3mqJjm.rst b/Misc/NEWS.d/next/Library/2020-02-15-15-29-34.bpo-39639.3mqJjm.rst
@@ -0,0 +1 @@
+Deprecated ``ast.Suite`` node class because it's no longer used. Patch by Batuhan Taskaya.
diff --git a/Misc/NEWS.d/next/Library/2020-03-15-17-56-48.bpo-39969.6snm0c.rst b/Misc/NEWS.d/next/Library/2020-03-15-17-56-48.bpo-39969.6snm0c.rst
@@ -1,2 +1,2 @@
-Remove ``ast.Param`` node class because it's no longer used. Patch by
+Deprecated ``ast.Param`` node class because it's no longer used. Patch by
 Batuhan Taskaya.
diff --git a/Misc/NEWS.d/next/Library/2020-03-17-09-35-00.bpo-39988.kXGl35.rst b/Misc/NEWS.d/next/Library/2020-03-17-09-35-00.bpo-39988.kXGl35.rst
@@ -1,2 +1,2 @@
-Removed ``ast.AugLoad`` and ``ast.AugStore`` node classes because they are
+Deprecated ``ast.AugLoad`` and ``ast.AugStore`` node classes because they are
 no longer used.
diff --git a/Misc/NEWS.d/next/Library/2020-03-18-11-50-25.bpo-39999.8aOXDT.rst b/Misc/NEWS.d/next/Library/2020-03-18-11-50-25.bpo-39999.8aOXDT.rst
@@ -0,0 +1,3 @@
+``__module__`` of the AST node classes is now set to "ast" instead of
+"_ast". Added docstrings for dummy AST node classes and deprecated
+attributes.
diff --git a/Parser/asdl_c.py b/Parser/asdl_c.py
@@ -774,7 +774,7 @@ def visitModule(self, mod):
 };
 
 static PyType_Spec AST_type_spec = {
-    "_ast.AST",
+    "ast.AST",
     sizeof(AST_object),
     0,
     Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC,
@@ -800,7 +800,7 @@ def visitModule(self, mod):
                     type, base,
                     astmodulestate_global->_fields, fnames,
                     astmodulestate_global->__module__,
-                    astmodulestate_global->_ast,
+                    astmodulestate_global->ast,
                     astmodulestate_global->__doc__, doc);
     Py_DECREF(fnames);
     return result;
@@ -1302,7 +1302,7 @@ def generate_module_def(f, mod):
         visitor_list.add(visitor)
 
     state_strings = {
-        "_ast",
+        "ast",
         "_fields",
         "__doc__",
         "__dict__",
diff --git a/Python/Python-ast.c b/Python/Python-ast.c

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	+Deprecated ``ast.Suite`` node class because it's no longer used. Patch by Batuhan Taskaya.
Original file line number	Diff line number	Diff line change
`@@ -1,2 +1,2 @@`
`1`		-Remove ``ast.Param`` node class because it's no longer used. Patch by
	`1`	+Deprecated ``ast.Param`` node class because it's no longer used. Patch by
`2`	`2`	`Batuhan Taskaya.`
Original file line number	Diff line number	Diff line change
`@@ -1,2 +1,2 @@`
`1`		-Removed ``ast.AugLoad`` and ``ast.AugStore`` node classes because they are
	`1`	+Deprecated ``ast.AugLoad`` and ``ast.AugStore`` node classes because they are
`2`	`2`	`no longer used.`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	+``__module__`` of the AST node classes is now set to "ast" instead of
	`2`	`+"_ast". Added docstrings for dummy AST node classes and deprecated`
	`3`	`+attributes.`