Text of peps.python.org › pep-0563 as Styx crawled it on Nov 20, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

PEP 563 – Postponed Evaluation of Annotations | peps.python.org

PEP 563 – Postponed Evaluation of Annotations PEP 563 – Postponed Evaluation of Annotations Author : Łukasz Langa <lukasz at python.org> Discussions-To : Python-Dev list Status : Superseded Type : Standards Track Topic : Typing Created : 08-Sep-2017 Python-Version : 3.7 Post-History : 01-Nov-2017, 21-Nov-2017 Superseded-By : 649 , 749 Resolution : Python-Dev message Table of Contents Resolution Abstract Rationale and Goals Non-goals Non-typing usage of annotations Implementation Enabling the future behavior in Python 3.7 Resolving Type Hints at Runtime Runtime annotation resolution and class decorators Runtime annotation resolution and TYPE_CHECKING Backwards Compatibility Deprecation policy Forward References Rejected Ideas Keeping the ability to use function local state when defining annotations Disallowing local state usage for classes, too Introducing a new dictionary for the string literal form instead Dropping annotations with -O Passing string literals in annotations verbatim to __annotations__ Making the name of the future import more verbose Prior discussion In PEP 484 python/typing#400 First draft discussion on python-ideas Second draft discussion on python-dev Acknowledgements Copyright Resolution The features proposed in this PEP never became the default behaviour, and have been replaced with deferred evaluation of annotations, as proposed by PEP 649 and PEP 749 .

Abstract PEP 3107 introduced syntax for function annotations, but the semantics were deliberately left undefined. PEP 484 introduced a standard meaning to annotations: type hints. PEP 526 defined variable annotations, explicitly tying them with the type hinting use case. This PEP proposes changing function annotations and variable annotations so that they are no longer evaluated at function definition time. Instead, they are preserved in __annotations__ in string form.

This change is being introduced gradually, starting with a __future__ import in Python 3.7. Rationale and Goals PEP 3107 added support for arbitrary annotations on parts of a function definition. Just like default values, annotations are evaluated at function definition time. This creates a number of issues for the type hinting use case: forward references: when a type hint contains names that have not been defined yet, that definition needs to be expressed as a string literal; type hints are executed at module import time, which is not computationally free.

Postponing the evaluation of annotations solves both problems. NOTE: PEP 649 proposes an alternative solution to the above issues, putting this PEP in danger of being superseded. Non-goals Just like in PEP 484 and PEP 526 , it should be emphasized that Python will remain a dynamically typed language, and the authors have no desire to ever make type hints mandatory, even by convention. This PEP is meant to solve the problem of forward references in type annotations.

There are still cases outside of annotations where forward references will require usage of string literals. Those are listed in a later section of this document. Annotations without forced evaluation enable opportunities to improve the syntax of type hints. This idea will require its own separate PEP and is not discussed further in this document. Non-typing usage of annotations While annotations are still available for arbitrary use besides type checking, it is worth mentioning that the design of this PEP, as well as its precursors ( PEP 484 and PEP 526 ), is predominantly motivated by the type hinting use case.

In Python 3.8 PEP 484 will graduate from provisional status. Other enhancements to the Python programming language like PEP 544 , PEP 557 , or PEP 560 , are already being built on this basis as they depend on type annotations and the typing module as defined by PEP 484 . In fact, the reason PEP 484 is staying provisional in Python 3.7 is to enable rapid evolution for another release cycle that some of the aforementioned enhancements require.

With this in mind, uses for annotations incompatible with the aforementioned PEPs should be considered deprecated. Implementation With this PEP, function and variable annotations will no longer be evaluated at definition time. Instead, a string form will be preserved in the respective __annotations__ dictionary. Static type checkers will see no difference in behavior, whereas tools using annotations at runtime will have to perform postponed evaluation.

The string form is obtained from the AST during the compilation step, which means that the string form might not preserve the exact formatting of the source. Note: if an annotation was a string literal already, it will still be wrapped in a string. Annotations need to be syntactically valid Python expressions, also when passed as literal strings (i.e. compile(literal, '', 'eval') ). Annotations can only use names present in the module scope as postponed evaluation using local names is not reliable (with the sole exception of class-level names resolved by typing.get_type_hints() ).

Note that as per PEP 526 , local variable annotations are not evaluated at all since they are not accessible outside of the function’s closure. Enabling the future behavior in Python 3.7 The functionality described above can be enabled starting from Python 3.7 using the following special import: from __future__ import annotations A reference implementation of this functionality is available on GitHub . Resolving Type Hints at Runtime To resolve an annotation at runtime from its string form to the result of the enclosed expression, user code needs to evaluate the string.

For code that uses type hints, the typing.get_type_hints(obj, globalns=None, localns=None) function correctly evaluates expressions back from its string form. Note that all valid code currently using __annotations__ should already be doing that since a type annotation can be expressed as a string literal. For code which uses annotations for other purposes, a regular eval(ann, globals, locals) call is enough to resolve the annotation.

In both cases it’s important to consider how globals and locals affect the postponed evaluation. An annotation is no longer evaluated at the time of definition and, more importantly, in the same scope where it was defined. Consequently, using local state in annotations is no longer possible in general. As for globals, the module where the annotation was defined is the correct context for postponed evaluation. The get_type_hints() function automatically resolves the correct value of globalns for functions and classes.

It also automatically provides the correct localns for classes. When running eval() , the value of globals can be gathered in the following way: function objects hold a reference to their respective globals in an attribute called __globals__ ; classes hold the name of the module they were defined in, this can be used to retrieve the respective globals: cls_globals = vars ( sys . modules [ SomeClass . __module__ ]) Note that this needs to be repeated for base classes to evaluate all __annotations__ . modules should use their own __dict__ .

The value of localns cannot be reliably retrieved for functions because in all likelihood the stack frame at the time of the call no longer exists. For classes, localns can be composed by chaining vars of the given class and its base classes (in the method resolution order). Since slots can only be filled after the class was defined, we don’t need to consult them for this purpose. Runtime annotation resolution and class decorators Metaclasses and class decorators that need to resolve annotations for the current class will fail for annotations that use the name of the current class.

Example: def class_decorator ( cls ): annotations = get_type_hints ( cls ) # raises NameError on 'C' print ( f 'Annotations for { cls } : { annotations } ' ) return cls @class_decorator class C : singleton : 'C' = None This was already true before this PEP. The class decorator acts on the class b

The rest of this page is on the live site.