Text of peps.python.org › pep-0649 as Styx crawled it on Nov 19, 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 649 – Deferred Evaluation Of Annotations Using Descriptors | peps.python.org

PEP 649 – Deferred Evaluation Of Annotations Using Descriptors PEP 649 – Deferred Evaluation Of Annotations Using Descriptors Author : Larry Hastings <larry at hastings.org> Discussions-To : Discourse thread Status : Final Type : Standards Track Topic : Typing Created : 11-Jan-2021 Python-Version : 3.14 Post-History : 11-Jan-2021 , 12-Apr-2021 , 18-Apr-2021 , 09-Aug-2021 , 20-Oct-2021 , 20-Oct-2021 , 17-Nov-2021 , 15-Mar-2022 , 23-Nov-2022 , 07-Feb-2023 , 11-Apr-2023 Replaces : 563 Resolution : 08-May-2023 Table of Contents Abstract Overview Comparison Of Annotation Semantics Mistaken Rejection Of This Approach In November 2017 Motivation A History Of Annotations The Current State Of Annotation Use Cases Static typing users Runtime annotation users Wrappers Documentation Motivation For This PEP Implementation Observed semantics for annotations expressions __annotate__ and __annotations__ Changes to allowable annotations syntax Changes to inspect.get_annotations and typing.get_type_hints The stringizer and the fake globals environment Compiler-generated __annotate__ functions Third-party __annotate__ functions Pseudocode Other modifications to the Python runtime Interactive REPL Shell Annotations On Local Variables Inside Functions Prototype Performance Comparison Backwards Compatibility Backwards Compatibility With Stock Semantics Backwards Compatibility With PEP 563 Semantics Rejected Ideas “Just store the strings” Acknowledgements References Copyright Important This PEP is a historical document.

The up-to-date, canonical documentation can now be found at Annotations . × See PEP 1 for how to propose changes. Abstract Annotations are a Python technology that allows expressing type information and other metadata about Python functions, classes, and modules. But Python’s original semantics for annotations required them to be eagerly evaluated, at the time the annotated object was bound. This caused chronic problems for static type analysis users using “type hints”, due to forward-reference and circular-reference problems.

Python solved this by accepting PEP 563 , incorporating a new approach called “stringized annotations” in which annotations were automatically converted into strings by Python. This solved the forward-reference and circular-reference problems, and also fostered intriguing new uses for annotation metadata. But stringized annotations in turn caused chronic problems for runtime users of annotations. This PEP proposes a new and comprehensive third approach for representing and computing annotations.

It adds a new internal mechanism for lazily computing annotations on demand, via a new object method called __annotate__ . This approach, when combined with a novel technique for coercing annotation values into alternative formats, solves all the above problems, supports all existing use cases, and should foster future innovations in annotations. Overview This PEP adds a new dunder attribute to the objects that support annotations–functions, classes, and modules.

The new attribute is called __annotate__ , and is a reference to a function which computes and returns that object’s annotations dict. At compile time, if the definition of an object includes annotations, the Python compiler will write the expressions computing the annotations into its own function. When run, the function will return the annotations dict. The Python compiler then stores a reference to this function in __annotate__ on the object.

Furthermore, __annotations__ is redefined to be a “data descriptor” which calls this annotation function once and caches the result. This mechanism delays the evaluation of annotations expressions until the annotations are examined, which solves many circular reference problems. This PEP also defines new functionality for two functions in the Python standard library: inspect.get_annotations and typing.get_type_hints .

The functionality is accessed via a new keyword-only parameter, format . format allows the user to request the annotations from these functions in a specific format. Format identifiers are always predefined integer values. The formats defined by this PEP are: inspect.VALUE = 1 The default value. The function will return the conventional Python values for the annotations. This format is identical to the return value for these functions under Python 3.11. inspect.FORWARDREF = 2 The function will attempt to return the conventional Python values for the annotations.

However, if it encounters an undefined name, or a free variable that has not yet been associated with a value, it dynamically creates a proxy object (a ForwardRef ) that substitutes for that value in the expression, then continues evaluation. The resulting dict may contain a mixture of proxies and real values. If all real values are defined at the time the function is called, inspect.FORWARDREF and inspect.VALUE produce identical results. inspect.SOURCE = 3 The function will produce an annotation dictionary where the values have been replaced by strings containing the original source code for the annotation expressions.

These strings may only be approximate, as they may be reverse-engineered from another format, rather than preserving the original source code, but the differences will be minor. If accepted, this PEP would supersede PEP 563 , and PEP 563 ’s behavior would be deprecated and eventually removed. Comparison Of Annotation Semantics Note The code presented in this section is simplified for clarity, and is intentionally inaccurate in some critical aspects.

This example is intended merely to communicate the high-level concepts involved without getting lost in the details. But readers should note that the actual implementation is quite different in several important ways. See the Implementation section later in this PEP for a far more accurate description of what this PEP proposes from a technical level. Consider this example code: def foo ( x : int = 3 , y : MyType = None ) -> float : ... class MyType : ... foo_y_annotation = foo . __annotations__ [ 'y' ] As we see here, annotations are available at runtime through an __annotations__ attribute on functions, classes, and modules.

When annotations are specified on one of these objects, __annotations__ is a dictionary mapping the names of the fields to the value specified as that field’s annotation. The default behavior in Python is to evaluate the expressions for the annotations, and build the annotations dict, at the time the function, class, or module is bound. At runtime the above code actually works something like this: annotations = { 'x' : int , 'y' : MyType , 'return' : float } def foo ( x = 3 , y = "abc" ): ... foo . __annotations__ = annotations class MyType : ... foo_y_annotation = foo . __annotations__ [ 'y' ] The crucial detail here is that the values int , MyType , and float are looked up at the time the function object is bound, and these values are stored in the annotations dict.

But this code doesn’t run—it throws a NameError on the first line, because MyType hasn’t been defined yet. PEP 563 ’s solution is to decompile the expressions back into strings during compilation and store those strings as the values in the annotations dict. The equivalent runtime code would look something like this: annotations = { 'x' : 'int' , 'y' : 'MyType' , 'return' : 'float' } def foo ( x = 3 , y = "abc" ): ... foo . __annotations__ = annotations class MyType : ... foo_y_annotation = foo . __annotations__ [ 'y' ] This code now runs successfully.

However, foo_y_annotation is no longer a reference to MyType , it is the string 'MyType' . To turn the string into the real value MyType , the user would need to evaluate the string using eval , inspect.get_annotations , or typing.get_type_hints . This PEP proposes a third approach, delaying the evaluation of the annotations by computing them in their own function. If this PEP was active, the generated code would work something like this

The rest of this page is on the live site.