Specification

We suggest the following deprecation plan:

• In Python 3.14,from__future__importannotations will continue to work as itdid before, converting annotations into strings.
  • If the future import is active, the__annotate__ function of objects withannotations will return the annotations as strings when called with theVALUEformat, reflecting the behavior of__annotations__.
• Sometime after the last release that did not supportPEP 649 semantics (expected to be 3.13)reaches its end-of-life,from__future__importannotations is deprecated. Compilingany code that uses the future import will emit aDeprecationWarning. This willhappen no sooner than the first release after Python 3.13 reaches its end-of-life, butthe community may decide to wait longer.
• After at least two releases, the future import is removed, and annotations are alwaysevaluated as perPEP 649. Code that continues to use the future import will raiseaSyntaxError, similar to any other undefined future import.

Rejected alternatives

Immediately make the future import a no-op: We considered applyingPEP 649 semanticsto all code in Python 3.14, making the future import a no-op. However, this would breakcode that works in 3.13 under the following set of conditions:

• __future__importannotations is active
• There are annotations that rely on forward references
• Annotations are eagerly evaluated at import time, for example by a metaclass orclass or function decorator. For example, this currently applies to thereleased version oftyping_extensions.TypedDict.

This is expected to be a common pattern, so we cannot afford to break such code duringthe upgrade from 3.13 to 3.14.

Such code would still break when the future import is eventually removed. However, thisis many years in the future, giving affected libraries plenty of time to update their code.

Immediately deprecate the future import: Instead of waiting until Python 3.13 reachesits end-of-life, we could immediately start emitting warnings when the future import isused. However, many libraries are already usingfrom__future__importannotations asan elegant way to enable unrestricted forward references in their annotations. If we deprecatethe future import immediately, it would be impossible for these libraries to use unrestrictedforward references on all supported Python versions while avoiding deprecation warnings:unlike other features deprecated from the standard library, a__future__ import mustbe the first statement in a given module, meaning it would be impossible to onlyconditionally import__future__.annotations on Python 3.13 and lower. (The necessarysys.version_info check would count as a statement preceding the__future__ import.)

Keep the future import around forever: We could also decide to keep the future importindefinitely. However, this would permanently bifurcate the behavior of the Pythonlanguage. This is undesirable; the language should have only a single set of semantics,not two permanently different modes.

Make the future import a no-op in the future: Instead of eventually makingfrom__future__importannotations aSyntaxError, we could make it do nothinginstead at some point after Python 3.13 reaches its end-of-life. This still has someof the same issues outlined above around making it a no-op now, although the ecosystemwould have had much longer to adapt. It is better to have users explicitly removethe future import from their code in the future once they have confirmed they do notrely on stringized annotations.

Rationale

PEP 649 indicates thattyping.ForwardRef should be used to implement theFORWARDREF format ininspect.get_annotations(). However, the existing implementationoftyping.ForwardRef is intertwined with the rest of thetyping module,and it would not make sense to addtyping-specific behavior to the genericget_annotations()function. Furthermore,typing.ForwardRef is a problematicclass: it is public and documented, but the documentation lists no attributes or methodsfor it. Nonetheless, third-party libraries make use of some of its undocumentedattributes. For instance,PydanticandTypeguarduse the_evaluate method;beartypeandpyanalyzeuse the__forward_arg__ attribute.

We replace the existing but poorly specifiedtyping.ForwardRef with a new class,annotationlib.ForwardRef. It is designed to be mostly compatible with existing usesof thetyping.ForwardRef class, but without the behaviors specific to thetyping module. For compatibility with existing users, we keep the private_evaluate method, but mark it as deprecated. It delegates to a new public function inthetyping module,typing.evaluate_forward_ref, that is designed toevaluate forward references in a way that is specific to type hints.

We add a functionannotationlib.call_annotate_function as a helper for calling__annotate__ functions. This is a useful building block when implementing functionalitythat needs to partially evaluate annotations while a class is being constructed.For example, the implementation oftyping.NamedTuple needs to retrievethe annotations from a class namespace dictionary before the namedtuple class itselfcan be constructed, because the annotations determine what fields exist on the namedtuple.

Specification

A new module,annotationlib, is added to the standard library. Its aim is toprovide tooling for introspecting and wrapping annotations.

