String annotations [PEP 563] (#4390)
* Document `from __future__ import annotations`
* Provide plumbing and tests for `from __future__ import annotations`
* Implement unparsing the AST back to string form
This is required for PEP 563 and as such only implements a part of the
unparsing process that covers expressions.
diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst
index dca9362..d7792f1 100644
--- a/Doc/reference/compound_stmts.rst
+++ b/Doc/reference/compound_stmts.rst
@@ -559,12 +559,14 @@
parameter name. Any parameter may have an annotation even those of the form
``*identifier`` or ``**identifier``. Functions may have "return" annotation of
the form "``-> expression``" after the parameter list. These annotations can be
-any valid Python expression and are evaluated when the function definition is
-executed. Annotations may be evaluated in a different order than they appear in
-the source code. The presence of annotations does not change the semantics of a
-function. The annotation values are available as values of a dictionary keyed
-by the parameters' names in the :attr:`__annotations__` attribute of the
-function object.
+any valid Python expression. The presence of annotations does not change the
+semantics of a function. The annotation values are available as values of
+a dictionary keyed by the parameters' names in the :attr:`__annotations__`
+attribute of the function object. If the ``annotations`` import from
+:mod:`__future__` is used, annotations are preserved as strings at runtime which
+enables postponed evaluation. Otherwise, they are evaluated when the function
+definition is executed. In this case annotations may be evaluated in
+a different order than they appear in the source code.
.. index:: pair: lambda; expression
@@ -587,6 +589,17 @@
:pep:`3107` - Function Annotations
The original specification for function annotations.
+ :pep:`484` - Type Hints
+ Definition of a standard meaning for annotations: type hints.
+
+ :pep:`526` - Syntax for Variable Annotations
+ Ability to type hint variable declarations, including class
+ variables and instance variables
+
+ :pep:`563` - Postponed Evaluation of Annotations
+ Support for forward references within annotations by preserving
+ annotations in a string form at runtime instead of eager evaluation.
+
.. _class: