From 4b6d17388f9a312bf5c8315150f7f71ff34abe7f Mon Sep 17 00:00:00 2001 From: sobolevn Date: Sun, 15 Jan 2023 14:30:11 +0300 Subject: [PATCH 1/6] gh-92788: Add docs for `ast.Module`, `ast.Expression`, and others --- Doc/library/ast.rst | 71 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) diff --git a/Doc/library/ast.rst b/Doc/library/ast.rst index 0811b3fa0e7842..f27d2fc11e5100 100644 --- a/Doc/library/ast.rst +++ b/Doc/library/ast.rst @@ -146,6 +146,77 @@ Node classes Snakes `__ project and all its contributors. +Root nodes +^^^^^^^^^^ + +.. class:: Module(body, type_ignores) + + A Python module. Body contains a list of module's statements. + + .. 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 expression. + + .. doctest:: + + >>> print(ast.dump(ast.parse('123', mode='eval'), indent=4)) + Expression( + body=Constant(value=123)) + + +.. class:: Interactive(body) + + A single Python interactive statement, just like in :ref:`tut-interac`. + + .. 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) + + Special type to represent old-style type comments for functions. + + Python versions prior to 3.6 used to annotate functions like this:: + + def sum_two_number(a, b): + # type: (int, int) -> int + return a + b + + .. 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())) + Literals ^^^^^^^^ From 7b5e468dab2ea47dc0b5c7f362f11997b96624f1 Mon Sep 17 00:00:00 2001 From: sobolevn Date: Mon, 16 Jan 2023 11:09:51 +0300 Subject: [PATCH 2/6] Address review --- Doc/library/ast.rst | 29 ++++++++++++++++++++++++++--- 1 file changed, 26 insertions(+), 3 deletions(-) diff --git a/Doc/library/ast.rst b/Doc/library/ast.rst index f27d2fc11e5100..9fcd44a8b5c11f 100644 --- a/Doc/library/ast.rst +++ b/Doc/library/ast.rst @@ -146,12 +146,19 @@ Node classes Snakes `__ project and all its contributors. + +.. _ast-root-nodes: + Root nodes ^^^^^^^^^^ .. class:: Module(body, type_ignores) - A Python module. Body contains a list of module's statements. + A Python module. + + *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:: @@ -169,6 +176,8 @@ Root nodes A single Python expression. + *body* is a single :ref:`ast-expressions` node. + .. doctest:: >>> print(ast.dump(ast.parse('123', mode='eval'), indent=4)) @@ -180,6 +189,8 @@ Root nodes A single Python interactive statement, just like in :ref:`tut-interac`. + *body* is a :class:`list` of :ref:`ast-statements` nodes. + .. doctest:: >>> print(ast.dump(ast.parse('x = 1; y = 2', mode='single'), indent=4)) @@ -197,14 +208,18 @@ Root nodes .. class:: FunctionType(argtypes, returns) - Special type to represent old-style type comments for functions. + Special type to represent old-style type comments for functions, + as Python versions prior to 3.5 didn't support :pep:`484` annotations. - Python versions prior to 3.6 used to annotate functions like this:: + 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:`ast-expressions` nodes. + *returns* is a single :ref:`ast-expressions` node. + .. doctest:: >>> print(ast.dump(ast.parse('(int, str) -> List[int]', mode='func_type'), indent=4)) @@ -217,6 +232,9 @@ Root nodes slice=Name(id='int', ctx=Load()), ctx=Load())) + .. versionadded:: 3.8 + + Literals ^^^^^^^^ @@ -415,6 +433,8 @@ Variables type_ignores=[]) +.. _ast-expressions: + Expressions ^^^^^^^^^^^ @@ -806,6 +826,9 @@ Comprehensions ifs=[], is_async=1)])) + +.. _ast-statements: + Statements ^^^^^^^^^^ From 40592bd172f850418591038223af4f9c6a93cd25 Mon Sep 17 00:00:00 2001 From: Nikita Sobolev Date: Mon, 16 Jan 2023 11:11:11 +0300 Subject: [PATCH 3/6] Update Doc/library/ast.rst Co-authored-by: C.A.M. Gerlach --- Doc/library/ast.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/ast.rst b/Doc/library/ast.rst index 9fcd44a8b5c11f..2be9effa90f186 100644 --- a/Doc/library/ast.rst +++ b/Doc/library/ast.rst @@ -187,7 +187,7 @@ Root nodes .. class:: Interactive(body) - A single Python interactive statement, just like in :ref:`tut-interac`. + A single Python interactive statement, like in :ref:`tut-interac`. *body* is a :class:`list` of :ref:`ast-statements` nodes. From a0a3a5fead36826da2355740ce304ae92a53524f Mon Sep 17 00:00:00 2001 From: Nikita Sobolev Date: Tue, 17 Jan 2023 09:53:48 +0300 Subject: [PATCH 4/6] Apply suggestions from code review Co-authored-by: C.A.M. Gerlach --- Doc/library/ast.rst | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/Doc/library/ast.rst b/Doc/library/ast.rst index 2be9effa90f186..04622dc7c789f6 100644 --- a/Doc/library/ast.rst +++ b/Doc/library/ast.rst @@ -157,7 +157,8 @@ Root nodes A Python module. *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, + + *type_ignores* is a :class:`list` of the module's type ignore comments; see :func:`ast.parse` for more details. .. doctest:: @@ -176,7 +177,8 @@ Root nodes A single Python expression. - *body* is a single :ref:`ast-expressions` node. + *body* is a single node, + one of the :ref:`expression types `. .. doctest:: @@ -187,9 +189,9 @@ Root nodes .. class:: Interactive(body) - A single Python interactive statement, like in :ref:`tut-interac`. + A single Python interactive line, like in :ref:`tut-interac`. - *body* is a :class:`list` of :ref:`ast-statements` nodes. + *body* is a :class:`list` of :ref:`statement nodes `. .. doctest:: @@ -208,7 +210,7 @@ Root nodes .. class:: FunctionType(argtypes, returns) - Special type to represent old-style type comments for functions, + A representation of an old-style type comments for functions, as Python versions prior to 3.5 didn't support :pep:`484` annotations. Such type comments would look like this:: @@ -217,8 +219,9 @@ Root nodes # type: (int, int) -> int return a + b - *argtypes* is a :class:`list` of :ref:`ast-expressions` nodes. - *returns* is a single :ref:`ast-expressions` node. + *argtypes* is a :class:`list` of :ref:`expression nodes `. + + *returns* is a single :ref:`expression node `. .. doctest:: From 65e7a83fcc384609a729efe98fac7c49040af9f1 Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Sun, 22 Jan 2023 20:28:32 -0600 Subject: [PATCH 5/6] Use correct terminology to describe ast.Interactive node --- Doc/library/ast.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/ast.rst b/Doc/library/ast.rst index 04622dc7c789f6..b90760ed2e65fe 100644 --- a/Doc/library/ast.rst +++ b/Doc/library/ast.rst @@ -189,7 +189,7 @@ Root nodes .. class:: Interactive(body) - A single Python interactive line, like in :ref:`tut-interac`. + A single interactive input, like in :ref:`tut-interac`. *body* is a :class:`list` of :ref:`statement nodes `. From ea49ee66a14273bc834492bbbe1cfc4ae9dae49d Mon Sep 17 00:00:00 2001 From: Nikita Sobolev Date: Mon, 6 Feb 2023 22:17:56 +0300 Subject: [PATCH 6/6] Apply suggestions from code review Co-authored-by: C.A.M. Gerlach --- Doc/library/ast.rst | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/Doc/library/ast.rst b/Doc/library/ast.rst index b90760ed2e65fe..4384f4996da540 100644 --- a/Doc/library/ast.rst +++ b/Doc/library/ast.rst @@ -154,7 +154,8 @@ Root nodes .. class:: Module(body, type_ignores) - A Python module. + A Python module, as with :ref:`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`. @@ -175,7 +176,8 @@ Root nodes .. class:: Expression(body) - A single Python expression. + A single Python :ref:`expression input `. + Node type generated by :func:`ast.parse` when *mode* is ``"eval"``. *body* is a single node, one of the :ref:`expression types `. @@ -189,7 +191,8 @@ Root nodes .. class:: Interactive(body) - A single interactive input, like in :ref:`tut-interac`. + A single :ref:`interactive input `, 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 `. @@ -212,6 +215,7 @@ Root nodes 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::