[Python-checkins] bpo-30637: Improve the docs of ast.parse regarding differences with compile() (GH-28459)

[pablogsal]

https://github.com/python/cpython/commit/e6d05a4092b4176a30d1d1596585df13c2ab676d
commit: e6d05a4092b4176a30d1d1596585df13c2ab676d
branch: main
author: Pablo Galindo Salgado <Pablogsal at gmail.com>
committer: pablogsal <Pablogsal at gmail.com>
date: 2021-09-19T23:44:51+01:00
summary:

bpo-30637: Improve the docs of ast.parse regarding differences with compile() (GH-28459)

files:
M Doc/library/ast.rst

diff --git a/Doc/library/ast.rst b/Doc/library/ast.rst
index 19e7bcc414b84..e21151bd4ef79 100644
--- a/Doc/library/ast.rst
+++ b/Doc/library/ast.rst
@@ -1917,6 +1917,19 @@ and classes for traversing abstract syntax trees:
    ``await`` as variable names.  The lowest supported version is
    ``(3, 4)``; the highest is ``sys.version_info[0:2]``.
 
+   If source contains a null character ('\0'), :exc:`ValueError` is raised.
+
+    .. warning::
+      Note that succesfully parsing souce code into an AST object doesn't
+      guarantee that the source code provided is valid Python code that can
+      be executed as the compilation step can raise further :exc:`SyntaxError`
+      exceptions. For instance, the source ``return 42`` generates a valid
+      AST node for a return statement, but it cannot be compiled alone (it needs
+      to be inside a function node).
+
+      In particular, :func:`ast.parse` won't do any scoping checks, which the
+      compilation step does.
+
    .. warning::
       It is possible to crash the Python interpreter with a
       sufficiently large/complex string due to stack depth limitations