[3.11] gh-92788: Add docs for `ast.Module`, `ast.Expression`, and others (GH-101055...

gh-92788: Add docs for `ast.Module`, `ast.Expression`, and others (GH-101055)
(cherry picked from commit 33608fd67df8b1033519f808441ee00289e2dac0)

Co-authored-by: Nikita Sobolev <mail@sobolevn.me>

diff --git a/Doc/library/ast.rst b/Doc/library/ast.rst
index c92826621ff558a3c56cd0e2ed713f6495d6f2f8..d136f016b9b17a67dd2a8ac3846cd4af49c69a26 100644 (file)
--- a/Doc/library/ast.rst
+++ b/Doc/library/ast.rst
@@ -146,6 +146,102 @@ Node classes
     Snakes <https://greentreesnakes.readthedocs.io/en/latest/>`__ project and
     all its contributors.
 
+
+.. _ast-root-nodes:
+
+Root nodes
+^^^^^^^^^^
+
+.. class:: Module(body, type_ignores)
+
+   A Python module, as with :ref:`file input <file-input>`.
+   Node type generated by :func:`ast.parse` in the default ``"exec"`` *mode*.
+
+   *body* is a :class:`list` of the module's :ref:`ast-statements`.
+
+   *type_ignores* is a :class:`list` of the module's type ignore comments;
+   see :func:`ast.parse` for more details.
+
+   .. doctest::
+
+        >>> print(ast.dump(ast.parse('x = 1'), indent=4))
+        Module(
+            body=[
+                Assign(
+                    targets=[
+                        Name(id='x', ctx=Store())],
+                    value=Constant(value=1))],
+            type_ignores=[])
+
+
+.. class:: Expression(body)
+
+   A single Python :ref:`expression input <expression-input>`.
+   Node type generated by :func:`ast.parse` when *mode* is ``"eval"``.
+
+   *body* is a single node,
+   one of the :ref:`expression types <ast-expressions>`.
+
+   .. doctest::
+
+        >>> print(ast.dump(ast.parse('123', mode='eval'), indent=4))
+        Expression(
+            body=Constant(value=123))
+
+
+.. class:: Interactive(body)
+
+   A single :ref:`interactive input <interactive>`, like in :ref:`tut-interac`.
+   Node type generated by :func:`ast.parse` when *mode* is ``"single"``.
+
+   *body* is a :class:`list` of :ref:`statement nodes <ast-statements>`.
+
+   .. doctest::
+
+        >>> print(ast.dump(ast.parse('x = 1; y = 2', mode='single'), indent=4))
+        Interactive(
+            body=[
+                Assign(
+                    targets=[
+                        Name(id='x', ctx=Store())],
+                    value=Constant(value=1)),
+                Assign(
+                    targets=[
+                        Name(id='y', ctx=Store())],
+                    value=Constant(value=2))])
+
+
+.. class:: FunctionType(argtypes, returns)
+
+   A representation of an old-style type comments for functions,
+   as Python versions prior to 3.5 didn't support :pep:`484` annotations.
+   Node type generated by :func:`ast.parse` when *mode* is ``"func_type"``.
+
+   Such type comments would look like this::
+
+       def sum_two_number(a, b):
+           # type: (int, int) -> int
+           return a + b
+
+   *argtypes* is a :class:`list` of :ref:`expression nodes <ast-expressions>`.
+
+   *returns* is a single :ref:`expression node <ast-expressions>`.
+
+   .. doctest::
+
+        >>> print(ast.dump(ast.parse('(int, str) -> List[int]', mode='func_type'), indent=4))
+        FunctionType(
+            argtypes=[
+                Name(id='int', ctx=Load()),
+                Name(id='str', ctx=Load())],
+            returns=Subscript(
+                value=Name(id='List', ctx=Load()),
+                slice=Name(id='int', ctx=Load()),
+                ctx=Load()))
+
+   .. versionadded:: 3.8
+
+
 Literals
 ^^^^^^^^
 
@@ -344,6 +440,8 @@ Variables
             type_ignores=[])
 
 
+.. _ast-expressions:
+
 Expressions
 ^^^^^^^^^^^
 
@@ -735,6 +833,9 @@ Comprehensions
                         ifs=[],
                         is_async=1)]))
 
+
+.. _ast-statements:
+
 Statements
 ^^^^^^^^^^