[3.12] annotations: expand documentation on "simple" assignment targets (GH-120535) (#120556)

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

(cherry picked from commit 9e0b11e)

Co-authored-by: Jelle Zijlstra <[email protected]>
Co-authored-by: Alex Waygood <[email protected]>

Author: 3 people

Doc/library/ast.rst

@@ -883,9 +883,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::
 

Doc/reference/simple_stmts.rst

@@ -333,15 +333,18 @@ 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
 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