Text of peps.python.org › pep-0849 as Styx crawled it on Oct 13, 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 849 – More Expressive Type Expressions | peps.python.org

PEP 849 – More Expressive Type Expressions PEP 849 – More Expressive Type Expressions Author : Imogen Hergeth <python at imogen.tech> Sponsor : Jelle Zijlstra <jelle.zijlstra at gmail.com> Discussions-To : Discourse thread Status : Draft Type : Standards Track Topic : Typing Created : 20-Sep-2026 Python-Version : 3.16 Post-History : 05-Nov-2025 02-Sep-2026 22-Sep-2026 Table of Contents Abstract Motivation Rationale Overview Implementation Performance Impact Usage Outside of Annotations Specification The AST Format Helper Functions Backwards Compatibility Security Implications How to Teach This Reference Implementation Rejected Ideas Creating Typing Objects Within Annotate Functions Storing Annotation Source Code Not Returning AST Namespaces Copyright Abstract Currently, the Python interpreter allows any expression to be used as an annotation.

But their most popular usage, type annotations, are restricted to only a small subset of possible expressions. This is because type annotations need to be introspectable at runtime and many valid expressions produce values where that is not possible. This greatly limits which expressions can be assigned a meaning within the typing spec and limits the expressiveness and ease of use of type annotations. This PEP proposes to expand annotate functions such that any Python expression can be used in type annotations.

It does this by creating a new annotation format which instructs annotate functions to return the annotation’s AST and namespaces. Runtime consumers of type annotations can then evaluate these into typing objects. Motivation Python type annotations are expressions attached to variable names that denote which values can be assigned to a variable. They are not only available to linters and type checkers via the source code directly but also to runtime reflection uses because the interpreter creates special annotate functions that compute the objects the annotation expressions evaluate to.

While this approach works well for many existing annotations and is easy to understand, it also greatly limits the kinds of expressions that can be used as type annotations. In the abstract, this is because the annotate functions evaluate such expressions using the same mechanism that Python uses for regular value expressions, and in many cases those semantics are not compatible with runtime reflection needs. We will now provide several more concrete examples of expressions that could see use in type annotations but are currently not feasible.

However, we are not directly advocating for any specific such usage and this PEP does not implement any of them. Rather, we are providing the groundwork that would make them and similar future proposals possible. PEP 586 introduced literal types, which enumerate a concrete list of possible literal values, e.g. the numbers 1 , 2 and 3 . This is currently spelled as Literal[1, 2, 3] . Many users intuitively want to instead spell this as 1 | 2 | 3 , writing out the bare literals and using the union operator to join them, which also is what other languages such as TypeScript use.

This is currently not possible in Python because the expression 1 | 2 | 3 evaluates simply to 3 because | is interpreted as the binary-or operation rather than the union of types. Further, constant folding eliminates this expression from appearing anywhere in the generated bytecode, and it thus is impossible to retrieve the actual type annotation at runtime. The above example only prevents us from using slightly shorter spellings for already existing types.

There also are many type annotations that either are reasonably possible or even currently being discussed, but which are infeasible to implement currently. The currently open draft of PEP 827 introduces many such types. For example, it proposes conditional types, which are type expressions that evaluate to one of two types depending on some condition. Intuitively, these would be written as FirstType if TypeCondition else OtherType , just like ternary expressions.

But that is not possible because no matter what TypeCondition evaluates to at runtime, one of the other type expressions will never be evaluated and thus be invisible to runtime introspection. Similar issues arise when defining other types that are defined using other existing types. For example, one might want to write {K: NotRequired[T] for K, T in SomeTypedDict} to define a typed dict that has the same definition as an existing typed dict, but where every key is optional.

This is currently not possible because type objects cannot be iterated over in this way. This has also already been discussed in e.g. this thread . Rationale Overview We propose to make it possible to use arbitrary expressions in type expressions while maintaining full runtime introspection capabilities by introducing a new format for annotate functions. It will instruct them to return objects that contain both the annotations’ ASTs and their namespace.

These can then be used to construct the actual type objects that runtime introspection users are interested in. For example, consider the following class: class MyClass : a : int b : list [ str ] When calling MyClass.__annotate__(Format.VALUE) it will still return the usual annotation dict {"a": int, "b": list[str]} . But when called as MyClass.__annotate__(Format.AST) we receive this dictionary: { "a" : AnnotationAST ( ast .

Name ( "int" ), { "int" : int }), "b" : AnnotationAST ( ast . Subscript ( ast . Name ( "list" ), ast . Name ( "str" )), { "list" : list , "str" : str ), } However, most users will never see these objects directly. Rather, we propose to add a new function get_type_annotations to the typing module, which will internally perform the above call and then return the familiar {"a": int, "b": list[str]} annotation dictionary.

The power of this approach is that it lets us implement new type expressions such as the ones mentioned above by simply extending the evaluation logic in get_type_annotations . This logic can then be completely decoupled from the usual Python expression semantics and can instead create typing objects that allow complete runtime introspection. We also propose to add some additional utility functionality related to annotate functions and these AST objects.

In particular, a new create_annoate_function in the annotationlib module to easily synthesize an annotate function. The core of this functionality is already implemented in the dataclasses module, and we foresee that many users will need this in order to create annotate functions that support this somewhat more complex format. Implementation While the exact mechanism annotate functions use is an implementation detail, it may be useful to look at what that might look like.

Consider, for example, the class from above: MyClass : a : int b : list [ str ] Under this proposal its annotate function may behave similar to this Python code: def __annotate__ ( format ): namespace = { "int" : int , "list" : list , "str" : str , } asts = { "a" : " \x1a\x03 int" , "b" : " \x18\x1a\x04 list \x1a\x03 str" , } return _make_annotate_asts ( namespace , asts ) It functions in essentially three steps. It populates the namespace dictionary by performing ordinary variable name lookups.

This is important to ensure that we can later evaluate the returned AST objects using the correct bindings for each variable. It also loads some string constants that contain binary data defining each annotation’s AST. This is a compact format that is easily implemented with existing compiler functionality. It also is much faster to parse than storing the source code of the annotations directly. The annotate function then uses a new intrinsic to actually build the required annotation AST objects.

The proposed get_type_annotations function would then compute the type objects using a function like this: def eval_type_annotation_AST ( ast , namespace ): match ast : case ast . Name : return namespace [ ast . id ] case ast . Att

The rest of this page is on the live site.