The design of the module is informed by the experience of updating the standardlibrary (e.g.,dataclasses andtyping.TypedDict) to usePEP 649 semantics.

The module will contain the following functionality:

• get_annotations(): A function that returns the annotations of a function,module, or class. This will replaceinspect.get_annotations(). The latterwill delegate to the new function. It may eventually be deprecated, but tominimize disruption, we do not propose an immediate deprecation.
• get_annotate_from_class_namespace(namespace:Mapping[str,Any]): A function thatreturns the__annotate__ function from a class namespace dictionary, orNoneif there is none. This is useful in metaclasses during class construction. It isa separate function to avoid exposing implementation details about the internal storagefor the__annotate__ function (seebelow).
• Format: an enum that contains the possible formats of annotations. This willreplace theVALUE,FORWARDREF, andSOURCE formats inPEP 649.PEP 649 proposed to make these values global members of theinspectmodule; we prefer to place them within an enum. We propose to add a fourth format,VALUE_WITH_FAKE_GLOBALS (see below).
• ForwardRef: a class representing a forward reference; it may be returned byget_annotations() when the format isFORWARDREF. The existing classtyping.ForwardRef will become an alias of this class. Its members include:
  • __forward_arg__: the string argument of the forward reference
  • evaluate(globals=None,locals=None,type_params=None,owner=None): a method that attempts to evaluatethe forward reference. TheForwardRef object may hold a reference to theglobals and other namespaces of the object that it originated from. If so, thesenamespaces may be used to evaluate the forward reference. Theowner argumentmay be the object that holds the original annotation, such as the class or moduleobject; it is used to extract the globals and locals namespaces if these are notprovided.
  • _evaluate(), with the same interface as the existingForwardRef._evaluatemethod. It will be undocumented and immediately deprecated. It is provided forcompatibility with existing users oftyping.ForwardRef.
• call_annotate_function(func:Callable,format:Format): a helper for callingan__annotate__ function with a given format. If the function does not supportthis format,call_annotate_function() will set up a “fake globals” environment,as described inPEP 649, and use that environment to return the desired annotationsformat.
• call_evaluate_function(func:Callable|None,format:Format): similar tocall_annotate_function, but does not rely on the function returning an annotationsdictionary. This is intended to be used for evaluating deferred attributes introduced byPEP 695 andPEP 696; see below for details.func may beNonefor convenience; ifNone is passed, the function also returnsNone.
• annotations_to_string(annotations:dict[str,object])->dict[str,str]: a function thatconverts each value in an annotations dictionary to a string representation.This is useful forimplementing theSOURCE format in cases where the original source is not available,such as in the functional syntax fortyping.TypedDict.
• type_repr(value:object)->str: a function that converts a single value to astring representation. This is used byannotations_to_string.It usesrepr() for most values, but for types it returns the fully qualified name.It is also useful as a helper for therepr() of a number of objects in thetyping andcollections.abc modules.

A new function is also added to thetyping module,typing.evaluate_forward_ref.This function is a wrapper around theForwardRef.evaluate method, but it performsadditional work that is specific to type hints. For example, it recurses into complextypes and evaluates additional forward references within these types.

Contrary toPEP 649, the annotation formats (VALUE,FORWARDREF, andSOURCE)will not be added as global members of theinspect module. The only recommendedway to refer to these constants will be asannotationlib.Format.VALUE.

Rejected alternatives

Use a different name: Naming is hard, and I considered several ideas:

• annotations: The most obvious name, but it may cause confusion with the existingfrom__future__importannotations, because users may have bothimportannotationsandfrom__future__importannotations in the same module. The use of a common wordas the name will make the module harder to search for. There is a PyPI packageannotations,but it had only a single release in 2015 and looks abandoned.
• annotation (in the singular): Similar, but does not cause confusion with the futureimport. There is an abandoned PyPI packageannotation, but it apparently neverreleased any artifacts.
• annotools: Analogous toitertools andfunctools, but “anno” is a lessobvious abbreviation than “iter” or “func”. As of this writing, thereis no PyPI package with this name.
• annotationtools: A more explicit version. There is a PyPI packageannotationtools, which had a release in 2023.
• annotation_tools: A variation of the above but without a PyPI conflict. However,no other public standard library module has an underscore in its name.
• annotationslib: Analogous totomllib,pathlib, andimportlib.There is no PyPI package with this name.
• annotationlib: Similar to the above, but one character shorter and subjectively readsbetter. Also not taken on PyPI.

