Text of peps.python.org › pep-0526 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 526 – Syntax for Variable Annotations | peps.python.org

PEP 526 – Syntax for Variable Annotations PEP 526 – Syntax for Variable Annotations Author : Ryan Gonzalez <rymg19 at gmail.com>, Philip House <phouse512 at gmail.com>, Ivan Levkivskyi <levkivskyi at gmail.com>, Lisa Roach <lisaroach14 at gmail.com>, Guido van Rossum <guido at python.org> Status : Final Type : Standards Track Topic : Typing Created : 09-Aug-2016 Python-Version : 3.6 Post-History : 30-Aug-2016, 02-Sep-2016 Resolution : Python-Dev message Table of Contents Status Notice for Reviewers Abstract Rationale Non-goals Specification Global and local variable annotations Class and instance variable annotations Annotating expressions Where annotations aren’t allowed Variable annotations in stub files Preferred coding style for variable annotations Changes to Standard Library and Documentation Runtime Effects of Type Annotations Other uses of annotations Rejected/Postponed Proposals Backwards Compatibility Implementation Copyright Important This PEP is a historical document: see Annotated assignment statements , ClassVar and typing.ClassVar for up-to-date specs and documentation.

Canonical typing specs are maintained at the typing specs site ; runtime typing behaviour is described in the CPython documentation. × See the typing specification update process for how to propose changes to the typing spec. Status This PEP has been provisionally accepted by the BDFL. See the acceptance message for more color: https://mail.python.org/pipermail/python-dev/2016-September/146282.html Notice for Reviewers This PEP was drafted in a separate repo: https://github.com/phouse512/peps/tree/pep-0526 .

There was preliminary discussion on python-ideas and at https://github.com/python/typing/issues/258 . Before you bring up an objection in a public forum please at least read the summary of rejected ideas listed at the end of this PEP. Abstract PEP 484 introduced type hints, a.k.a. type annotations. While its main focus was function annotations, it also introduced the notion of type comments to annotate variables: # 'primes' is a list of integers primes = [] # type: List[int] # 'captain' is a string (Note: initial value is a problem) captain = ... # type: str class Starship : # 'stats' is a class variable stats = {} # type: Dict[str, int] This PEP aims at adding syntax to Python for annotating the types of variables (including class variables and instance variables), instead of expressing them through comments: primes : List [ int ] = [] captain : str # Note: no initial value! class Starship : stats : ClassVar [ Dict [ str , int ]] = {} PEP 484 explicitly states that type comments are intended to help with type inference in complex cases, and this PEP does not change this intention.

However, since in practice type comments have also been adopted for class variables and instance variables, this PEP also discusses the use of type annotations for those variables. Rationale Although type comments work well enough, the fact that they’re expressed through comments has some downsides: Text editors often highlight comments differently from type annotations. There’s no way to annotate the type of an undefined variable; one needs to initialize it to None (e.g. a = None # type: int ).

Variables annotated in a conditional branch are difficult to read: if some_value : my_var = function () # type: Logger else : my_var = another_function () # Why isn't there a type here? Since type comments aren’t actually part of the language, if a Python script wants to parse them, it requires a custom parser instead of just using ast . Type comments are used a lot in typeshed. Migrating typeshed to use the variable annotation syntax instead of type comments would improve readability of stubs.

In situations where normal comments and type comments are used together, it is difficult to distinguish them: path = None # type: Optional[str] # Path to module source It’s impossible to retrieve the annotations at runtime outside of attempting to find the module’s source code and parse it at runtime, which is inelegant, to say the least. The majority of these issues can be alleviated by making the syntax a core part of the language.

Moreover, having a dedicated annotation syntax for class and instance variables (in addition to method annotations) will pave the way to static duck-typing as a complement to nominal typing defined by PEP 484 . Non-goals While the proposal is accompanied by an extension of the typing.get_type_hints standard library function for runtime retrieval of annotations, variable annotations are not designed for runtime type checking.

Third party packages will have to be developed to implement such functionality. It should also 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. Type annotations should not be confused with variable declarations in statically typed languages. The goal of annotation syntax is to provide an easy way to specify structured type metadata for third party tools.

This PEP does not require type checkers to change their type checking rules. It merely provides a more readable syntax to replace type comments. Specification Type annotation can be added to an assignment statement or to a single expression indicating the desired type of the annotation target to a third party type checker: my_var : int my_var = 5 # Passes type check. other_var : int = 'a' # Flagged as error by type checker, # but OK at runtime.

This syntax does not introduce any new semantics beyond PEP 484 , so that the following three statements are equivalent: var = value # type: annotation var : annotation ; var = value var : annotation = value Below we specify the syntax of type annotations in different contexts and their runtime effects. We also suggest how type checkers might interpret annotations, but compliance to these suggestions is not mandatory. (This is in line with the attitude towards compliance in PEP 484 .) Global and local variable annotations The types of locals and globals can be annotated as follows: some_number : int # variable without initial value some_list : List [ int ] = [] # variable with initial value Being able to omit the initial value allows for easier typing of variables assigned in conditional branches: sane_world : bool if 2 + 2 == 4 : sane_world = True else : sane_world = False Note that, although the syntax does allow tuple packing, it does not allow one to annotate the types of variables when tuple unpacking is used: # Tuple packing with variable annotation syntax t : Tuple [ int , ... ] = ( 1 , 2 , 3 ) # or t : Tuple [ int , ... ] = 1 , 2 , 3 # This only works in Python 3.8+ # Tuple unpacking with variable annotation syntax header : str kind : int body : Optional [ List [ str ]] header , kind , body = message Omitting the initial value leaves the variable uninitialized: a : int print ( a ) # raises NameError However, annotating a local variable will cause the interpreter to always make it a local: def f (): a : int print ( a ) # raises UnboundLocalError # Commenting out the a: int makes it a NameError. as if the code were: def f (): if False : a = 0 print ( a ) # raises UnboundLocalError Duplicate type annotations will be ignored.

However, static type checkers may issue a warning for annotations of the same variable by a different type: a : int a : str # Static type checker may or may not warn about this. Class and instance variable annotations Type annotations can also be used to annotate class and instance variables in class bodies and methods. In particular, the value-less notation a: int allows one to annotate instance variables that should be initialized in __init__ or __new__ .

The proposed syntax is as follows: class BasicStarship : captain : str = 'Picard' # instance variable with default damage : int # instance variable without default stats : ClassVar [ Dict [ str , int ]] = {} # class variable Here ClassVar is a special class defined b

The rest of this page is on the live site.