Issue #27985: Implement PEP 526 -- Syntax for Variable Annotations.

Patch by Ivan Levkivskyi.

2 files changed, 65 insertions, 14 deletions

diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index a075503..3d581a5 100644
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -686,33 +686,36 @@ Modules
    Attribute assignment updates the module's namespace dictionary, e.g.,
    ``m.x = 1`` is equivalent to ``m.__dict__["x"] = 1``.
 
-   .. index:: single: __dict__ (module attribute)
-
-   Special read-only attribute: :attr:`~object.__dict__` is the module's namespace as a
-   dictionary object.
-
-   .. impl-detail::
-
-      Because of the way CPython clears module dictionaries, the module
-      dictionary will be cleared when the module falls out of scope even if the
-      dictionary still has live references.  To avoid this, copy the dictionary
-      or keep the module around while using its dictionary directly.
-
    .. index::
       single: __name__ (module attribute)
       single: __doc__ (module attribute)
       single: __file__ (module attribute)
+      single: __annotations__ (module attribute)
       pair: module; namespace
 
    Predefined (writable) attributes: :attr:`__name__` is the module's name;
    :attr:`__doc__` is the module's documentation string, or ``None`` if
-   unavailable; :attr:`__file__` is the pathname of the file from which the
+   unavailable; :attr:`__annotations__` (optional) is a dictionary containing
+   :term:`variable annotations <variable annotation>` collected during module
+   body execution; :attr:`__file__` is the pathname of the file from which the
    module was loaded, if it was loaded from a file. The :attr:`__file__`
    attribute may be missing for certain types of modules, such as C modules
    that are statically linked into the interpreter; for extension modules
    loaded dynamically from a shared library, it is the pathname of the shared
    library file.
 
+   .. index:: single: __dict__ (module attribute)
+
+   Special read-only attribute: :attr:`~object.__dict__` is the module's
+   namespace as a dictionary object.
+
+   .. impl-detail::
+
+      Because of the way CPython clears module dictionaries, the module
+      dictionary will be cleared when the module falls out of scope even if the
+      dictionary still has live references.  To avoid this, copy the dictionary
+      or keep the module around while using its dictionary directly.
+
 Custom classes
    Custom class types are typically created by class definitions (see section
    :ref:`class`).  A class has a namespace implemented by a dictionary object.
@@ -761,13 +764,17 @@ Custom classes
       single: __dict__ (class attribute)
       single: __bases__ (class attribute)
       single: __doc__ (class attribute)
+      single: __annotations__ (class attribute)
 
    Special attributes: :attr:`~definition.__name__` is the class name; :attr:`__module__` is
    the module name in which the class was defined; :attr:`~object.__dict__` is the
    dictionary containing the class's namespace; :attr:`~class.__bases__` is a
    tuple (possibly empty or a singleton) containing the base classes, in the
    order of their occurrence in the base class list; :attr:`__doc__` is the
-   class's documentation string, or None if undefined.
+   class's documentation string, or None if undefined;
+   :attr:`__annotations__` (optional) is a dictionary containing
+   :term:`variable annotations <variable annotation>` collected during
+   class body execution.
 
 Class instances
    .. index::
diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst
index eee3f43..1973272 100644
--- a/Doc/reference/simple_stmts.rst
+++ b/Doc/reference/simple_stmts.rst
@@ -16,6 +16,7 @@ simple statements is:
               : | `assert_stmt`
               : | `assignment_stmt`
               : | `augmented_assignment_stmt`
+              : | `annotated_assignment_stmt`
               : | `pass_stmt`
               : | `del_stmt`
               : | `return_stmt`
@@ -312,6 +313,49 @@ For targets which are attribute references, the same :ref:`caveat about class
 and instance attributes <attr-target-note>` applies as for regular assignments.
 
 
+.. _annassign:
+
+Annotated assignment statements
+-------------------------------
+
+.. index::
+   pair: annotated; assignment
+   single: statement; assignment, annotated
+
+Annotation assignment is the combination, in a single statement,
+of a variable or attribute annotation and an optional assignment statement:
+
+.. productionlist::
+   annotated_assignment_stmt: `augtarget` ":" `expression` ["=" `expression`]
+
+The difference from normal :ref:`assignment` is that only single target and
+only single right hand side value is allowed.
+
+For simple names as 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 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
+in class or module scope, but not stored.
+
+If a name is annotated in a function scope, then this name is local for
+that scope. Annotations are never evaluated and stored in function scopes.
+
+If the right hand side is present, an annotated
+assignment performs the actual assignment before evaluating annotations
+(where applicable). If the right hand side is not present for an expression
+target, then the interpreter evaluates the target except for the last
+:meth:`__setitem__` or :meth:`__setattr__` call.
+
+.. seealso::
+
+   :pep:`526` - Variable and attribute annotation syntax
+   :pep:`484` - Type hints
+
+
 .. _assert:
 
 The :keyword:`assert` statement