annotationlib appears to be the best option.

Add the functionality to the inspect module: As described above, theinspect module is already quite large, and its import time is prohibitivefor some use cases.

Add the functionality to the typing module: While annotations are mostlyused for typing, they may also be used for other purposes. We prefer to keep a cleanseparation between functionality for introspecting annotations and functionality thatis exclusively meant for type hints.

Add the functionality to the types module: Thetypes module ismeant for functionality related totypes, and annotations can exist on functionsand modules, not only on types.

Develop this functionality in a third-party package: The functionality in this newmodule will be pure Python code, and it is possible to implement a third-party packagethat provides the same functionality by interacting directly with__annotate__functions generated by the interpreter. However, the functionality of the proposed newmodule will certainly be useful in the standard library itself (e.g., for implementingdataclasses andtyping.NamedTuple), so it makes sense to includeit in the standard library.

Add this functionality to a private module: It would be possible to initially developthe module in a private standard library module (e.g.,_annotations), and publicizeit only after we have gained more experience with the API. However, we already knowthat we will need parts of this module for the standard library itself (e.g., forimplementingdataclasses andtyping.NamedTuple). Even if we makeit private, the module will inevitably get used by third-party users. It is preferableto start with a clear, documented API from the beginning, to enable third-party users tosupportPEP 649 semantics as thoroughly as the standard library. The module willimmediately be used in other parts of the standard library, ensuring that it covers areasonable set of use cases.

Specification

We propose to treat the interactive console like any other module-level code, andmake annotations lazily evaluated. This makes the language more consistent andavoids subtle behavior changes between modules and the REPL.

Because the REPL is evaluated line by line, we would generate a new__annotate__function for every evaluated statement in the global scope that contains annotations. Whenever a linecontaining annotations is evaluated, the previous__annotate__ function islost:

>>>x:int>>>__annotate__(1){'x': <class 'int'>}>>>y:str>>>__annotate__(1){'y': <class 'str'>}>>>z:doesntexist>>>__annotate__(1)Traceback (most recent call last):File "<python-input-5>", line 1, in <module>    __annotate__(1)    ~~~~~~~~~~~~^^^File "<python-input-4>", line 1, in __annotate__    z:doesntexist       ^^^^^^^^^^^NameError: name 'doesntexist' is not defined

There will be no__annotations__ key in the global namespace of the REPL.In module namespaces, this key is created lazily when the__annotations__descriptor of the module object is accessed, but in the REPL there is no such moduleobject.

Classes and functions defined within the REPL will also work like any other classes,so evaluation of their annotations will be deferred. It is possible to access the__annotations__ and__annotate__ attributes or use theannotationlib moduleto introspect the annotations.

Specification

Wrappers that provide annotations should be designed with the following goalsin mind:

• Evaluation of__annotations__ should be deferred for as long as possible,consistent with the behavior of built-in functions, classes, and modules.
• Backward compatibility with the behavior prior to the implementation ofPEP 649should be preserved.
• The__annotate__ and__annotations__ attributes should both be suppliedwith semantics consistent to those of the wrapped object.

More specifically:

• functools.update_wrapper() (and thereforefunctools.wraps())will copy only the__annotate__ attributefrom the wrapped object to the wrapper. The__annotations__ descriptor on thewrapper function will use the copied__annotate__.
• The constructors forclassmethod() andstaticmethod() currentlycopy the__annotations__ attribute from the wrapped object to the wrapper.They will instead have writable attributes for__annotate__ and__annotations__. Reading these attributes will retrievethe corresponding attribute from the underlying callable and cache it in the wrapper’s__dict__. Writing to these attributes will directly update the__dict__,without affecting the wrapped callable.

Pre-existing bugs

We found several bugs in the existing behavior of__annotations__ on classeswhile investigating the behaviors to be specified in this PEP. Fixing these bugson Python 3.13 and earlier is outside the scope of this PEP, but they are noted hereto explain the corner cases that need to be dealt with.

For context, on Python 3.10 through 3.13 the__annotations__ dictionary isplaced in the class namespace if the class has any annotations. If it does not,there is no__annotations__ class dictionary key when the class is created,but accessingcls.__annotations__ invokes a descriptor defined ontypethat returns an empty dictionary and stores it in the class dictionary.Static types are an exception: they never haveannotations, and accessing.__annotations__ raisesAttributeError.On Python 3.9 and earlier, the behavior was different; seegh-88067.

The following code fails identically on Python 3.10 through 3.13:

classMeta(type):passclassX(metaclass=Meta):a:strclassY(X):passMeta.__annotations__# importantassertY.__annotations__=={},Y.__annotations__# fails: {'a': <class 'str'>}

If the annotations on the metaclassMeta are accessed before the annotationsonY, then the annotations for the base classX are leaked toY.However, if the metaclass’s annotations arenot accessed (i.e., the lineMeta.__annotations__above is removed), then the annotations forY are correctly empty.

Similarly, annotations from annotated metaclasses leak to unannotatedclasses that are instances of the metaclass:

classMeta(type):a:strclassX(metaclass=Meta):passassertX.__annotations__=={},X.__annotations__# fails: {'a': <class 'str'>}

The reason for these behaviors is that if the metaclass contains an__annotations__ entry in its class dictionary, this preventsinstances of the metaclass from using the__annotations__ data descriptoron the basetype class. In the first case, accessingMeta.__annotations__setsMeta.__dict__["__annotations__"]={} as a side effect. Then, lookingup the__annotations__ attribute onY first sees the metaclass attribute,but skips it because it is a data descriptor. Next, it looks in the class dictionariesof the classes in its method resolution order (MRO), findsX.__annotations__,and returns it. In the second example, there are no annotationsanywhere in the MRO, sotype.__getattribute__ falls back toreturning the metaclass attribute.

Metaclass behavior with PEP 649

WithPEP 649, the behavior of accessing the.__annotations__ attributeon classes when metaclasses are involved becomes even more erratic, because now__annotations__ is only lazily added to the class dictionary even for classeswith annotations. The new__annotate__ attribute is also lazily createdon classes without annotations, which causes further misbehaviors whenmetaclasses are involved.

The cause of these problems is that we set the__annotate__ and__annotations__class dictionary entries only under some circumstances, and rely on descriptorsdefined ontype to fill them in if they are not set. When normalattribute lookup is used, this approach breaks down in the presence ofmetaclasses, because entries in the metaclass’s own class dictionary can renderthe descriptors invisible.

We considered several solutions but landed on one where we store the__annotate__and__annotations__ objects in the class dictionary, but under a different,internal-only name. This means that the class dictionary entries will not interferewith the descriptors defined ontype.

This approach means that the.__annotate__ and.__annotations__ objects in classobjects will behave mostly intuitively, but there are a few downsides.

One concerns the interaction with classes defined underfrom__future__importannotations.Those will continue to have the__annotations__ entry in the class dictionary, meaningthat they will continue to display some buggy behavior. For example, if a metaclass is definedwith the__future__ import enabled and has annotations, and a class using that metaclass isdefined without the__future__ import, accessing.__annotations__ on that class will yieldthe wrong results. However, this bug already exists in previous versions of Python. It could befixed by setting the annotations at a different key in the class dict in this case too, but thatwould break users who directly access the class dictionary (e.g., during class construction).We prefer to keep the behavior under the__future__ import unchanged as much as possible.

Second, in previous versions of Python it was possible to access the__annotations__ attributeon instances of user-defined classes with annotations. However, this behavior was undocumentedand not supported byinspect.get_annotations(), and it cannot be preserved under thePEP 649 framework without bigger changes, such as a newobject.__annotations__ descriptor.This behavior change should be called out in porting guides.

Specification

The.__annotate__ and.__annotations__ attributes on class objectsshould reliably return the annotate function and the annotations dictionary,respectively, even in the presence of custom metaclasses.

Users should not access the class dictionary directly for accessing annotationsor the annotate function; the data stored in the class dictionary is an implementationdetail and its format may change in the future. If only the class namespacedictionary is available (e.g., while the class is being constructed),annotationlib.get_annotate_from_class_namespace may be used to retrieve the annotate functionfrom the class dictionary.

Rejected alternatives

We considered three broad approaches for dealing with the behaviorof the__annotations__ and__annotate__ entries in classes:

• Ensure that the entry isalways present in the class dictionary, even if itis empty or has not yet been evaluated. This means we do not have to rely onthe descriptors defined ontype to fill in the field, andtherefore the metaclass’s attributes will not interfere. (Prototypeingh-120719.)
• Warn users against using the__annotations__ and__annotate__ attributesdirectly. Instead, users should call function inannotationlib thatinvoke thetype descriptors directly. (Implemented ingh-122074.)
• Ensure that the entry isnever present in the class dictionary, or at leastnever added by logic in the language core. This means that the descriptorsontype will always be used, without interference from the metaclass.(Initial prototype ingh-120816;later implemented ingh-132345.)

Alex Waygood suggested an implementation using the first approach. When aheap type (such as a class created through theclass statement) is created,cls.__dict__["__annotations__"] is set to a special descriptor.On__get__, the descriptor evaluates the annotations by calling__annotate__and returning the result. The annotations dictionary is cached within thedescriptor instance. The descriptor also behaves like a mapping,so that code that usescls.__dict__["__annotations__"] will still usuallywork: treating the object as a mapping will evaluate the annotations and behaveas if the descriptor itself was the annotations dictionary. (Code that assumesthatcls.__dict__["__annotations__"] is specifically an instance ofdictmay break, however.)

This approach is also straightforward to implement for__annotate__: thisattribute is already always set for classes with annotations, and we can setit explicitly toNone for classes without annotations.

While this approach would fix the known edge cases with metaclasses, itintroduces significant complexity to all classes, including a new built-in type(for the annotations descriptor) with unusual behavior.

The second approach is simple to implement, but has the downside that directaccess tocls.__annotations__ remains prone to erratic behavior.

Specification

An additional format,VALUE_WITH_FAKE_GLOBALS, is added to theFormat enum in theannotationlib module, with value equal to 2. (As a result, the values of theother formats will shift relative to PEP 649:FORWARDREF will be 3 andSOURCEwill be 4.) The integer values of these formats are specified for use in places wherethe enum is not readily available, such as in__annotate__ functions implementedin C.

Compiler-generatedannotate functions will support this format and return the same value asthey would return for theVALUE format. The standard library will passthis format to the__annotate__ function when it is called in a “fake globals”environment, as used to implement theFORWARDREF andSOURCE formats.All public functions in theannotationlib module that accept a formatargument will raiseNotImplementedError if the format isVALUE_WITH_FAKE_GLOBALS.

Third-party code that implements__annotate__ functions should raiseNotImplementedError if theVALUE_WITH_FAKE_GLOBALS format is passedand the function is not prepared to be run in a “fake globals” environment.This should be mentioned in the data model documentation for__annotate__.

Specification

Deleting the__annotations__ attribute on functions, modules, and classesresults in setting__annotate__ to None.

Specification

We will add the following new attributes:

• evaluate_value ontyping.TypeAliasType
• evaluate_bound,evaluate_constraints, andevaluate_default ontyping.TypeVar
• evaluate_default ontyping.ParamSpec
• evaluate_default ontyping.TypeVarTuple

Except forevaluate_value, these attributes may beNone if the objectdoes not have a bound, constraints, or default. Otherwise, the attribute is acallable, similar to an__annotate__ function, that takes a single integerargument and returns the evaluated value. Unlike__annotate__ functions,these callables return a single value, not a dictionary of annotations.These attributes are read-only.

Usually, users would use these attributes in combinations withannotationlib.call_evaluate_function. For example, to get aTypeVar’s boundin SOURCE format, one could writeannotationlib.call_evaluate_function(T.evaluate_bound,annotationlib.Format.SOURCE).

Specification

TheSOURCE format is renamed toSTRING. To reiterate the changes in thisPEP, the four supported formats are now:

• VALUE: the default format, which evaluates the annotations and returns theresulting values.
• VALUE_WITH_FAKE_GLOBALS: for internal use; should be handled likeVALUEby annotate functions that support execution with fake globals.
• FORWARDREF: replaces undefined names withForwardRef objects.
• STRING: returns strings, attempts to recreate code close to the original source.

Specification

For classes and modules, the__annotate__ function will return onlyannotations for those assignments that were executed when the class or module bodywas executed.

Specification

Accessing__annotations__ on a partially executed module willcontinue to return the annotations that have been executed so far,similar to the behavior in earlier versions in Python. However, in thiscase the__annotations__ dictionary will not be cached, so lateraccesses to the__annotations__ attribute will return a fresh dictionary.This is necessary because__annotate__ must be called again in order toincorporate additional annotations.

Supported operations onForwardRef objects

TheSOURCE format is implemented by the “stringizer” technique,where the globals dictionary of a function is augmented so that everylookup results in a special object that can be used to reconstruct theoperations that are performed on the object.

PEP 649 specifies:

In practice, the “stringizer” functionality will be implementedin theForwardRef object currently defined in thetyping module.ForwardRef will be extended toimplement all stringizer functionality; it will also beextended to support evaluating the string it contains,to produce the real value (assuming all symbols referencedare defined).

However, this is likely to lead to confusion in practice. An objectthat implements stringizer functionality must implement almost allspecial methods, including__getattr__ and__eq__, to returna new stringizer. Such an object is confusing to work with: all operationssucceed, but they are likely to return different objects than the userexpects.

The current implementation instead implements only a few useful methodson theForwardRef class. During the evaluation of annotations,an instance of a private stringizer class is used instead ofForwardRef.After evaluation completes, the implementation of the FORWARDREF formatconverts these internal objects intoForwardRef objects.

Signature of__annotate__ functions

PEP 649 specifies the signature of__annotate__ functions as:

__annotate__(format:int)->dict

However, usingformat as a parameter name could lead to collisionsif an annotation uses a symbol namedformat. To avoid this problem,the current implementation uses a positional-only parameter that is namedformat in the function signature, but that does not shadow use of the nameformat within the annotation.

Which expressions can be stringified?

PEP 649 acknowledges that the stringifier cannot handle all expressions. Now that wehave a draft implementation, we can be more precise about the expressions that can andcannot be handled. Below is a list of all expressions in the Python AST that can andcannot be recovered by the stringifier. The full list should probably not be added tothe documentation, but creating it is a useful exercise.

First, the stringifier of course cannot recover any information that is not present inthe compiled code, including comments, whitespace, parenthesization, and operations thatget simplified by the AST optimizer.

Second, the stringifier can intercept almost all operations that involve names lookedup in some scope, but it cannot intercept operations that operate fully on constants.As a corollary, this also means it is not safe to request theSOURCE format onuntrusted code: Python is powerful enough that it is possible to achieve arbitrarycode execution even with no access to any globals or builtins. For example:

>>>deff(x:(1).__class__.__base__.__subclasses__()[-1].__init__.__builtins__["print"]("Hello world")):pass...>>>annotationlib.get_annotations(f,format=annotationlib.Format.SOURCE)Hello world{'x': 'None'}

(This particular example worked for me on the current implementation of a draft of this PEP;the exact code may not keep working in the future.)

The following are supported (sometimes with caveats):

• BinOp
• UnaryOp
  • Invert (~),UAdd (+), andUSub (-) are supported
  • Not (not) is not supported
• Dict (except when using** unpacking)
• Set
• Compare
  • Eq andNotEq are supported
  • Lt,LtE,Gt, andGtE are supported, but the operand may be flipped
  • Is,IsNot,In, andNotIn are not supported
• Call (except when using** unpacking)
• Constant (though not the exact representation of the constant; for example, escapesequences in strings are lost; hexadecimal numbers are converted to decimal)
• Attribute (assuming the value is not a constant)
• Subscript (assuming the value is not a constant)
• Starred (* unpacking)
• Name
• List
• Tuple
• Slice

The following are unsupported, but throw an informative error when encountered by thestringifier:

• FormattedValue (f-strings; error is not detected if conversion specifiers like!rare used)
• JoinedStr (f-strings)

The following are unsupported and result in incorrect output:

• BoolOp (and andor)
• IfExp
• Lambda
• ListComp
• SetComp
• DictComp
• GeneratorExp

The following are disallowed in annotation scopes and therefore not relevant:

• NamedExpr (:=)
• Await
• Yield
• YieldFrom