annotations: expand documentation on "simple" assignment targets (#120535)

This behavior is rather surprising and it was not clearly specified.

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>

diff --git a/Doc/library/ast.rst b/Doc/library/ast.rst
index 9ee56b92431b576a3542d80955635ff763a8330c..f7e8afa7000392deb29194e0bc8160204c91e166 100644 (file)
--- a/Doc/library/ast.rst
+++ b/Doc/library/ast.rst
@@ -891,9 +891,13 @@ Statements
    An assignment with a type annotation. ``target`` is a single node and can
    be a :class:`Name`, a :class:`Attribute` or a :class:`Subscript`.
    ``annotation`` is the annotation, such as a :class:`Constant` or :class:`Name`
-   node. ``value`` is a single optional node. ``simple`` is a boolean integer
-   set to True for a :class:`Name` node in ``target`` that do not appear in
-   between parenthesis and are hence pure names and not expressions.
+   node. ``value`` is a single optional node.
+
+   ``simple`` is always either 0 (indicating a "complex" target) or 1
+   (indicating a "simple" target). A "simple" target consists solely of a
+   :class:`Name` node that does not appear between parentheses; all other
+   targets are considered complex. Only simple targets appear in
+   the :attr:`__annotations__` dictionary of modules and classes.
 
    .. doctest::
 

diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst
index a253482156d3b4bf35a12d66827db622c8eef2d4..4f6c0c63ae42beb881fa9432d98ac4d15c704021 100644 (file)
--- a/Doc/reference/simple_stmts.rst
+++ b/Doc/reference/simple_stmts.rst
@@ -333,7 +333,9 @@ statement, of a variable or attribute annotation and an optional assignment stat
 
 The difference from normal :ref:`assignment` is that only a single target is allowed.
 
-For simple names as assignment targets, if in class or module scope,
+The assignment target is considered "simple" if it consists of a single
+name that is not enclosed in parentheses.
+For simple assignment targets, if in class or module scope,
 the annotations are evaluated and stored in a special class or module
 attribute :attr:`__annotations__`
 that is a dictionary mapping from variable names (mangled if private) to
@@ -341,7 +343,8 @@ evaluated annotations. This attribute is writable and is automatically
 created at the start of class or module body execution, if annotations
 are found statically.
 
-For expressions as assignment targets, the annotations are evaluated if
+If the assignment target is not simple (an attribute, subscript node, or
+parenthesized name), the annotation is evaluated if
 in class or module scope, but not stored.
 
 If a name is annotated in a function scope, then this name is local for