CINXE.COM

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta name="color-scheme" content="light dark"> <title>PEP 526 – Syntax for Variable Annotations | peps.python.org</title> <link rel="shortcut icon" href="../_static/py.png"> <link rel="canonical" href="https://peps.python.org/pep-0526/"> <link rel="stylesheet" href="../_static/style.css" type="text/css"> <link rel="stylesheet" href="../_static/mq.css" type="text/css"> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" media="(prefers-color-scheme: light)" id="pyg-light"> <link rel="stylesheet" href="../_static/pygments_dark.css" type="text/css" media="(prefers-color-scheme: dark)" id="pyg-dark"> <link rel="alternate" type="application/rss+xml" title="Latest PEPs" href="https://peps.python.org/peps.rss"> <meta property="og:title" content='PEP 526 – Syntax for Variable Annotations | peps.python.org'> <meta property="og:description" content="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:"> <meta property="og:type" content="website"> <meta property="og:url" content="https://peps.python.org/pep-0526/"> <meta property="og:site_name" content="Python Enhancement Proposals (PEPs)"> <meta property="og:image" content="https://peps.python.org/_static/og-image.png"> <meta property="og:image:alt" content="Python PEPs"> <meta property="og:image:width" content="200"> <meta property="og:image:height" content="200"> <meta name="description" content="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:"> <meta name="theme-color" content="#3776ab"> </head> <body> <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> <symbol id="svg-sun-half" viewBox="0 0 24 24" pointer-events="all"> <title>Following system colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="9"></circle> <path d="M12 3v18m0-12l4.65-4.65M12 14.3l7.37-7.37M12 19.6l8.85-8.85"></path> </svg> </symbol> <symbol id="svg-moon" viewBox="0 0 24 24" pointer-events="all"> <title>Selected dark colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <path stroke="none" d="M0 0h24v24H0z" fill="none"></path> <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z"></path> </svg> </symbol> <symbol id="svg-sun" viewBox="0 0 24 24" pointer-events="all"> <title>Selected light colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="5"></circle> <line x1="12" y1="1" x2="12" y2="3"></line> <line x1="12" y1="21" x2="12" y2="23"></line> <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line> <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line> <line x1="1" y1="12" x2="3" y2="12"></line> <line x1="21" y1="12" x2="23" y2="12"></line> <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line> <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line> </svg> </symbol> </svg> <script> document.documentElement.dataset.colour_scheme = localStorage.getItem("colour_scheme") || "auto" </script> <section id="pep-page-section"> <header> <h1>Python Enhancement Proposals</h1> <ul class="breadcrumbs"> <li><a href="https://www.python.org/" title="The Python Programming Language">Python</a> » </li> <li><a href="../pep-0000/">PEP Index</a> » </li> <li>PEP 526</li> </ul> <button id="colour-scheme-cycler" onClick="setColourScheme(nextColourScheme())"> <svg aria-hidden="true" class="colour-scheme-icon-when-auto"><use href="#svg-sun-half"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-dark"><use href="#svg-moon"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-light"><use href="#svg-sun"></use></svg> Toggle light / dark / auto colour theme </button> </header> <article> <section id="pep-content"> <h1 class="page-title">PEP 526 – Syntax for Variable Annotations</h1> <dl class="rfc2822 field-list simple"> <dt class="field-odd">Author:</dt> <dd class="field-odd">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></dd> <dt class="field-even">Status:</dt> <dd class="field-even"><abbr title="Accepted and implementation complete, or no longer active">Final</abbr></dd> <dt class="field-odd">Type:</dt> <dd class="field-odd"><abbr title="Normative PEP with a new feature for Python, implementation change for CPython or interoperability standard for the ecosystem">Standards Track</abbr></dd> <dt class="field-even">Topic:</dt> <dd class="field-even"><a class="reference external" href="../topic/typing/">Typing</a></dd> <dt class="field-odd">Created:</dt> <dd class="field-odd">09-Aug-2016</dd> <dt class="field-even">Python-Version:</dt> <dd class="field-even">3.6</dd> <dt class="field-odd">Post-History:</dt> <dd class="field-odd">30-Aug-2016, 02-Sep-2016</dd> <dt class="field-even">Resolution:</dt> <dd class="field-even"><a class="reference external" href="https://mail.python.org/pipermail/python-dev/2016-September/146282.html">Python-Dev message</a></dd> </dl> <hr class="docutils" /> <section id="contents"> <details><summary>Table of Contents</summary><ul class="simple"> <li><a class="reference internal" href="#status">Status</a></li> <li><a class="reference internal" href="#notice-for-reviewers">Notice for Reviewers</a></li> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#rationale">Rationale</a><ul> <li><a class="reference internal" href="#non-goals">Non-goals</a></li> </ul> </li> <li><a class="reference internal" href="#specification">Specification</a><ul> <li><a class="reference internal" href="#global-and-local-variable-annotations">Global and local variable annotations</a></li> <li><a class="reference internal" href="#class-and-instance-variable-annotations">Class and instance variable annotations</a></li> <li><a class="reference internal" href="#annotating-expressions">Annotating expressions</a></li> <li><a class="reference internal" href="#where-annotations-aren-t-allowed">Where annotations aren’t allowed</a></li> <li><a class="reference internal" href="#variable-annotations-in-stub-files">Variable annotations in stub files</a></li> <li><a class="reference internal" href="#preferred-coding-style-for-variable-annotations">Preferred coding style for variable annotations</a></li> </ul> </li> <li><a class="reference internal" href="#changes-to-standard-library-and-documentation">Changes to Standard Library and Documentation</a></li> <li><a class="reference internal" href="#runtime-effects-of-type-annotations">Runtime Effects of Type Annotations</a><ul> <li><a class="reference internal" href="#other-uses-of-annotations">Other uses of annotations</a></li> </ul> </li> <li><a class="reference internal" href="#rejected-postponed-proposals">Rejected/Postponed Proposals</a></li> <li><a class="reference internal" href="#backwards-compatibility">Backwards Compatibility</a></li> <li><a class="reference internal" href="#implementation">Implementation</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> </details></section> <div class="pep-banner canonical-typing-spec sticky-banner admonition important"> Important This PEP is a historical document: see <a class="reference external" href="https://docs.python.org/3/reference/simple_stmts.html#annassign" title="(in Python v3.13)">Annotated assignment statements</a>, <a class="reference external" href="https://typing.readthedocs.io/en/latest/spec/class-compat.html#classvar" title="(in typing)">ClassVar</a> and <a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.ClassVar" title="(in Python v3.13)"><code class="xref py py-data docutils literal notranslate">typing.ClassVar</code></a> for up-to-date specs and documentation. Canonical typing specs are maintained at the <a class="reference external" href="https://typing.readthedocs.io/en/latest/spec/">typing specs site</a>; runtime typing behaviour is described in the CPython documentation. × See the <a class="reference external" href="https://typing.readthedocs.io/en/latest/spec/meta.html">typing specification update process</a> for how to propose changes to the typing spec. </div> <section id="status"> <h2><a class="toc-backref" href="#status" role="doc-backlink">Status</a></h2> This PEP has been provisionally accepted by the BDFL. See the acceptance message for more color: <a class="reference external" href="https://mail.python.org/pipermail/python-dev/2016-September/146282.html">https://mail.python.org/pipermail/python-dev/2016-September/146282.html</a> </section> <section id="notice-for-reviewers"> <h2><a class="toc-backref" href="#notice-for-reviewers" role="doc-backlink">Notice for Reviewers</a></h2> This PEP was drafted in a separate repo: <a class="reference external" href="https://github.com/phouse512/peps/tree/pep-0526">https://github.com/phouse512/peps/tree/pep-0526</a>. There was preliminary discussion on python-ideas and at <a class="reference external" href="https://github.com/python/typing/issues/258">https://github.com/python/typing/issues/258</a>. Before you bring up an objection in a public forum please at least read the summary of <a class="reference internal" href="#pep-526-rejected">rejected ideas</a> listed at the end of this PEP. </section> <section id="abstract"> <h2><a class="toc-backref" href="#abstract" role="doc-backlink">Abstract</a></h2> <a class="pep reference internal" href="../pep-0484/" title="PEP 484 – Type Hints">PEP 484</a> 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: <div class="highlight-default notranslate"><div class="highlight"><pre># '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] </pre></div> </div> 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: <div class="highlight-default notranslate"><div class="highlight"><pre>primes: List[int] = [] captain: str # Note: no initial value! class Starship: stats: ClassVar[Dict[str, int]] = {} </pre></div> </div> <a class="pep reference internal" href="../pep-0484/" title="PEP 484 – Type Hints">PEP 484</a> 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. </section> <section id="rationale"> <h2><a class="toc-backref" href="#rationale" role="doc-backlink">Rationale</a></h2> Although type comments work well enough, the fact that they’re expressed through comments has some downsides: <ul> <li>Text editors often highlight comments differently from type annotations.</li> <li>There’s no way to annotate the type of an undefined variable; one needs to initialize it to <code class="docutils literal notranslate">None</code> (e.g. <code class="docutils literal notranslate">a = None # type: int</code>).</li> <li>Variables annotated in a conditional branch are difficult to read:<div class="highlight-default notranslate"><div class="highlight"><pre>if some_value: my_var = function() # type: Logger else: my_var = another_function() # Why isn't there a type here? </pre></div> </div> </li> <li>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 <code class="docutils literal notranslate">ast</code>.</li> <li>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.</li> <li>In situations where normal comments and type comments are used together, it is difficult to distinguish them:<div class="highlight-default notranslate"><div class="highlight"><pre>path = None # type: Optional[str] # Path to module source </pre></div> </div> </li> <li>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.</li> </ul> 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 <a class="pep reference internal" href="../pep-0484/" title="PEP 484 – Type Hints">PEP 484</a>. <section id="non-goals"> <h3><a class="toc-backref" href="#non-goals" role="doc-backlink">Non-goals</a></h3> While the proposal is accompanied by an extension of the <code class="docutils literal notranslate">typing.get_type_hints</code> 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. </section> </section> <section id="specification"> <h2><a class="toc-backref" href="#specification" role="doc-backlink">Specification</a></h2> 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: <div class="highlight-default notranslate"><div class="highlight"><pre>my_var: int my_var = 5 # Passes type check. other_var: int = 'a' # Flagged as error by type checker, # but OK at runtime. </pre></div> </div> This syntax does not introduce any new semantics beyond <a class="pep reference internal" href="../pep-0484/" title="PEP 484 – Type Hints">PEP 484</a>, so that the following three statements are equivalent: <div class="highlight-default notranslate"><div class="highlight"><pre>var = value # type: annotation var: annotation; var = value var: annotation = value </pre></div> </div> 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 <a class="pep reference internal" href="../pep-0484/" title="PEP 484 – Type Hints">PEP 484</a>.) <section id="global-and-local-variable-annotations"> <h3><a class="toc-backref" href="#global-and-local-variable-annotations" role="doc-backlink">Global and local variable annotations</a></h3> The types of locals and globals can be annotated as follows: <div class="highlight-default notranslate"><div class="highlight"><pre>some_number: int # variable without initial value some_list: List[int] = [] # variable with initial value </pre></div> </div> Being able to omit the initial value allows for easier typing of variables assigned in conditional branches: <div class="highlight-default notranslate"><div class="highlight"><pre>sane_world: bool if 2+2 == 4: sane_world = True else: sane_world = False </pre></div> </div> 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: <div class="highlight-default notranslate"><div class="highlight"><pre># 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 </pre></div> </div> Omitting the initial value leaves the variable uninitialized: <div class="highlight-default notranslate"><div class="highlight"><pre>a: int print(a) # raises NameError </pre></div> </div> However, annotating a local variable will cause the interpreter to always make it a local: <div class="highlight-default notranslate"><div class="highlight"><pre>def f(): a: int print(a) # raises UnboundLocalError # Commenting out the a: int makes it a NameError. </pre></div> </div> as if the code were: <div class="highlight-default notranslate"><div class="highlight"><pre>def f(): if False: a = 0 print(a) # raises UnboundLocalError </pre></div> </div> Duplicate type annotations will be ignored. However, static type checkers may issue a warning for annotations of the same variable by a different type: <div class="highlight-default notranslate"><div class="highlight"><pre>a: int a: str # Static type checker may or may not warn about this. </pre></div> </div> </section> <section id="class-and-instance-variable-annotations"> <h3><a class="toc-backref" href="#class-and-instance-variable-annotations" role="doc-backlink">Class and instance variable annotations</a></h3> Type annotations can also be used to annotate class and instance variables in class bodies and methods. In particular, the value-less notation <code class="docutils literal notranslate">a: int</code> allows one to annotate instance variables that should be initialized in <code class="docutils literal notranslate">__init__</code> or <code class="docutils literal notranslate">__new__</code>. The proposed syntax is as follows: <div class="highlight-default notranslate"><div class="highlight"><pre>class BasicStarship: captain: str = 'Picard' # instance variable with default damage: int # instance variable without default stats: ClassVar[Dict[str, int]] = {} # class variable </pre></div> </div> Here <code class="docutils literal notranslate">ClassVar</code> is a special class defined by the typing module that indicates to the static type checker that this variable should not be set on instances. Note that a <code class="docutils literal notranslate">ClassVar</code> parameter cannot include any type variables, regardless of the level of nesting: <code class="docutils literal notranslate">ClassVar[T]</code> and <code class="docutils literal notranslate">ClassVar[List[Set[T]]]</code> are both invalid if <code class="docutils literal notranslate">T</code> is a type variable. This could be illustrated with a more detailed example. In this class: <div class="highlight-default notranslate"><div class="highlight"><pre>class Starship: captain = 'Picard' stats = {} def __init__(self, damage, captain=None): self.damage = damage if captain: self.captain = captain # Else keep the default def hit(self): Starship.stats['hits'] = Starship.stats.get('hits', 0) + 1 </pre></div> </div> <code class="docutils literal notranslate">stats</code> is intended to be a class variable (keeping track of many different per-game statistics), while <code class="docutils literal notranslate">captain</code> is an instance variable with a default value set in the class. This difference might not be seen by a type checker: both get initialized in the class, but <code class="docutils literal notranslate">captain</code> serves only as a convenient default value for the instance variable, while <code class="docutils literal notranslate">stats</code> is truly a class variable – it is intended to be shared by all instances. Since both variables happen to be initialized at the class level, it is useful to distinguish them by marking class variables as annotated with types wrapped in <code class="docutils literal notranslate">ClassVar[...]</code>. In this way a type checker may flag accidental assignments to attributes with the same name on instances. For example, annotating the discussed class: <div class="highlight-default notranslate"><div class="highlight"><pre>class Starship: captain: str = 'Picard' damage: int stats: ClassVar[Dict[str, int]] = {} def __init__(self, damage: int, captain: str = None): self.damage = damage if captain: self.captain = captain # Else keep the default def hit(self): Starship.stats['hits'] = Starship.stats.get('hits', 0) + 1 enterprise_d = Starship(3000) enterprise_d.stats = {} # Flagged as error by a type checker Starship.stats = {} # This is OK </pre></div> </div> As a matter of convenience (and convention), instance variables can be annotated in <code class="docutils literal notranslate">__init__</code> or other methods, rather than in the class: <div class="highlight-default notranslate"><div class="highlight"><pre>from typing import Generic, TypeVar T = TypeVar('T') class Box(Generic[T]): def __init__(self, content): self.content: T = content </pre></div> </div> </section> <section id="annotating-expressions"> <h3><a class="toc-backref" href="#annotating-expressions" role="doc-backlink">Annotating expressions</a></h3> The target of the annotation can be any valid single assignment target, at least syntactically (it is up to the type checker what to do with this): <div class="highlight-default notranslate"><div class="highlight"><pre>class Cls: pass c = Cls() c.x: int = 0 # Annotates c.x with int. c.y: int # Annotates c.y with int. d = {} d['a']: int = 0 # Annotates d['a'] with int. d['b']: int # Annotates d['b'] with int. </pre></div> </div> Note that even a parenthesized name is considered an expression, not a simple name: <div class="highlight-default notranslate"><div class="highlight"><pre>(x): int # Annotates x with int, (x) treated as expression by compiler. (y): int = 0 # Same situation here. </pre></div> </div> </section> <section id="where-annotations-aren-t-allowed"> <h3><a class="toc-backref" href="#where-annotations-aren-t-allowed" role="doc-backlink">Where annotations aren’t allowed</a></h3> It is illegal to attempt to annotate variables subject to <code class="docutils literal notranslate">global</code> or <code class="docutils literal notranslate">nonlocal</code> in the same function scope: <div class="highlight-default notranslate"><div class="highlight"><pre>def f(): global x: int # SyntaxError def g(): x: int # Also a SyntaxError global x </pre></div> </div> The reason is that <code class="docutils literal notranslate">global</code> and <code class="docutils literal notranslate">nonlocal</code> don’t own variables; therefore, the type annotations belong in the scope owning the variable. Only single assignment targets and single right hand side values are allowed. In addition, one cannot annotate variables used in a <code class="docutils literal notranslate">for</code> or <code class="docutils literal notranslate">with</code> statement; they can be annotated ahead of time, in a similar manner to tuple unpacking: <div class="highlight-default notranslate"><div class="highlight"><pre>a: int for a in my_iter: ... f: MyFile with myfunc() as f: ... </pre></div> </div> </section> <section id="variable-annotations-in-stub-files"> <h3><a class="toc-backref" href="#variable-annotations-in-stub-files" role="doc-backlink">Variable annotations in stub files</a></h3> As variable annotations are more readable than type comments, they are preferred in stub files for all versions of Python, including Python 2.7. Note that stub files are not executed by Python interpreters, and therefore using variable annotations will not lead to errors. Type checkers should support variable annotations in stubs for all versions of Python. For example: <div class="highlight-default notranslate"><div class="highlight"><pre># file lib.pyi ADDRESS: unicode = ... class Error: cause: Union[str, unicode] </pre></div> </div> </section> <section id="preferred-coding-style-for-variable-annotations"> <h3><a class="toc-backref" href="#preferred-coding-style-for-variable-annotations" role="doc-backlink">Preferred coding style for variable annotations</a></h3> Annotations for module level variables, class and instance variables, and local variables should have a single space after corresponding colon. There should be no space before the colon. If an assignment has right hand side, then the equality sign should have exactly one space on both sides. Examples: <ul> <li>Yes:<div class="highlight-default notranslate"><div class="highlight"><pre>code: int class Point: coords: Tuple[int, int] label: str = '<unknown>' </pre></div> </div> </li> <li>No:<div class="highlight-default notranslate"><div class="highlight"><pre>code:int # No space after colon code : int # Space before colon class Test: result: int=0 # No spaces around equality sign </pre></div> </div> </li> </ul> </section> </section> <section id="changes-to-standard-library-and-documentation"> <h2><a class="toc-backref" href="#changes-to-standard-library-and-documentation" role="doc-backlink">Changes to Standard Library and Documentation</a></h2> <ul class="simple"> <li>A new covariant type <code class="docutils literal notranslate">ClassVar[T_co]</code> is added to the <code class="docutils literal notranslate">typing</code> module. It accepts only a single argument that should be a valid type, and is used to annotate class variables that should not be set on class instances. This restriction is ensured by static checkers, but not at runtime. See the <a class="reference internal" href="#classvar">classvar</a> section for examples and explanations for the usage of <code class="docutils literal notranslate">ClassVar</code>, and see the <a class="reference internal" href="#pep-526-rejected">rejected</a> section for more information on the reasoning behind <code class="docutils literal notranslate">ClassVar</code>.</li> <li>Function <code class="docutils literal notranslate">get_type_hints</code> in the <code class="docutils literal notranslate">typing</code> module will be extended, so that one can retrieve type annotations at runtime from modules and classes as well as functions. Annotations are returned as a dictionary mapping from variable or arguments to their type hints with forward references evaluated. For classes it returns a mapping (perhaps <code class="docutils literal notranslate">collections.ChainMap</code>) constructed from annotations in method resolution order.</li> <li>Recommended guidelines for using annotations will be added to the documentation, containing a pedagogical recapitulation of specifications described in this PEP and in <a class="pep reference internal" href="../pep-0484/" title="PEP 484 – Type Hints">PEP 484</a>. In addition, a helper script for translating type comments into type annotations will be published separately from the standard library.</li> </ul> </section> <section id="runtime-effects-of-type-annotations"> <h2><a class="toc-backref" href="#runtime-effects-of-type-annotations" role="doc-backlink">Runtime Effects of Type Annotations</a></h2> Annotating a local variable will cause the interpreter to treat it as a local, even if it was never assigned to. Annotations for local variables will not be evaluated: <div class="highlight-default notranslate"><div class="highlight"><pre>def f(): x: NonexistentName # No error. </pre></div> </div> However, if it is at a module or class level, then the type will be evaluated: <div class="highlight-default notranslate"><div class="highlight"><pre>x: NonexistentName # Error! class X: var: NonexistentName # Error! </pre></div> </div> In addition, at the module or class level, if the item being annotated is a simple name, then it and the annotation will be stored in the <code class="docutils literal notranslate">__annotations__</code> attribute of that module or class (mangled if private) as an ordered mapping from names to evaluated annotations. Here is an example: <div class="highlight-default notranslate"><div class="highlight"><pre>from typing import Dict class Player: ... players: Dict[str, Player] __points: int print(__annotations__) # prints: {'players': typing.Dict[str, __main__.Player], # '_Player__points': <class 'int'>} </pre></div> </div> <code class="docutils literal notranslate">__annotations__</code> is writable, so this is permitted: <div class="highlight-default notranslate"><div class="highlight"><pre>__annotations__['s'] = str </pre></div> </div> But attempting to update <code class="docutils literal notranslate">__annotations__</code> to something other than an ordered mapping may result in a TypeError: <div class="highlight-default notranslate"><div class="highlight"><pre>class C: __annotations__ = 42 x: int = 5 # raises TypeError </pre></div> </div> (Note that the assignment to <code class="docutils literal notranslate">__annotations__</code>, which is the culprit, is accepted by the Python interpreter without questioning it – but the subsequent type annotation expects it to be a <code class="docutils literal notranslate">MutableMapping</code> and will fail.) The recommended way of getting annotations at runtime is by using <code class="docutils literal notranslate">typing.get_type_hints</code> function; as with all dunder attributes, any undocumented use of <code class="docutils literal notranslate">__annotations__</code> is subject to breakage without warning: <div class="highlight-default notranslate"><div class="highlight"><pre>from typing import Dict, ClassVar, get_type_hints class Starship: hitpoints: int = 50 stats: ClassVar[Dict[str, int]] = {} shield: int = 100 captain: str def __init__(self, captain: str) -> None: ... assert get_type_hints(Starship) == {'hitpoints': int, 'stats': ClassVar[Dict[str, int]], 'shield': int, 'captain': str} assert get_type_hints(Starship.__init__) == {'captain': str, 'return': None} </pre></div> </div> Note that if annotations are not found statically, then the <code class="docutils literal notranslate">__annotations__</code> dictionary is not created at all. Also the value of having annotations available locally does not offset the cost of having to create and populate the annotations dictionary on every function call. Therefore, annotations at function level are not evaluated and not stored. <section id="other-uses-of-annotations"> <h3><a class="toc-backref" href="#other-uses-of-annotations" role="doc-backlink">Other uses of annotations</a></h3> While Python with this PEP will not object to: <div class="highlight-default notranslate"><div class="highlight"><pre>alice: 'well done' = 'A+' bob: 'what a shame' = 'F-' </pre></div> </div> since it will not care about the type annotation beyond “it evaluates without raising”, a type checker that encounters it will flag it, unless disabled with <code class="docutils literal notranslate"># type: ignore</code> or <code class="docutils literal notranslate">@no_type_check</code>. However, since Python won’t care what the “type” is, if the above snippet is at the global level or in a class, <code class="docutils literal notranslate">__annotations__</code> will include <code class="docutils literal notranslate">{'alice': 'well done', 'bob': 'what a shame'}</code>. These stored annotations might be used for other purposes, but with this PEP we explicitly recommend type hinting as the preferred use of annotations. </section> </section> <section id="rejected-postponed-proposals"> <h2><a class="toc-backref" href="#rejected-postponed-proposals" role="doc-backlink">Rejected/Postponed Proposals</a></h2> <ul> <li>Should we introduce variable annotations at all? Variable annotations have already been around for almost two years in the form of type comments, sanctioned by <a class="pep reference internal" href="../pep-0484/" title="PEP 484 – Type Hints">PEP 484</a>. They are extensively used by third party type checkers (mypy, pytype, PyCharm, etc.) and by projects using the type checkers. However, the comment syntax has many downsides listed in Rationale. This PEP is not about the need for type annotations, it is about what should be the syntax for such annotations.</li> <li>Introduce a new keyword: The choice of a good keyword is hard, e.g. it can’t be <code class="docutils literal notranslate">var</code> because that is way too common a variable name, and it can’t be <code class="docutils literal notranslate">local</code> if we want to use it for class variables or globals. Second, no matter what we choose, we’d still need a <code class="docutils literal notranslate">__future__</code> import.</li> <li>Use <code class="docutils literal notranslate">def</code> as a keyword: The proposal would be:<div class="highlight-default notranslate"><div class="highlight"><pre>def primes: List[int] = [] def captain: str </pre></div> </div> The problem with this is that <code class="docutils literal notranslate">def</code> means “define a function” to generations of Python programmers (and tools!), and using it also to define variables does not increase clarity. (Though this is of course subjective.) </li> <li>Use function based syntax: It was proposed to annotate types of variables using <code class="docutils literal notranslate">var = cast(annotation[, value])</code>. Although this syntax alleviates some problems with type comments like absence of the annotation in AST, it does not solve other problems such as readability and it introduces possible runtime overhead.</li> <li>Allow type annotations for tuple unpacking: This causes ambiguity: it’s not clear what this statement means:<div class="highlight-default notranslate"><div class="highlight"><pre>x, y: T </pre></div> </div> Are <code class="docutils literal notranslate">x</code> and <code class="docutils literal notranslate">y</code> both of type <code class="docutils literal notranslate">T</code>, or do we expect <code class="docutils literal notranslate">T</code> to be a tuple type of two items that are distributed over <code class="docutils literal notranslate">x</code> and <code class="docutils literal notranslate">y</code>, or perhaps <code class="docutils literal notranslate">x</code> has type <code class="docutils literal notranslate">Any</code> and <code class="docutils literal notranslate">y</code> has type <code class="docutils literal notranslate">T</code>? (The latter is what this would mean if this occurred in a function signature.) Rather than leave the (human) reader guessing, we forbid this, at least for now. </li> <li>Parenthesized form <code class="docutils literal notranslate">(var: type)</code> for annotations: It was brought up on python-ideas as a remedy for the above-mentioned ambiguity, but it was rejected since such syntax would be hairy, the benefits are slight, and the readability would be poor.</li> <li>Allow annotations in chained assignments: This has problems of ambiguity and readability similar to tuple unpacking, for example in:<div class="highlight-default notranslate"><div class="highlight"><pre>x: int = y = 1 z = w: int = 1 </pre></div> </div> it is ambiguous, what should the types of <code class="docutils literal notranslate">y</code> and <code class="docutils literal notranslate">z</code> be? Also the second line is difficult to parse. </li> <li>Allow annotations in <code class="docutils literal notranslate">with</code> and <code class="docutils literal notranslate">for</code> statement: This was rejected because in <code class="docutils literal notranslate">for</code> it would make it hard to spot the actual iterable, and in <code class="docutils literal notranslate">with</code> it would confuse the CPython’s LL(1) parser.</li> <li>Evaluate local annotations at function definition time: This has been rejected by Guido because the placement of the annotation strongly suggests that it’s in the same scope as the surrounding code.</li> <li>Store variable annotations also in function scope: The value of having the annotations available locally is just not enough to significantly offset the cost of creating and populating the dictionary on each function call.</li> <li>Initialize variables annotated without assignment: It was proposed on python-ideas to initialize <code class="docutils literal notranslate">x</code> in <code class="docutils literal notranslate">x: int</code> to <code class="docutils literal notranslate">None</code> or to an additional special constant like Javascript’s <code class="docutils literal notranslate">undefined</code>. However, adding yet another singleton value to the language would needed to be checked for everywhere in the code. Therefore, Guido just said plain “No” to this.</li> <li>Add also <code class="docutils literal notranslate">InstanceVar</code> to the typing module: This is redundant because instance variables are way more common than class variables. The more common usage deserves to be the default.</li> <li>Allow instance variable annotations only in methods: The problem is that many <code class="docutils literal notranslate">__init__</code> methods do a lot of things besides initializing instance variables, and it would be harder (for a human) to find all the instance variable annotations. And sometimes <code class="docutils literal notranslate">__init__</code> is factored into more helper methods so it’s even harder to chase them down. Putting the instance variable annotations together in the class makes it easier to find them, and helps a first-time reader of the code.</li> <li>Use syntax <code class="docutils literal notranslate">x: class t = v</code> for class variables: This would require a more complicated parser and the <code class="docutils literal notranslate">class</code> keyword would confuse simple-minded syntax highlighters. Anyway we need to have <code class="docutils literal notranslate">ClassVar</code> store class variables to <code class="docutils literal notranslate">__annotations__</code>, so a simpler syntax was chosen.</li> <li>Forget about <code class="docutils literal notranslate">ClassVar</code> altogether: This was proposed since mypy seems to be getting along fine without a way to distinguish between class and instance variables. But a type checker can do useful things with the extra information, for example flag accidental assignments to a class variable via the instance (which would create an instance variable shadowing the class variable). It could also flag instance variables with mutable defaults, a well-known hazard.</li> <li>Use <code class="docutils literal notranslate">ClassAttr</code> instead of <code class="docutils literal notranslate">ClassVar</code>: The main reason why <code class="docutils literal notranslate">ClassVar</code> is better is following: many things are class attributes, e.g. methods, descriptors, etc. But only specific attributes are conceptually class variables (or maybe constants).</li> <li>Do not evaluate annotations, treat them as strings: This would be inconsistent with the behavior of function annotations that are always evaluated. Although this might be reconsidered in future, it was decided in <a class="pep reference internal" href="../pep-0484/" title="PEP 484 – Type Hints">PEP 484</a> that this would have to be a separate PEP.</li> <li>Annotate variable types in class docstring: Many projects already use various docstring conventions, often without much consistency and generally without conforming to the <a class="pep reference internal" href="../pep-0484/" title="PEP 484 – Type Hints">PEP 484</a> annotation syntax yet. Also this would require a special sophisticated parser. This, in turn, would defeat the purpose of the PEP – collaborating with the third party type checking tools.</li> <li>Implement <code class="docutils literal notranslate">__annotations__</code> as a descriptor: This was proposed to prohibit setting <code class="docutils literal notranslate">__annotations__</code> to something non-dictionary or non-None. Guido has rejected this idea as unnecessary; instead a TypeError will be raised if an attempt is made to update <code class="docutils literal notranslate">__annotations__</code> when it is anything other than a mapping.</li> <li>Treating bare annotations the same as global or nonlocal: The rejected proposal would prefer that the presence of an annotation without assignment in a function body should not involve any evaluation. In contrast, the PEP implies that if the target is more complex than a single name, its “left-hand part” should be evaluated at the point where it occurs in the function body, just to enforce that it is defined. For example, in this example:<div class="highlight-default notranslate"><div class="highlight"><pre>def foo(self): slef.name: str </pre></div> </div> the name <code class="docutils literal notranslate">slef</code> should be evaluated, just so that if it is not defined (as is likely in this example :-), the error will be caught at runtime. This is more in line with what happens when there is an initial value, and thus is expected to lead to fewer surprises. (Also note that if the target was <code class="docutils literal notranslate">self.name</code> (this time correctly spelled :-), an optimizing compiler has no obligation to evaluate <code class="docutils literal notranslate">self</code> as long as it can prove that it will definitely be defined.) </li> </ul> </section> <section id="backwards-compatibility"> <h2><a class="toc-backref" href="#backwards-compatibility" role="doc-backlink">Backwards Compatibility</a></h2> This PEP is fully backwards compatible. </section> <section id="implementation"> <h2><a class="toc-backref" href="#implementation" role="doc-backlink">Implementation</a></h2> An implementation for Python 3.6 can be found <a class="reference external" href="https://github.com/python/cpython/commit/f8cb8a16a3">on GitHub</a>. </section> <section id="copyright"> <h2><a class="toc-backref" href="#copyright" role="doc-backlink">Copyright</a></h2> This document has been placed in the public domain. </section> </section> <hr class="docutils" /> Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0526.rst">https://github.com/python/peps/blob/main/peps/pep-0526.rst</a> Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0526.rst">2025-02-01 08:59:27 GMT</a> </article> <nav id="pep-sidebar"> <h2>Contents</h2> <ul> <li><a class="reference internal" href="#status">Status</a></li> <li><a class="reference internal" href="#notice-for-reviewers">Notice for Reviewers</a></li> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#rationale">Rationale</a><ul> <li><a class="reference internal" href="#non-goals">Non-goals</a></li> </ul> </li> <li><a class="reference internal" href="#specification">Specification</a><ul> <li><a class="reference internal" href="#global-and-local-variable-annotations">Global and local variable annotations</a></li> <li><a class="reference internal" href="#class-and-instance-variable-annotations">Class and instance variable annotations</a></li> <li><a class="reference internal" href="#annotating-expressions">Annotating expressions</a></li> <li><a class="reference internal" href="#where-annotations-aren-t-allowed">Where annotations aren’t allowed</a></li> <li><a class="reference internal" href="#variable-annotations-in-stub-files">Variable annotations in stub files</a></li> <li><a class="reference internal" href="#preferred-coding-style-for-variable-annotations">Preferred coding style for variable annotations</a></li> </ul> </li> <li><a class="reference internal" href="#changes-to-standard-library-and-documentation">Changes to Standard Library and Documentation</a></li> <li><a class="reference internal" href="#runtime-effects-of-type-annotations">Runtime Effects of Type Annotations</a><ul> <li><a class="reference internal" href="#other-uses-of-annotations">Other uses of annotations</a></li> </ul> </li> <li><a class="reference internal" href="#rejected-postponed-proposals">Rejected/Postponed Proposals</a></li> <li><a class="reference internal" href="#backwards-compatibility">Backwards Compatibility</a></li> <li><a class="reference internal" href="#implementation">Implementation</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> <a id="source" href="https://github.com/python/peps/blob/main/peps/pep-0526.rst">Page Source (GitHub)</a> </nav> </section> <script src="../_static/colour_scheme.js"></script> <script src="../_static/wrap_tables.js"></script> <script src="../_static/sticky_banner.js"></script> </body> </html>