parthtamu/rag-code-assistant
0
1<!DOCTYPE html>2 3<html lang="en" data-content_root="../">4 <head>5 <meta charset="utf-8" />6 <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />7<meta property="og:title" content="typing — Support for type hints" />8<meta property="og:type" content="website" />9<meta property="og:url" content="https://docs.python.org/3/library/typing.html" />10<meta property="og:site_name" content="Python documentation" />11<meta property="og:description" content="Source code: Lib/typing.py This module provides runtime support for type hints. Consider the function below: The function surface_area_of_cube takes an argument expected to be an instance of float,..." />12<meta property="og:image:width" content="1146" />13<meta property="og:image:height" content="600" />14<meta property="og:image" content="https://docs.python.org/3.15/_images/social_previews/summary_library_typing_cafdca99.png" />15<meta property="og:image:alt" content="Source code: Lib/typing.py This module provides runtime support for type hints. Consider the function below: The function surface_area_of_cube takes an argument expected to be an instance of float,..." />16<meta name="description" content="Source code: Lib/typing.py This module provides runtime support for type hints. Consider the function below: The function surface_area_of_cube takes an argument expected to be an instance of float,..." />17<meta name="twitter:card" content="summary_large_image" />18<meta name="theme-color" content="#3776ab">19 20 <title>typing — Support for type hints — Python 3.15.0a6 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">21 22 <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />23 <link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />24 <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=89a2f22a" />25 <link rel="stylesheet" type="text/css" href="../_static/profiling-sampling-visualization.css?v=0c2600ae" />26 <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=5349f25f" />27 28 <script src="../_static/documentation_options.js?v=6b7c9ff5"></script>29 <script src="../_static/doctools.js?v=9bcbadda"></script>30 <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>31 <script src="../_static/profiling-sampling-visualization.js?v=9811ed04"></script>32 33 <script src="../_static/sidebar.js"></script>34 35 <link rel="search" type="application/opensearchdescription+xml"36 title="Search within Python 3.15.0a6 documentation"37 href="../_static/opensearch.xml"/>38 <link rel="author" title="About these documents" href="../about.html" />39 <link rel="index" title="Index" href="../genindex.html" />40 <link rel="search" title="Search" href="../search.html" />41 <link rel="copyright" title="Copyright" href="../copyright.html" />42 <link rel="next" title="pydoc — Documentation generator and online help system" href="pydoc.html" />43 <link rel="prev" title="Development Tools" href="development.html" />44 45 46 <script defer file-types="bz2,epub,zip" data-domain="docs.python.org" src="https://analytics.python.org/js/script.file-downloads.outbound-links.js"></script>47 48 <link rel="canonical" href="https://docs.python.org/3/library/typing.html">49 50 51 52 53 <style>54 @media only screen {55 table.full-width-table {56 width: 100%;57 }58 }59 </style>60<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">61 <link rel="shortcut icon" type="image/png" href="../_static/py.svg">62 <script type="text/javascript" src="../_static/copybutton.js"></script>63 <script type="text/javascript" src="../_static/menu.js"></script>64 <script type="text/javascript" src="../_static/search-focus.js"></script>65 <script type="text/javascript" src="../_static/themetoggle.js"></script> 66 <script type="text/javascript" src="../_static/rtd_switcher.js"></script>67 <meta name="readthedocs-addons-api-version" content="1">68 69 </head>70<body>71<div class="mobile-nav">72 <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"73 aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu">74 <nav class="nav-content" role="navigation">75 <label for="menuToggler" class="toggler__label">76 <span></span>77 </label>78 <span class="nav-items-wrapper">79 <a href="https://www.python.org/" class="nav-logo">80 <img src="../_static/py.svg" alt="Python logo">81 </a>82 <span class="version_switcher_placeholder"></span>83 <form role="search" class="search" action="../search.html" method="get">84 <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">85 <path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>86 </svg>87 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q">88 <input type="submit" value="Go">89 </form>90 </span>91 </nav>92 <div class="menu-wrapper">93 <nav class="menu" role="navigation" aria-label="main navigation">94 <div class="language_switcher_placeholder"></div>95 96<label class="theme-selector-label">97 Theme98 <select class="theme-selector" oninput="activateTheme(this.value)">99 <option value="auto" selected>Auto</option>100 <option value="light">Light</option>101 <option value="dark">Dark</option>102 </select>103</label>104 <div>105 <h3><a href="../contents.html">Table of Contents</a></h3>106 <ul>107<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">typing</span></code> — Support for type hints</a><ul>108<li><a class="reference internal" href="#specification-for-the-python-type-system">Specification for the Python Type System</a></li>109<li><a class="reference internal" href="#type-aliases">Type aliases</a></li>110<li><a class="reference internal" href="#newtype">NewType</a></li>111<li><a class="reference internal" href="#annotating-callable-objects">Annotating callable objects</a></li>112<li><a class="reference internal" href="#generics">Generics</a></li>113<li><a class="reference internal" href="#annotating-tuples">Annotating tuples</a></li>114<li><a class="reference internal" href="#the-type-of-class-objects">The type of class objects</a></li>115<li><a class="reference internal" href="#annotating-generators-and-coroutines">Annotating generators and coroutines</a></li>116<li><a class="reference internal" href="#user-defined-generic-types">User-defined generic types</a></li>117<li><a class="reference internal" href="#the-any-type">The <code class="xref py py-data docutils literal notranslate"><span class="pre">Any</span></code> type</a></li>118<li><a class="reference internal" href="#nominal-vs-structural-subtyping">Nominal vs structural subtyping</a></li>119<li><a class="reference internal" href="#module-contents">Module contents</a><ul>120<li><a class="reference internal" href="#special-typing-primitives">Special typing primitives</a><ul>121<li><a class="reference internal" href="#special-types">Special types</a></li>122<li><a class="reference internal" href="#special-forms">Special forms</a></li>123<li><a class="reference internal" href="#building-generic-types-and-type-aliases">Building generic types and type aliases</a></li>124<li><a class="reference internal" href="#other-special-directives">Other special directives</a></li>125</ul>126</li>127<li><a class="reference internal" href="#protocols">Protocols</a></li>128<li><a class="reference internal" href="#abcs-and-protocols-for-working-with-i-o">ABCs and Protocols for working with I/O</a></li>129<li><a class="reference internal" href="#functions-and-decorators">Functions and decorators</a></li>130<li><a class="reference internal" href="#introspection-helpers">Introspection helpers</a></li>131<li><a class="reference internal" href="#constant">Constant</a></li>132<li><a class="reference internal" href="#deprecated-aliases">Deprecated aliases</a><ul>133<li><a class="reference internal" href="#aliases-to-built-in-types">Aliases to built-in types</a></li>134<li><a class="reference internal" href="#aliases-to-types-in-collections">Aliases to types in <code class="xref py py-mod docutils literal notranslate"><span class="pre">collections</span></code></a></li>135<li><a class="reference internal" href="#aliases-to-other-concrete-types">Aliases to other concrete types</a></li>136<li><a class="reference internal" href="#aliases-to-container-abcs-in-collections-abc">Aliases to container ABCs in <code class="xref py py-mod docutils literal notranslate"><span class="pre">collections.abc</span></code></a></li>137<li><a class="reference internal" href="#aliases-to-asynchronous-abcs-in-collections-abc">Aliases to asynchronous ABCs in <code class="xref py py-mod docutils literal notranslate"><span class="pre">collections.abc</span></code></a></li>138<li><a class="reference internal" href="#aliases-to-other-abcs-in-collections-abc">Aliases to other ABCs in <code class="xref py py-mod docutils literal notranslate"><span class="pre">collections.abc</span></code></a></li>139<li><a class="reference internal" href="#aliases-to-contextlib-abcs">Aliases to <code class="xref py py-mod docutils literal notranslate"><span class="pre">contextlib</span></code> ABCs</a></li>140</ul>141</li>142</ul>143</li>144<li><a class="reference internal" href="#deprecation-timeline-of-major-features">Deprecation Timeline of Major Features</a></li>145</ul>146</li>147</ul>148 149 </div>150 <div>151 <h4>Previous topic</h4>152 <p class="topless"><a href="development.html"153 title="previous chapter">Development Tools</a></p>154 </div>155 <div>156 <h4>Next topic</h4>157 <p class="topless"><a href="pydoc.html"158 title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">pydoc</span></code> — Documentation generator and online help system</a></p>159 </div>160 <script>161 document.addEventListener('DOMContentLoaded', () => {162 const title = document.querySelector('meta[property="og:title"]').content;163 const elements = document.querySelectorAll('.improvepage');164 const pageurl = window.location.href.split('?')[0];165 elements.forEach(element => {166 const url = new URL(element.href.split('?')[0].replace("-nojs", ""));167 url.searchParams.set('pagetitle', title);168 url.searchParams.set('pageurl', pageurl);169 url.searchParams.set('pagesource', "library/typing.rst");170 element.href = url.toString();171 });172 });173 </script>174 <div role="note" aria-label="source link">175 <h3>This page</h3>176 <ul class="this-page-menu">177 <li><a href="../bugs.html">Report a bug</a></li>178 <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>179 <li>180 <a href="https://github.com/python/cpython/blob/main/Doc/library/typing.rst?plain=1"181 rel="nofollow">Show source182 </a>183 </li>184 185 </ul>186 </div>187 </nav>188 </div>189</div>190 191 192 <div class="related" role="navigation" aria-label="Related">193 <h3>Navigation</h3>194 <ul>195 <li class="right" style="margin-right: 10px">196 <a href="../genindex.html" title="General Index"197 accesskey="I">index</a></li>198 <li class="right" >199 <a href="../py-modindex.html" title="Python Module Index"200 >modules</a> |</li>201 <li class="right" >202 <a href="pydoc.html" title="pydoc — Documentation generator and online help system"203 accesskey="N">next</a> |</li>204 <li class="right" >205 <a href="development.html" title="Development Tools"206 accesskey="P">previous</a> |</li>207 208 <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>209 <li><a href="https://www.python.org/">Python</a> »</li>210 <li class="switchers">211 <div class="language_switcher_placeholder"></div>212 <div class="version_switcher_placeholder"></div>213 </li>214 <li>215 216 </li>217 <li id="cpython-language-and-version">218 <a href="../index.html">3.15.0a6 Documentation</a> »219 </li>220 221 <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>222 <li class="nav-item nav-item-2"><a href="development.html" accesskey="U">Development Tools</a> »</li>223 <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">typing</span></code> — Support for type hints</a></li>224 <li class="right">225 226 227 <div class="inline-search" role="search">228 <form class="inline-search" action="../search.html" method="get">229 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">230 <input type="submit" value="Go">231 </form>232 </div>233 |234 </li>235 <li class="right">236<label class="theme-selector-label">237 Theme238 <select class="theme-selector" oninput="activateTheme(this.value)">239 <option value="auto" selected>Auto</option>240 <option value="light">Light</option>241 <option value="dark">Dark</option>242 </select>243</label> |</li>244 245 </ul>246 </div> 247 248 <div class="document">249 <div class="documentwrapper">250 <div class="bodywrapper">251 <div class="body" role="main">252 253 <section id="typing-support-for-type-hints">254<h1><code class="xref py py-mod docutils literal notranslate"><span class="pre">typing</span></code> — Support for type hints<a class="headerlink" href="#typing-support-for-type-hints" title="Link to this heading">¶</a></h1>255<div class="versionadded" id="module-typing">256<p><span class="versionmodified added">Added in version 3.5.</span></p>257</div>258<p><strong>Source code:</strong> <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/main/Lib/typing.py">Lib/typing.py</a></p>259<div class="admonition note">260<p class="admonition-title">Note</p>261<p>The Python runtime does not enforce function and variable type annotations.262They can be used by third party tools such as <a class="reference internal" href="../glossary.html#term-static-type-checker"><span class="xref std std-term">type checkers</span></a>,263IDEs, linters, etc.</p>264</div>265<hr class="docutils" />266<p>This module provides runtime support for type hints.</p>267<p>Consider the function below:</p>268<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">surface_area_of_cube</span><span class="p">(</span><span class="n">edge_length</span><span class="p">:</span> <span class="nb">float</span><span class="p">)</span> <span class="o">-></span> <span class="nb">str</span><span class="p">:</span>269 <span class="k">return</span> <span class="sa">f</span><span class="s2">"The surface area of the cube is </span><span class="si">{</span><span class="mi">6</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="n">edge_length</span><span class="w"> </span><span class="o">**</span><span class="w"> </span><span class="mi">2</span><span class="si">}</span><span class="s2">."</span>270</pre></div>271</div>272<p>The function <code class="docutils literal notranslate"><span class="pre">surface_area_of_cube</span></code> takes an argument expected to273be an instance of <a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code></a>, as indicated by the <a class="reference internal" href="../glossary.html#term-type-hint"><span class="xref std std-term">type hint</span></a>274<code class="docutils literal notranslate"><span class="pre">edge_length:</span> <span class="pre">float</span></code>. The function is expected to return an instance275of <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>, as indicated by the <code class="docutils literal notranslate"><span class="pre">-></span> <span class="pre">str</span></code> hint.</p>276<p>While type hints can be simple classes like <a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code></a> or <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>,277they can also be more complex. The <a class="reference internal" href="#module-typing" title="typing: Support for type hints (see :pep:`484`)."><code class="xref py py-mod docutils literal notranslate"><span class="pre">typing</span></code></a> module provides a vocabulary of278more advanced type hints.</p>279<p>New features are frequently added to the <code class="docutils literal notranslate"><span class="pre">typing</span></code> module.280The <a class="extlink-pypi reference external" href="https://pypi.org/project/typing_extensions/">typing_extensions</a> package281provides backports of these new features to older versions of Python.</p>282<div class="admonition seealso">283<p class="admonition-title">See also</p>284<dl class="simple">285<dt><a class="reference external" href="https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html">Typing cheat sheet</a></dt><dd><p>A quick overview of type hints (hosted at the mypy docs)</p>286</dd>287<dt>Type System Reference section of <a class="reference external" href="https://mypy.readthedocs.io/en/stable/index.html">the mypy docs</a></dt><dd><p>The Python typing system is standardised via PEPs, so this reference288should broadly apply to most Python type checkers. (Some parts may still289be specific to mypy.)</p>290</dd>291<dt><a class="reference external" href="https://typing.python.org/en/latest/">Static Typing with Python</a></dt><dd><p>Type-checker-agnostic documentation written by the community detailing292type system features, useful typing related tools and typing best293practices.</p>294</dd>295</dl>296</div>297<section id="specification-for-the-python-type-system">298<span id="relevant-peps"></span><h2>Specification for the Python Type System<a class="headerlink" href="#specification-for-the-python-type-system" title="Link to this heading">¶</a></h2>299<p>The canonical, up-to-date specification of the Python type system can be300found at <a class="reference external" href="https://typing.python.org/en/latest/spec/index.html">Specification for the Python type system</a>.</p>301</section>302<section id="type-aliases">303<span id="id2"></span><h2>Type aliases<a class="headerlink" href="#type-aliases" title="Link to this heading">¶</a></h2>304<p>A type alias is defined using the <a class="reference internal" href="../reference/simple_stmts.html#type"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">type</span></code></a> statement, which creates305an instance of <a class="reference internal" href="#typing.TypeAliasType" title="typing.TypeAliasType"><code class="xref py py-class docutils literal notranslate"><span class="pre">TypeAliasType</span></code></a>. In this example,306<code class="docutils literal notranslate"><span class="pre">Vector</span></code> and <code class="docutils literal notranslate"><span class="pre">list[float]</span></code> will be treated equivalently by static type307checkers:</p>308<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nb">type</span> <span class="n">Vector</span> <span class="o">=</span> <span class="nb">list</span><span class="p">[</span><span class="nb">float</span><span class="p">]</span>309 310<span class="k">def</span><span class="w"> </span><span class="nf">scale</span><span class="p">(</span><span class="n">scalar</span><span class="p">:</span> <span class="nb">float</span><span class="p">,</span> <span class="n">vector</span><span class="p">:</span> <span class="n">Vector</span><span class="p">)</span> <span class="o">-></span> <span class="n">Vector</span><span class="p">:</span>311 <span class="k">return</span> <span class="p">[</span><span class="n">scalar</span> <span class="o">*</span> <span class="n">num</span> <span class="k">for</span> <span class="n">num</span> <span class="ow">in</span> <span class="n">vector</span><span class="p">]</span>312 313<span class="c1"># passes type checking; a list of floats qualifies as a Vector.</span>314<span class="n">new_vector</span> <span class="o">=</span> <span class="n">scale</span><span class="p">(</span><span class="mf">2.0</span><span class="p">,</span> <span class="p">[</span><span class="mf">1.0</span><span class="p">,</span> <span class="o">-</span><span class="mf">4.2</span><span class="p">,</span> <span class="mf">5.4</span><span class="p">])</span>315</pre></div>316</div>317<p>Type aliases are useful for simplifying complex type signatures. For example:</p>318<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">collections.abc</span><span class="w"> </span><span class="kn">import</span> <span class="n">Sequence</span>319 320<span class="nb">type</span> <span class="n">ConnectionOptions</span> <span class="o">=</span> <span class="nb">dict</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="nb">str</span><span class="p">]</span>321<span class="nb">type</span> <span class="n">Address</span> <span class="o">=</span> <span class="nb">tuple</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="nb">int</span><span class="p">]</span>322<span class="nb">type</span> <span class="n">Server</span> <span class="o">=</span> <span class="nb">tuple</span><span class="p">[</span><span class="n">Address</span><span class="p">,</span> <span class="n">ConnectionOptions</span><span class="p">]</span>323 324<span class="k">def</span><span class="w"> </span><span class="nf">broadcast_message</span><span class="p">(</span><span class="n">message</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">servers</span><span class="p">:</span> <span class="n">Sequence</span><span class="p">[</span><span class="n">Server</span><span class="p">])</span> <span class="o">-></span> <span class="kc">None</span><span class="p">:</span>325 <span class="o">...</span>326 327<span class="c1"># The static type checker will treat the previous type signature as</span>328<span class="c1"># being exactly equivalent to this one.</span>329<span class="k">def</span><span class="w"> </span><span class="nf">broadcast_message</span><span class="p">(</span>330 <span class="n">message</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span>331 <span class="n">servers</span><span class="p">:</span> <span class="n">Sequence</span><span class="p">[</span><span class="nb">tuple</span><span class="p">[</span><span class="nb">tuple</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="nb">int</span><span class="p">],</span> <span class="nb">dict</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="nb">str</span><span class="p">]]]</span>332<span class="p">)</span> <span class="o">-></span> <span class="kc">None</span><span class="p">:</span>333 <span class="o">...</span>334</pre></div>335</div>336<p>The <a class="reference internal" href="../reference/simple_stmts.html#type"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">type</span></code></a> statement is new in Python 3.12. For backwards337compatibility, type aliases can also be created through simple assignment:</p>338<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">Vector</span> <span class="o">=</span> <span class="nb">list</span><span class="p">[</span><span class="nb">float</span><span class="p">]</span>339</pre></div>340</div>341<p>Or marked with <a class="reference internal" href="#typing.TypeAlias" title="typing.TypeAlias"><code class="xref py py-data docutils literal notranslate"><span class="pre">TypeAlias</span></code></a> to make it explicit that this is a type alias,342not a normal variable assignment:</p>343<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">typing</span><span class="w"> </span><span class="kn">import</span> <span class="n">TypeAlias</span>344 345<span class="n">Vector</span><span class="p">:</span> <span class="n">TypeAlias</span> <span class="o">=</span> <span class="nb">list</span><span class="p">[</span><span class="nb">float</span><span class="p">]</span>346</pre></div>347</div>348</section>349<section id="newtype">350<span id="distinct"></span><h2>NewType<a class="headerlink" href="#newtype" title="Link to this heading">¶</a></h2>351<p>Use the <a class="reference internal" href="#typing.NewType" title="typing.NewType"><code class="xref py py-class docutils literal notranslate"><span class="pre">NewType</span></code></a> helper to create distinct types:</p>352<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">typing</span><span class="w"> </span><span class="kn">import</span> <span class="n">NewType</span>353 354<span class="n">UserId</span> <span class="o">=</span> <span class="n">NewType</span><span class="p">(</span><span class="s1">'UserId'</span><span class="p">,</span> <span class="nb">int</span><span class="p">)</span>355<span class="n">some_id</span> <span class="o">=</span> <span class="n">UserId</span><span class="p">(</span><span class="mi">524313</span><span class="p">)</span>356</pre></div>357</div>358<p>The static type checker will treat the new type as if it were a subclass359of the original type. This is useful in helping catch logical errors:</p>360<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">get_user_name</span><span class="p">(</span><span class="n">user_id</span><span class="p">:</span> <span class="n">UserId</span><span class="p">)</span> <span class="o">-></span> <span class="nb">str</span><span class="p">:</span>361 <span class="o">...</span>362 363<span class="c1"># passes type checking</span>364<span class="n">user_a</span> <span class="o">=</span> <span class="n">get_user_name</span><span class="p">(</span><span class="n">UserId</span><span class="p">(</span><span class="mi">42351</span><span class="p">))</span>365 366<span class="c1"># fails type checking; an int is not a UserId</span>367<span class="n">user_b</span> <span class="o">=</span> <span class="n">get_user_name</span><span class="p">(</span><span class="o">-</span><span class="mi">1</span><span class="p">)</span>368</pre></div>369</div>370<p>You may still perform all <code class="docutils literal notranslate"><span class="pre">int</span></code> operations on a variable of type <code class="docutils literal notranslate"><span class="pre">UserId</span></code>,371but the result will always be of type <code class="docutils literal notranslate"><span class="pre">int</span></code>. This lets you pass in a372<code class="docutils literal notranslate"><span class="pre">UserId</span></code> wherever an <code class="docutils literal notranslate"><span class="pre">int</span></code> might be expected, but will prevent you from373accidentally creating a <code class="docutils literal notranslate"><span class="pre">UserId</span></code> in an invalid way:</p>374<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="c1"># 'output' is of type 'int', not 'UserId'</span>375<span class="n">output</span> <span class="o">=</span> <span class="n">UserId</span><span class="p">(</span><span class="mi">23413</span><span class="p">)</span> <span class="o">+</span> <span class="n">UserId</span><span class="p">(</span><span class="mi">54341</span><span class="p">)</span>376</pre></div>377</div>378<p>Note that these checks are enforced only by the static type checker. At runtime,379the statement <code class="docutils literal notranslate"><span class="pre">Derived</span> <span class="pre">=</span> <span class="pre">NewType('Derived',</span> <span class="pre">Base)</span></code> will make <code class="docutils literal notranslate"><span class="pre">Derived</span></code> a380callable that immediately returns whatever parameter you pass it. That means381the expression <code class="docutils literal notranslate"><span class="pre">Derived(some_value)</span></code> does not create a new class or introduce382much overhead beyond that of a regular function call.</p>383<p>More precisely, the expression <code class="docutils literal notranslate"><span class="pre">some_value</span> <span class="pre">is</span> <span class="pre">Derived(some_value)</span></code> is always384true at runtime.</p>385<p>It is invalid to create a subtype of <code class="docutils literal notranslate"><span class="pre">Derived</span></code>:</p>386<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">typing</span><span class="w"> </span><span class="kn">import</span> <span class="n">NewType</span>387 388<span class="n">UserId</span> <span class="o">=</span> <span class="n">NewType</span><span class="p">(</span><span class="s1">'UserId'</span><span class="p">,</span> <span class="nb">int</span><span class="p">)</span>389 390<span class="c1"># Fails at runtime and does not pass type checking</span>391<span class="k">class</span><span class="w"> </span><span class="nc">AdminUserId</span><span class="p">(</span><span class="n">UserId</span><span class="p">):</span> <span class="k">pass</span>392</pre></div>393</div>394<p>However, it is possible to create a <a class="reference internal" href="#typing.NewType" title="typing.NewType"><code class="xref py py-class docutils literal notranslate"><span class="pre">NewType</span></code></a> based on a ‘derived’ <code class="docutils literal notranslate"><span class="pre">NewType</span></code>:</p>395<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">typing</span><span class="w"> </span><span class="kn">import</span> <span class="n">NewType</span>396 397<span class="n">UserId</span> <span class="o">=</span> <span class="n">NewType</span><span class="p">(</span><span class="s1">'UserId'</span><span class="p">,</span> <span class="nb">int</span><span class="p">)</span>398 399<span class="n">ProUserId</span> <span class="o">=</span> <span class="n">NewType</span><span class="p">(</span><span class="s1">'ProUserId'</span><span class="p">,</span> <span class="n">UserId</span><span class="p">)</span>400</pre></div>401</div>402<p>and typechecking for <code class="docutils literal notranslate"><span class="pre">ProUserId</span></code> will work as expected.</p>403<p>See <span class="target" id="index-0"></span><a class="pep reference external" href="https://peps.python.org/pep-0484/"><strong>PEP 484</strong></a> for more details.</p>404<div class="admonition note">405<p class="admonition-title">Note</p>406<p>Recall that the use of a type alias declares two types to be <em>equivalent</em> to407one another. Doing <code class="docutils literal notranslate"><span class="pre">type</span> <span class="pre">Alias</span> <span class="pre">=</span> <span class="pre">Original</span></code> will make the static type checker408treat <code class="docutils literal notranslate"><span class="pre">Alias</span></code> as being <em>exactly equivalent</em> to <code class="docutils literal notranslate"><span class="pre">Original</span></code> in all cases.409This is useful when you want to simplify complex type signatures.</p>410<p>In contrast, <code class="docutils literal notranslate"><span class="pre">NewType</span></code> declares one type to be a <em>subtype</em> of another.411Doing <code class="docutils literal notranslate"><span class="pre">Derived</span> <span class="pre">=</span> <span class="pre">NewType('Derived',</span> <span class="pre">Original)</span></code> will make the static type412checker treat <code class="docutils literal notranslate"><span class="pre">Derived</span></code> as a <em>subclass</em> of <code class="docutils literal notranslate"><span class="pre">Original</span></code>, which means a413value of type <code class="docutils literal notranslate"><span class="pre">Original</span></code> cannot be used in places where a value of type414<code class="docutils literal notranslate"><span class="pre">Derived</span></code> is expected. This is useful when you want to prevent logic415errors with minimal runtime cost.</p>416</div>417<div class="versionadded">418<p><span class="versionmodified added">Added in version 3.5.2.</span></p>419</div>420<div class="versionchanged">421<p><span class="versionmodified changed">Changed in version 3.10: </span><code class="docutils literal notranslate"><span class="pre">NewType</span></code> is now a class rather than a function. As a result, there is422some additional runtime cost when calling <code class="docutils literal notranslate"><span class="pre">NewType</span></code> over a regular423function.</p>424</div>425<div class="versionchanged">426<p><span class="versionmodified changed">Changed in version 3.11: </span>The performance of calling <code class="docutils literal notranslate"><span class="pre">NewType</span></code> has been restored to its level in427Python 3.9.</p>428</div>429</section>430<section id="annotating-callable-objects">431<span id="annotating-callables"></span><h2>Annotating callable objects<a class="headerlink" href="#annotating-callable-objects" title="Link to this heading">¶</a></h2>432<p>Functions – or other <a class="reference internal" href="../glossary.html#term-callable"><span class="xref std std-term">callable</span></a> objects – can be annotated using433<a class="reference internal" href="collections.abc.html#collections.abc.Callable" title="collections.abc.Callable"><code class="xref py py-class docutils literal notranslate"><span class="pre">collections.abc.Callable</span></code></a> or deprecated <a class="reference internal" href="#typing.Callable" title="typing.Callable"><code class="xref py py-data docutils literal notranslate"><span class="pre">typing.Callable</span></code></a>.434<code class="docutils literal notranslate"><span class="pre">Callable[[int],</span> <span class="pre">str]</span></code> signifies a function that takes a single parameter435of type <a class="reference internal" href="functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a> and returns a <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>.</p>436<p>For example:</p>437<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">collections.abc</span><span class="w"> </span><span class="kn">import</span> <span class="n">Callable</span><span class="p">,</span> <span class="n">Awaitable</span>438 439<span class="k">def</span><span class="w"> </span><span class="nf">feeder</span><span class="p">(</span><span class="n">get_next_item</span><span class="p">:</span> <span class="n">Callable</span><span class="p">[[],</span> <span class="nb">str</span><span class="p">])</span> <span class="o">-></span> <span class="kc">None</span><span class="p">:</span>440 <span class="o">...</span> <span class="c1"># Body</span>441 442<span class="k">def</span><span class="w"> </span><span class="nf">async_query</span><span class="p">(</span><span class="n">on_success</span><span class="p">:</span> <span class="n">Callable</span><span class="p">[[</span><span class="nb">int</span><span class="p">],</span> <span class="kc">None</span><span class="p">],</span>443 <span class="n">on_error</span><span class="p">:</span> <span class="n">Callable</span><span class="p">[[</span><span class="nb">int</span><span class="p">,</span> <span class="ne">Exception</span><span class="p">],</span> <span class="kc">None</span><span class="p">])</span> <span class="o">-></span> <span class="kc">None</span><span class="p">:</span>444 <span class="o">...</span> <span class="c1"># Body</span>445 446<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">on_update</span><span class="p">(</span><span class="n">value</span><span class="p">:</span> <span class="nb">str</span><span class="p">)</span> <span class="o">-></span> <span class="kc">None</span><span class="p">:</span>447 <span class="o">...</span> <span class="c1"># Body</span>448 449<span class="n">callback</span><span class="p">:</span> <span class="n">Callable</span><span class="p">[[</span><span class="nb">str</span><span class="p">],</span> <span class="n">Awaitable</span><span class="p">[</span><span class="kc">None</span><span class="p">]]</span> <span class="o">=</span> <span class="n">on_update</span>450</pre></div>451</div>452<p id="index-1">The subscription syntax must always be used with exactly two values: the453argument list and the return type. The argument list must be a list of types,454a <a class="reference internal" href="#typing.ParamSpec" title="typing.ParamSpec"><code class="xref py py-class docutils literal notranslate"><span class="pre">ParamSpec</span></code></a>, <a class="reference internal" href="#typing.Concatenate" title="typing.Concatenate"><code class="xref py py-data docutils literal notranslate"><span class="pre">Concatenate</span></code></a>, or an ellipsis (<code class="docutils literal notranslate"><span class="pre">...</span></code>). The return type must455be a single type.</p>456<p>If a literal ellipsis <code class="docutils literal notranslate"><span class="pre">...</span></code> is given as the argument list, it indicates that457a callable with any arbitrary parameter list would be acceptable:</p>458<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">concat</span><span class="p">(</span><span class="n">x</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">y</span><span class="p">:</span> <span class="nb">str</span><span class="p">)</span> <span class="o">-></span> <span class="nb">str</span><span class="p">:</span>459 <span class="k">return</span> <span class="n">x</span> <span class="o">+</span> <span class="n">y</span>460 461<span class="n">x</span><span class="p">:</span> <span class="n">Callable</span><span class="p">[</span><span class="o">...</span><span class="p">,</span> <span class="nb">str</span><span class="p">]</span>462<span class="n">x</span> <span class="o">=</span> <span class="nb">str</span> <span class="c1"># OK</span>463<span class="n">x</span> <span class="o">=</span> <span class="n">concat</span> <span class="c1"># Also OK</span>464</pre></div>465</div>466<p><code class="docutils literal notranslate"><span class="pre">Callable</span></code> cannot express complex signatures such as functions that take a467variadic number of arguments, <a class="reference internal" href="#overload"><span class="std std-ref">overloaded functions</span></a>, or468functions that have keyword-only parameters. However, these signatures can be469expressed by defining a <a class="reference internal" href="#typing.Protocol" title="typing.Protocol"><code class="xref py py-class docutils literal notranslate"><span class="pre">Protocol</span></code></a> class with a470<a class="reference internal" href="../reference/datamodel.html#object.__call__" title="object.__call__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__call__()</span></code></a> method:</p>471<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">collections.abc</span><span class="w"> </span><span class="kn">import</span> <span class="n">Iterable</span>472<span class="kn">from</span><span class="w"> </span><span class="nn">typing</span><span class="w"> </span><span class="kn">import</span> <span class="n">Protocol</span>473 474<span class="k">class</span><span class="w"> </span><span class="nc">Combiner</span><span class="p">(</span><span class="n">Protocol</span><span class="p">):</span>475 <span class="k">def</span><span class="w"> </span><span class="fm">__call__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="o">*</span><span class="n">vals</span><span class="p">:</span> <span class="nb">bytes</span><span class="p">,</span> <span class="n">maxlen</span><span class="p">:</span> <span class="nb">int</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">)</span> <span class="o">-></span> <span class="nb">list</span><span class="p">[</span><span class="nb">bytes</span><span class="p">]:</span> <span class="o">...</span>476 477<span class="k">def</span><span class="w"> </span><span class="nf">batch_proc</span><span class="p">(</span><span class="n">data</span><span class="p">:</span> <span class="n">Iterable</span><span class="p">[</span><span class="nb">bytes</span><span class="p">],</span> <span class="n">cb_results</span><span class="p">:</span> <span class="n">Combiner</span><span class="p">)</span> <span class="o">-></span> <span class="nb">bytes</span><span class="p">:</span>478 <span class="k">for</span> <span class="n">item</span> <span class="ow">in</span> <span class="n">data</span><span class="p">:</span>479 <span class="o">...</span>480 481<span class="k">def</span><span class="w"> </span><span class="nf">good_cb</span><span class="p">(</span><span class="o">*</span><span class="n">vals</span><span class="p">:</span> <span class="nb">bytes</span><span class="p">,</span> <span class="n">maxlen</span><span class="p">:</span> <span class="nb">int</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">)</span> <span class="o">-></span> <span class="nb">list</span><span class="p">[</span><span class="nb">bytes</span><span class="p">]:</span>482 <span class="o">...</span>483<span class="k">def</span><span class="w"> </span><span class="nf">bad_cb</span><span class="p">(</span><span class="o">*</span><span class="n">vals</span><span class="p">:</span> <span class="nb">bytes</span><span class="p">,</span> <span class="n">maxitems</span><span class="p">:</span> <span class="nb">int</span> <span class="o">|</span> <span class="kc">None</span><span class="p">)</span> <span class="o">-></span> <span class="nb">list</span><span class="p">[</span><span class="nb">bytes</span><span class="p">]:</span>484 <span class="o">...</span>485 486<span class="n">batch_proc</span><span class="p">([],</span> <span class="n">good_cb</span><span class="p">)</span> <span class="c1"># OK</span>487<span class="n">batch_proc</span><span class="p">([],</span> <span class="n">bad_cb</span><span class="p">)</span> <span class="c1"># Error! Argument 2 has incompatible type because of</span>488 <span class="c1"># different name and kind in the callback</span>489</pre></div>490</div>491<p>Callables which take other callables as arguments may indicate that their492parameter types are dependent on each other using <a class="reference internal" href="#typing.ParamSpec" title="typing.ParamSpec"><code class="xref py py-class docutils literal notranslate"><span class="pre">ParamSpec</span></code></a>.493Additionally, if that callable adds or removes arguments from other494callables, the <a class="reference internal" href="#typing.Concatenate" title="typing.Concatenate"><code class="xref py py-data docutils literal notranslate"><span class="pre">Concatenate</span></code></a> operator may be used. They495take the form <code class="docutils literal notranslate"><span class="pre">Callable[ParamSpecVariable,</span> <span class="pre">ReturnType]</span></code> and496<code class="docutils literal notranslate"><span class="pre">Callable[Concatenate[Arg1Type,</span> <span class="pre">Arg2Type,</span> <span class="pre">...,</span> <span class="pre">ParamSpecVariable],</span> <span class="pre">ReturnType]</span></code>497respectively.</p>498<div class="versionchanged">499<p><span class="versionmodified changed">Changed in version 3.10: </span><code class="docutils literal notranslate"><span class="pre">Callable</span></code> now supports <a class="reference internal" href="#typing.ParamSpec" title="typing.ParamSpec"><code class="xref py py-class docutils literal notranslate"><span class="pre">ParamSpec</span></code></a> and <a class="reference internal" href="#typing.Concatenate" title="typing.Concatenate"><code class="xref py py-data docutils literal notranslate"><span class="pre">Concatenate</span></code></a>.500See <span class="target" id="index-2"></span><a class="pep reference external" href="https://peps.python.org/pep-0612/"><strong>PEP 612</strong></a> for more details.</p>501</div>502<div class="admonition seealso">503<p class="admonition-title">See also</p>504<p>The documentation for <a class="reference internal" href="#typing.ParamSpec" title="typing.ParamSpec"><code class="xref py py-class docutils literal notranslate"><span class="pre">ParamSpec</span></code></a> and <a class="reference internal" href="#typing.Concatenate" title="typing.Concatenate"><code class="xref py py-class docutils literal notranslate"><span class="pre">Concatenate</span></code></a> provides505examples of usage in <code class="docutils literal notranslate"><span class="pre">Callable</span></code>.</p>506</div>507</section>508<section id="generics">509<span id="id3"></span><h2>Generics<a class="headerlink" href="#generics" title="Link to this heading">¶</a></h2>510<p>Since type information about objects kept in containers cannot be statically511inferred in a generic way, many container classes in the standard library support512subscription to denote the expected types of container elements.</p>513<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">collections.abc</span><span class="w"> </span><span class="kn">import</span> <span class="n">Mapping</span><span class="p">,</span> <span class="n">Sequence</span>514 515<span class="k">class</span><span class="w"> </span><span class="nc">Employee</span><span class="p">:</span> <span class="o">...</span>516 517<span class="c1"># Sequence[Employee] indicates that all elements in the sequence</span>518<span class="c1"># must be instances of "Employee".</span>519<span class="c1"># Mapping[str, str] indicates that all keys and all values in the mapping</span>520<span class="c1"># must be strings.</span>521<span class="k">def</span><span class="w"> </span><span class="nf">notify_by_email</span><span class="p">(</span><span class="n">employees</span><span class="p">:</span> <span class="n">Sequence</span><span class="p">[</span><span class="n">Employee</span><span class="p">],</span>522 <span class="n">overrides</span><span class="p">:</span> <span class="n">Mapping</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="nb">str</span><span class="p">])</span> <span class="o">-></span> <span class="kc">None</span><span class="p">:</span> <span class="o">...</span>523</pre></div>524</div>525<p>Generic functions and classes can be parameterized by using526<a class="reference internal" href="../reference/compound_stmts.html#type-params"><span class="std std-ref">type parameter syntax</span></a>:</p>527<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">collections.abc</span><span class="w"> </span><span class="kn">import</span> <span class="n">Sequence</span>528 529<span class="k">def</span><span class="w"> </span><span class="nf">first</span><span class="p">[</span><span class="n">T</span><span class="p">](</span><span class="n">l</span><span class="p">:</span> <span class="n">Sequence</span><span class="p">[</span><span class="n">T</span><span class="p">])</span> <span class="o">-></span> <span class="n">T</span><span class="p">:</span> <span class="c1"># Function is generic over the TypeVar "T"</span>530 <span class="k">return</span> <span class="n">l</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>531</pre></div>532</div>533<p>Or by using the <a class="reference internal" href="#typing.TypeVar" title="typing.TypeVar"><code class="xref py py-class docutils literal notranslate"><span class="pre">TypeVar</span></code></a> factory directly:</p>534<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">collections.abc</span><span class="w"> </span><span class="kn">import</span> <span class="n">Sequence</span>535<span class="kn">from</span><span class="w"> </span><span class="nn">typing</span><span class="w"> </span><span class="kn">import</span> <span class="n">TypeVar</span>536 537<span class="n">U</span> <span class="o">=</span> <span class="n">TypeVar</span><span class="p">(</span><span class="s1">'U'</span><span class="p">)</span> <span class="c1"># Declare type variable "U"</span>538 539<span class="k">def</span><span class="w"> </span><span class="nf">second</span><span class="p">(</span><span class="n">l</span><span class="p">:</span> <span class="n">Sequence</span><span class="p">[</span><span class="n">U</span><span class="p">])</span> <span class="o">-></span> <span class="n">U</span><span class="p">:</span> <span class="c1"># Function is generic over the TypeVar "U"</span>540 <span class="k">return</span> <span class="n">l</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span>541</pre></div>542</div>543<div class="versionchanged">544<p><span class="versionmodified changed">Changed in version 3.12: </span>Syntactic support for generics is new in Python 3.12.</p>545</div>546</section>547<section id="annotating-tuples">548<span id="id4"></span><h2>Annotating tuples<a class="headerlink" href="#annotating-tuples" title="Link to this heading">¶</a></h2>549<p>For most containers in Python, the typing system assumes that all elements in550the container will be of the same type. For example:</p>551<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">collections.abc</span><span class="w"> </span><span class="kn">import</span> <span class="n">Mapping</span>552 553<span class="c1"># Type checker will infer that all elements in ``x`` are meant to be ints</span>554<span class="n">x</span><span class="p">:</span> <span class="nb">list</span><span class="p">[</span><span class="nb">int</span><span class="p">]</span> <span class="o">=</span> <span class="p">[]</span>555 556<span class="c1"># Type checker error: ``list`` only accepts a single type argument:</span>557<span class="n">y</span><span class="p">:</span> <span class="nb">list</span><span class="p">[</span><span class="nb">int</span><span class="p">,</span> <span class="nb">str</span><span class="p">]</span> <span class="o">=</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="s1">'foo'</span><span class="p">]</span>558 559<span class="c1"># Type checker will infer that all keys in ``z`` are meant to be strings,</span>560<span class="c1"># and that all values in ``z`` are meant to be either strings or ints</span>561<span class="n">z</span><span class="p">:</span> <span class="n">Mapping</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="nb">str</span> <span class="o">|</span> <span class="nb">int</span><span class="p">]</span> <span class="o">=</span> <span class="p">{}</span>562</pre></div>563</div>564<p><a class="reference internal" href="stdtypes.html#list" title="list"><code class="xref py py-class docutils literal notranslate"><span class="pre">list</span></code></a> only accepts one type argument, so a type checker would emit an565error on the <code class="docutils literal notranslate"><span class="pre">y</span></code> assignment above. Similarly,566<a class="reference internal" href="collections.abc.html#collections.abc.Mapping" title="collections.abc.Mapping"><code class="xref py py-class docutils literal notranslate"><span class="pre">Mapping</span></code></a> only accepts two type arguments: the first567indicates the type of the keys, and the second indicates the type of the568values.</p>569<p>Unlike most other Python containers, however, it is common in idiomatic Python570code for tuples to have elements which are not all of the same type. For this571reason, tuples are special-cased in Python’s typing system. <a class="reference internal" href="stdtypes.html#tuple" title="tuple"><code class="xref py py-class docutils literal notranslate"><span class="pre">tuple</span></code></a>572accepts <em>any number</em> of type arguments:</p>573<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="c1"># OK: ``x`` is assigned to a tuple of length 1 where the sole element is an int</span>574<span class="n">x</span><span class="p">:</span> <span class="nb">tuple</span><span class="p">[</span><span class="nb">int</span><span class="p">]</span> <span class="o">=</span> <span class="p">(</span><span class="mi">5</span><span class="p">,)</span>575 576<span class="c1"># OK: ``y`` is assigned to a tuple of length 2;</span>577<span class="c1"># element 1 is an int, element 2 is a str</span>578<span class="n">y</span><span class="p">:</span> <span class="nb">tuple</span><span class="p">[</span><span class="nb">int</span><span class="p">,</span> <span class="nb">str</span><span class="p">]</span> <span class="o">=</span> <span class="p">(</span><span class="mi">5</span><span class="p">,</span> <span class="s2">"foo"</span><span class="p">)</span>579 580<span class="c1"># Error: the type annotation indicates a tuple of length 1,</span>581<span class="c1"># but ``z`` has been assigned to a tuple of length 3</span>582<span class="n">z</span><span class="p">:</span> <span class="nb">tuple</span><span class="p">[</span><span class="nb">int</span><span class="p">]</span> <span class="o">=</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">)</span>583</pre></div>584</div>585<p id="index-3">To denote a tuple which could be of <em>any</em> length, and in which all elements are586of the same type <code class="docutils literal notranslate"><span class="pre">T</span></code>, use the literal ellipsis <code class="docutils literal notranslate"><span class="pre">...</span></code>: <code class="docutils literal notranslate"><span class="pre">tuple[T,</span> <span class="pre">...]</span></code>.587To denote an empty tuple, use588<code class="docutils literal notranslate"><span class="pre">tuple[()]</span></code>. Using plain <code class="docutils literal notranslate"><span class="pre">tuple</span></code> as an annotation is equivalent to using589<code class="docutils literal notranslate"><span class="pre">tuple[Any,</span> <span class="pre">...]</span></code>:</p>590<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">x</span><span class="p">:</span> <span class="nb">tuple</span><span class="p">[</span><span class="nb">int</span><span class="p">,</span> <span class="o">...</span><span class="p">]</span> <span class="o">=</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">)</span>591<span class="c1"># These reassignments are OK: ``tuple[int, ...]`` indicates x can be of any length</span>592<span class="n">x</span> <span class="o">=</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">)</span>593<span class="n">x</span> <span class="o">=</span> <span class="p">()</span>594<span class="c1"># This reassignment is an error: all elements in ``x`` must be ints</span>595<span class="n">x</span> <span class="o">=</span> <span class="p">(</span><span class="s2">"foo"</span><span class="p">,</span> <span class="s2">"bar"</span><span class="p">)</span>596 597<span class="c1"># ``y`` can only ever be assigned to an empty tuple</span>598<span class="n">y</span><span class="p">:</span> <span class="nb">tuple</span><span class="p">[()]</span> <span class="o">=</span> <span class="p">()</span>599 600<span class="n">z</span><span class="p">:</span> <span class="nb">tuple</span> <span class="o">=</span> <span class="p">(</span><span class="s2">"foo"</span><span class="p">,</span> <span class="s2">"bar"</span><span class="p">)</span>601<span class="c1"># These reassignments are OK: plain ``tuple`` is equivalent to ``tuple[Any, ...]``</span>602<span class="n">z</span> <span class="o">=</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">)</span>603<span class="n">z</span> <span class="o">=</span> <span class="p">()</span>604</pre></div>605</div>606</section>607<section id="the-type-of-class-objects">608<span id="type-of-class-objects"></span><h2>The type of class objects<a class="headerlink" href="#the-type-of-class-objects" title="Link to this heading">¶</a></h2>609<p>A variable annotated with <code class="docutils literal notranslate"><span class="pre">C</span></code> may accept a value of type <code class="docutils literal notranslate"><span class="pre">C</span></code>. In610contrast, a variable annotated with <code class="docutils literal notranslate"><span class="pre">type[C]</span></code> (or deprecated611<a class="reference internal" href="#typing.Type" title="typing.Type"><code class="xref py py-class docutils literal notranslate"><span class="pre">typing.Type[C]</span></code></a>) may accept values that are classes612themselves – specifically, it will accept the <em>class object</em> of <code class="docutils literal notranslate"><span class="pre">C</span></code>. For613example:</p>614<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">a</span> <span class="o">=</span> <span class="mi">3</span> <span class="c1"># Has type ``int``</span>615<span class="n">b</span> <span class="o">=</span> <span class="nb">int</span> <span class="c1"># Has type ``type[int]``</span>616<span class="n">c</span> <span class="o">=</span> <span class="nb">type</span><span class="p">(</span><span class="n">a</span><span class="p">)</span> <span class="c1"># Also has type ``type[int]``</span>617</pre></div>618</div>619<p>Note that <code class="docutils literal notranslate"><span class="pre">type[C]</span></code> is covariant:</p>620<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">class</span><span class="w"> </span><span class="nc">User</span><span class="p">:</span> <span class="o">...</span>621<span class="k">class</span><span class="w"> </span><span class="nc">ProUser</span><span class="p">(</span><span class="n">User</span><span class="p">):</span> <span class="o">...</span>622<span class="k">class</span><span class="w"> </span><span class="nc">TeamUser</span><span class="p">(</span><span class="n">User</span><span class="p">):</span> <span class="o">...</span>623 624<span class="k">def</span><span class="w"> </span><span class="nf">make_new_user</span><span class="p">(</span><span class="n">user_class</span><span class="p">:</span> <span class="nb">type</span><span class="p">[</span><span class="n">User</span><span class="p">])</span> <span class="o">-></span> <span class="n">User</span><span class="p">:</span>625 <span class="c1"># ...</span>626 <span class="k">return</span> <span class="n">user_class</span><span class="p">()</span>627 628<span class="n">make_new_user</span><span class="p">(</span><span class="n">User</span><span class="p">)</span> <span class="c1"># OK</span>629<span class="n">make_new_user</span><span class="p">(</span><span class="n">ProUser</span><span class="p">)</span> <span class="c1"># Also OK: ``type[ProUser]`` is a subtype of ``type[User]``</span>630<span class="n">make_new_user</span><span class="p">(</span><span class="n">TeamUser</span><span class="p">)</span> <span class="c1"># Still fine</span>631<span class="n">make_new_user</span><span class="p">(</span><span class="n">User</span><span class="p">())</span> <span class="c1"># Error: expected ``type[User]`` but got ``User``</span>632<span class="n">make_new_user</span><span class="p">(</span><span class="nb">int</span><span class="p">)</span> <span class="c1"># Error: ``type[int]`` is not a subtype of ``type[User]``</span>633</pre></div>634</div>635<p>The only legal parameters for <a class="reference internal" href="functions.html#type" title="type"><code class="xref py py-class docutils literal notranslate"><span class="pre">type</span></code></a> are classes, <a class="reference internal" href="#typing.Any" title="typing.Any"><code class="xref py py-data docutils literal notranslate"><span class="pre">Any</span></code></a>,636<a class="reference internal" href="#generics"><span class="std std-ref">type variables</span></a>, and unions of any of these types.637For example:</p>638<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">new_non_team_user</span><span class="p">(</span><span class="n">user_class</span><span class="p">:</span> <span class="nb">type</span><span class="p">[</span><span class="n">BasicUser</span> <span class="o">|</span> <span class="n">ProUser</span><span class="p">]):</span> <span class="o">...</span>639 640<span class="n">new_non_team_user</span><span class="p">(</span><span class="n">BasicUser</span><span class="p">)</span> <span class="c1"># OK</span>641<span class="n">new_non_team_user</span><span class="p">(</span><span class="n">ProUser</span><span class="p">)</span> <span class="c1"># OK</span>642<span class="n">new_non_team_user</span><span class="p">(</span><span class="n">TeamUser</span><span class="p">)</span> <span class="c1"># Error: ``type[TeamUser]`` is not a subtype</span>643 <span class="c1"># of ``type[BasicUser | ProUser]``</span>644<span class="n">new_non_team_user</span><span class="p">(</span><span class="n">User</span><span class="p">)</span> <span class="c1"># Also an error</span>645</pre></div>646</div>647<p><code class="docutils literal notranslate"><span class="pre">type[Any]</span></code> is equivalent to <a class="reference internal" href="functions.html#type" title="type"><code class="xref py py-class docutils literal notranslate"><span class="pre">type</span></code></a>, which is the root of Python’s648<a class="reference internal" href="../reference/datamodel.html#metaclasses"><span class="std std-ref">metaclass hierarchy</span></a>.</p>649</section>650<section id="annotating-generators-and-coroutines">651<span id="id5"></span><h2>Annotating generators and coroutines<a class="headerlink" href="#annotating-generators-and-coroutines" title="Link to this heading">¶</a></h2>652<p>A generator can be annotated using the generic type653<a class="reference internal" href="collections.abc.html#collections.abc.Generator" title="collections.abc.Generator"><code class="xref py py-class docutils literal notranslate"><span class="pre">Generator[YieldType,</span> <span class="pre">SendType,</span> <span class="pre">ReturnType]</span></code></a>.654For example:</p>655<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">echo_round</span><span class="p">()</span> <span class="o">-></span> <span class="n">Generator</span><span class="p">[</span><span class="nb">int</span><span class="p">,</span> <span class="nb">float</span><span class="p">,</span> <span class="nb">str</span><span class="p">]:</span>656 <span class="n">sent</span> <span class="o">=</span> <span class="k">yield</span> <span class="mi">0</span>657 <span class="k">while</span> <span class="n">sent</span> <span class="o">>=</span> <span class="mi">0</span><span class="p">:</span>658 <span class="n">sent</span> <span class="o">=</span> <span class="k">yield</span> <span class="nb">round</span><span class="p">(</span><span class="n">sent</span><span class="p">)</span>659 <span class="k">return</span> <span class="s1">'Done'</span>660</pre></div>661</div>662<p>Note that unlike many other generic classes in the standard library,663the <code class="docutils literal notranslate"><span class="pre">SendType</span></code> of <a class="reference internal" href="collections.abc.html#collections.abc.Generator" title="collections.abc.Generator"><code class="xref py py-class docutils literal notranslate"><span class="pre">Generator</span></code></a> behaves664contravariantly, not covariantly or invariantly.</p>665<p>The <code class="docutils literal notranslate"><span class="pre">SendType</span></code> and <code class="docutils literal notranslate"><span class="pre">ReturnType</span></code> parameters default to <code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code>:</p>666<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">infinite_stream</span><span class="p">(</span><span class="n">start</span><span class="p">:</span> <span class="nb">int</span><span class="p">)</span> <span class="o">-></span> <span class="n">Generator</span><span class="p">[</span><span class="nb">int</span><span class="p">]:</span>667 <span class="k">while</span> <span class="kc">True</span><span class="p">:</span>668 <span class="k">yield</span> <span class="n">start</span>669 <span class="n">start</span> <span class="o">+=</span> <span class="mi">1</span>670</pre></div>671</div>672<p>It is also possible to set these types explicitly:</p>673<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">infinite_stream</span><span class="p">(</span><span class="n">start</span><span class="p">:</span> <span class="nb">int</span><span class="p">)</span> <span class="o">-></span> <span class="n">Generator</span><span class="p">[</span><span class="nb">int</span><span class="p">,</span> <span class="kc">None</span><span class="p">,</span> <span class="kc">None</span><span class="p">]:</span>674 <span class="k">while</span> <span class="kc">True</span><span class="p">:</span>675 <span class="k">yield</span> <span class="n">start</span>676 <span class="n">start</span> <span class="o">+=</span> <span class="mi">1</span>677</pre></div>678</div>679<p>Simple generators that only ever yield values can also be annotated680as having a return type of either681<a class="reference internal" href="collections.abc.html#collections.abc.Iterable" title="collections.abc.Iterable"><code class="xref py py-class docutils literal notranslate"><span class="pre">Iterable[YieldType]</span></code></a>682or <a class="reference internal" href="collections.abc.html#collections.abc.Iterator" title="collections.abc.Iterator"><code class="xref py py-class docutils literal notranslate"><span class="pre">Iterator[YieldType]</span></code></a>:</p>683<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">infinite_stream</span><span class="p">(</span><span class="n">start</span><span class="p">:</span> <span class="nb">int</span><span class="p">)</span> <span class="o">-></span> <span class="n">Iterator</span><span class="p">[</span><span class="nb">int</span><span class="p">]:</span>684 <span class="k">while</span> <span class="kc">True</span><span class="p">:</span>685 <span class="k">yield</span> <span class="n">start</span>686 <span class="n">start</span> <span class="o">+=</span> <span class="mi">1</span>687</pre></div>688</div>689<p>Async generators are handled in a similar fashion, but don’t690expect a <code class="docutils literal notranslate"><span class="pre">ReturnType</span></code> type argument691(<a class="reference internal" href="collections.abc.html#collections.abc.AsyncGenerator" title="collections.abc.AsyncGenerator"><code class="xref py py-class docutils literal notranslate"><span class="pre">AsyncGenerator[YieldType,</span> <span class="pre">SendType]</span></code></a>).692The <code class="docutils literal notranslate"><span class="pre">SendType</span></code> argument defaults to <code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code>, so the following definitions693are equivalent:</p>694<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">infinite_stream</span><span class="p">(</span><span class="n">start</span><span class="p">:</span> <span class="nb">int</span><span class="p">)</span> <span class="o">-></span> <span class="n">AsyncGenerator</span><span class="p">[</span><span class="nb">int</span><span class="p">]:</span>695 <span class="k">while</span> <span class="kc">True</span><span class="p">:</span>696 <span class="k">yield</span> <span class="n">start</span>697 <span class="n">start</span> <span class="o">=</span> <span class="k">await</span> <span class="n">increment</span><span class="p">(</span><span class="n">start</span><span class="p">)</span>698 699<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">infinite_stream</span><span class="p">(</span><span class="n">start</span><span class="p">:</span> <span class="nb">int</span><span class="p">)</span> <span class="o">-></span> <span class="n">AsyncGenerator</span><span class="p">[</span><span class="nb">int</span><span class="p">,</span> <span class="kc">None</span><span class="p">]:</span>700 <span class="k">while</span> <span class="kc">True</span><span class="p">:</span>701 <span class="k">yield</span> <span class="n">start</span>702 <span class="n">start</span> <span class="o">=</span> <span class="k">await</span> <span class="n">increment</span><span class="p">(</span><span class="n">start</span><span class="p">)</span>703</pre></div>704</div>705<p>As in the synchronous case,706<a class="reference internal" href="collections.abc.html#collections.abc.AsyncIterable" title="collections.abc.AsyncIterable"><code class="xref py py-class docutils literal notranslate"><span class="pre">AsyncIterable[YieldType]</span></code></a>707and <a class="reference internal" href="collections.abc.html#collections.abc.AsyncIterator" title="collections.abc.AsyncIterator"><code class="xref py py-class docutils literal notranslate"><span class="pre">AsyncIterator[YieldType]</span></code></a> are708available as well:</p>709<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">infinite_stream</span><span class="p">(</span><span class="n">start</span><span class="p">:</span> <span class="nb">int</span><span class="p">)</span> <span class="o">-></span> <span class="n">AsyncIterator</span><span class="p">[</span><span class="nb">int</span><span class="p">]:</span>710 <span class="k">while</span> <span class="kc">True</span><span class="p">:</span>711 <span class="k">yield</span> <span class="n">start</span>712 <span class="n">start</span> <span class="o">=</span> <span class="k">await</span> <span class="n">increment</span><span class="p">(</span><span class="n">start</span><span class="p">)</span>713</pre></div>714</div>715<p>Coroutines can be annotated using716<a class="reference internal" href="collections.abc.html#collections.abc.Coroutine" title="collections.abc.Coroutine"><code class="xref py py-class docutils literal notranslate"><span class="pre">Coroutine[YieldType,</span> <span class="pre">SendType,</span> <span class="pre">ReturnType]</span></code></a>.717Generic arguments correspond to those of <a class="reference internal" href="collections.abc.html#collections.abc.Generator" title="collections.abc.Generator"><code class="xref py py-class docutils literal notranslate"><span class="pre">Generator</span></code></a>,718for example:</p>719<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">collections.abc</span><span class="w"> </span><span class="kn">import</span> <span class="n">Coroutine</span>720<span class="n">c</span><span class="p">:</span> <span class="n">Coroutine</span><span class="p">[</span><span class="nb">list</span><span class="p">[</span><span class="nb">str</span><span class="p">],</span> <span class="nb">str</span><span class="p">,</span> <span class="nb">int</span><span class="p">]</span> <span class="c1"># Some coroutine defined elsewhere</span>721<span class="n">x</span> <span class="o">=</span> <span class="n">c</span><span class="o">.</span><span class="n">send</span><span class="p">(</span><span class="s1">'hi'</span><span class="p">)</span> <span class="c1"># Inferred type of 'x' is list[str]</span>722<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">bar</span><span class="p">()</span> <span class="o">-></span> <span class="kc">None</span><span class="p">:</span>723 <span class="n">y</span> <span class="o">=</span> <span class="k">await</span> <span class="n">c</span> <span class="c1"># Inferred type of 'y' is int</span>724</pre></div>725</div>726</section>727<section id="user-defined-generic-types">728<span id="user-defined-generics"></span><h2>User-defined generic types<a class="headerlink" href="#user-defined-generic-types" title="Link to this heading">¶</a></h2>729<p>A user-defined class can be defined as a generic class.</p>730<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">logging</span><span class="w"> </span><span class="kn">import</span> <span class="n">Logger</span>731 732<span class="k">class</span><span class="w"> </span><span class="nc">LoggedVar</span><span class="p">[</span><span class="n">T</span><span class="p">]:</span>733 <span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">value</span><span class="p">:</span> <span class="n">T</span><span class="p">,</span> <span class="n">name</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">logger</span><span class="p">:</span> <span class="n">Logger</span><span class="p">)</span> <span class="o">-></span> <span class="kc">None</span><span class="p">:</span>734 <span class="bp">self</span><span class="o">.</span><span class="n">name</span> <span class="o">=</span> <span class="n">name</span>735 <span class="bp">self</span><span class="o">.</span><span class="n">logger</span> <span class="o">=</span> <span class="n">logger</span>736 <span class="bp">self</span><span class="o">.</span><span class="n">value</span> <span class="o">=</span> <span class="n">value</span>737 738 <span class="k">def</span><span class="w"> </span><span class="nf">set</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">new</span><span class="p">:</span> <span class="n">T</span><span class="p">)</span> <span class="o">-></span> <span class="kc">None</span><span class="p">:</span>739 <span class="bp">self</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s1">'Set '</span> <span class="o">+</span> <span class="nb">repr</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">value</span><span class="p">))</span>740 <span class="bp">self</span><span class="o">.</span><span class="n">value</span> <span class="o">=</span> <span class="n">new</span>741 742 <span class="k">def</span><span class="w"> </span><span class="nf">get</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">-></span> <span class="n">T</span><span class="p">:</span>743 <span class="bp">self</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s1">'Get '</span> <span class="o">+</span> <span class="nb">repr</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">value</span><span class="p">))</span>744 <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">value</span>745 746 <span class="k">def</span><span class="w"> </span><span class="nf">log</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">message</span><span class="p">:</span> <span class="nb">str</span><span class="p">)</span> <span class="o">-></span> <span class="kc">None</span><span class="p">:</span>747 <span class="bp">self</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">'</span><span class="si">%s</span><span class="s1">: </span><span class="si">%s</span><span class="s1">'</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">name</span><span class="p">,</span> <span class="n">message</span><span class="p">)</span>748</pre></div>749</div>750<p>This syntax indicates that the class <code class="docutils literal notranslate"><span class="pre">LoggedVar</span></code> is parameterised around a751single <a class="reference internal" href="#typevar"><span class="std std-ref">type variable</span></a> <code class="docutils literal notranslate"><span class="pre">T</span></code> . This also makes <code class="docutils literal notranslate"><span class="pre">T</span></code> valid as752a type within the class body.</p>753<p>Generic classes implicitly inherit from <a class="reference internal" href="#typing.Generic" title="typing.Generic"><code class="xref py py-class docutils literal notranslate"><span class="pre">Generic</span></code></a>. For compatibility754with Python 3.11 and lower, it is also possible to inherit explicitly from755<code class="xref py py-class docutils literal notranslate"><span class="pre">Generic</span></code> to indicate a generic class:</p>756<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">typing</span><span class="w"> </span><span class="kn">import</span> <span class="n">TypeVar</span><span class="p">,</span> <span class="n">Generic</span>757 758<span class="n">T</span> <span class="o">=</span> <span class="n">TypeVar</span><span class="p">(</span><span class="s1">'T'</span><span class="p">)</span>759 760<span class="k">class</span><span class="w"> </span><span class="nc">LoggedVar</span><span class="p">(</span><span class="n">Generic</span><span class="p">[</span><span class="n">T</span><span class="p">]):</span>761 <span class="o">...</span>762</pre></div>763</div>764<p>Generic classes have <a class="reference internal" href="../reference/datamodel.html#object.__class_getitem__" title="object.__class_getitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__class_getitem__()</span></code></a> methods, meaning they765can be parameterised at runtime (e.g. <code class="docutils literal notranslate"><span class="pre">LoggedVar[int]</span></code> below):</p>766<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">collections.abc</span><span class="w"> </span><span class="kn">import</span> <span class="n">Iterable</span>767 768<span class="k">def</span><span class="w"> </span><span class="nf">zero_all_vars</span><span class="p">(</span><span class="nb">vars</span><span class="p">:</span> <span class="n">Iterable</span><span class="p">[</span><span class="n">LoggedVar</span><span class="p">[</span><span class="nb">int</span><span class="p">]])</span> <span class="o">-></span> <span class="kc">None</span><span class="p">:</span>769 <span class="k">for</span> <span class="n">var</span> <span class="ow">in</span> <span class="nb">vars</span><span class="p">:</span>770 <span class="n">var</span><span class="o">.</span><span class="n">set</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span>771</pre></div>772</div>773<p>A generic type can have any number of type variables. All varieties of774<a class="reference internal" href="#typing.TypeVar" title="typing.TypeVar"><code class="xref py py-class docutils literal notranslate"><span class="pre">TypeVar</span></code></a> are permissible as parameters for a generic type:</p>775<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">typing</span><span class="w"> </span><span class="kn">import</span> <span class="n">TypeVar</span><span class="p">,</span> <span class="n">Generic</span><span class="p">,</span> <span class="n">Sequence</span>776 777<span class="k">class</span><span class="w"> </span><span class="nc">WeirdTrio</span><span class="p">[</span><span class="n">T</span><span class="p">,</span> <span class="n">B</span><span class="p">:</span> <span class="n">Sequence</span><span class="p">[</span><span class="nb">bytes</span><span class="p">],</span> <span class="n">S</span><span class="p">:</span> <span class="p">(</span><span class="nb">int</span><span class="p">,</span> <span class="nb">str</span><span class="p">)]:</span>778 <span class="o">...</span>779 780<span class="n">OldT</span> <span class="o">=</span> <span class="n">TypeVar</span><span class="p">(</span><span class="s1">'OldT'</span><span class="p">,</span> <span class="n">contravariant</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>781<span class="n">OldB</span> <span class="o">=</span> <span class="n">TypeVar</span><span class="p">(</span><span class="s1">'OldB'</span><span class="p">,</span> <span class="n">bound</span><span class="o">=</span><span class="n">Sequence</span><span class="p">[</span><span class="nb">bytes</span><span class="p">],</span> <span class="n">covariant</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>782<span class="n">OldS</span> <span class="o">=</span> <span class="n">TypeVar</span><span class="p">(</span><span class="s1">'OldS'</span><span class="p">,</span> <span class="nb">int</span><span class="p">,</span> <span class="nb">str</span><span class="p">)</span>783 784<span class="k">class</span><span class="w"> </span><span class="nc">OldWeirdTrio</span><span class="p">(</span><span class="n">Generic</span><span class="p">[</span><span class="n">OldT</span><span class="p">,</span> <span class="n">OldB</span><span class="p">,</span> <span class="n">OldS</span><span class="p">]):</span>785 <span class="o">...</span>786</pre></div>787</div>788<p>Each type variable argument to <a class="reference internal" href="#typing.Generic" title="typing.Generic"><code class="xref py py-class docutils literal notranslate"><span class="pre">Generic</span></code></a> must be distinct.789This is thus invalid:</p>790<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">typing</span><span class="w"> </span><span class="kn">import</span> <span class="n">TypeVar</span><span class="p">,</span> <span class="n">Generic</span>791<span class="o">...</span>792 793<span class="k">class</span><span class="w"> </span><span class="nc">Pair</span><span class="p">[</span><span class="n">M</span><span class="p">,</span> <span class="n">M</span><span class="p">]:</span> <span class="c1"># SyntaxError</span>794 <span class="o">...</span>795 796<span class="n">T</span> <span class="o">=</span> <span class="n">TypeVar</span><span class="p">(</span><span class="s1">'T'</span><span class="p">)</span>797 798<span class="k">class</span><span class="w"> </span><span class="nc">Pair</span><span class="p">(</span><span class="n">Generic</span><span class="p">[</span><span class="n">T</span><span class="p">,</span> <span class="n">T</span><span class="p">]):</span> <span class="c1"># INVALID</span>799 <span class="o">...</span>800</pre></div>801</div>802<p>Generic classes can also inherit from other classes:</p>803<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">collections.abc</span><span class="w"> </span><span class="kn">import</span> <span class="n">Sized</span>804 805<span class="k">class</span><span class="w"> </span><span class="nc">LinkedList</span><span class="p">[</span><span class="n">T</span><span class="p">](</span><span class="n">Sized</span><span class="p">):</span>806 <span class="o">...</span>807</pre></div>808</div>809<p>When inheriting from generic classes, some type parameters could be fixed:</p>810<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">collections.abc</span><span class="w"> </span><span class="kn">import</span> <span class="n">Mapping</span>811 812<span class="k">class</span><span class="w"> </span><span class="nc">MyDict</span><span class="p">[</span><span class="n">T</span><span class="p">](</span><span class="n">Mapping</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="n">T</span><span class="p">]):</span>813 <span class="o">...</span>814</pre></div>815</div>816<p>In this case <code class="docutils literal notranslate"><span class="pre">MyDict</span></code> has a single parameter, <code class="docutils literal notranslate"><span class="pre">T</span></code>.</p>817<p>Using a generic class without specifying type parameters assumes818<a class="reference internal" href="#typing.Any" title="typing.Any"><code class="xref py py-data docutils literal notranslate"><span class="pre">Any</span></code></a> for each position. In the following example, <code class="docutils literal notranslate"><span class="pre">MyIterable</span></code> is819not generic but implicitly inherits from <code class="docutils literal notranslate"><span class="pre">Iterable[Any]</span></code>:</p>820<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">collections.abc</span><span class="w"> </span><span class="kn">import</span> <span class="n">Iterable</span>821 822<span class="k">class</span><span class="w"> </span><span class="nc">MyIterable</span><span class="p">(</span><span class="n">Iterable</span><span class="p">):</span> <span class="c1"># Same as Iterable[Any]</span>823 <span class="o">...</span>824</pre></div>825</div>826<p>User-defined generic type aliases are also supported. Examples:</p>827<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">collections.abc</span><span class="w"> </span><span class="kn">import</span> <span class="n">Iterable</span>828 829<span class="nb">type</span> <span class="n">Response</span><span class="p">[</span><span class="n">S</span><span class="p">]</span> <span class="o">=</span> <span class="n">Iterable</span><span class="p">[</span><span class="n">S</span><span class="p">]</span> <span class="o">|</span> <span class="nb">int</span>830 831<span class="c1"># Return type here is same as Iterable[str] | int</span>832<span class="k">def</span><span class="w"> </span><span class="nf">response</span><span class="p">(</span><span class="n">query</span><span class="p">:</span> <span class="nb">str</span><span class="p">)</span> <span class="o">-></span> <span class="n">Response</span><span class="p">[</span><span class="nb">str</span><span class="p">]:</span>833 <span class="o">...</span>834 835<span class="nb">type</span> <span class="n">Vec</span><span class="p">[</span><span class="n">T</span><span class="p">]</span> <span class="o">=</span> <span class="n">Iterable</span><span class="p">[</span><span class="nb">tuple</span><span class="p">[</span><span class="n">T</span><span class="p">,</span> <span class="n">T</span><span class="p">]]</span>836 837<span class="k">def</span><span class="w"> </span><span class="nf">inproduct</span><span class="p">[</span><span class="n">T</span><span class="p">:</span> <span class="p">(</span><span class="nb">int</span><span class="p">,</span> <span class="nb">float</span><span class="p">,</span> <span class="nb">complex</span><span class="p">)](</span><span class="n">v</span><span class="p">:</span> <span class="n">Vec</span><span class="p">[</span><span class="n">T</span><span class="p">])</span> <span class="o">-></span> <span class="n">T</span><span class="p">:</span> <span class="c1"># Same as Iterable[tuple[T, T]]</span>838 <span class="k">return</span> <span class="nb">sum</span><span class="p">(</span><span class="n">x</span><span class="o">*</span><span class="n">y</span> <span class="k">for</span> <span class="n">x</span><span class="p">,</span> <span class="n">y</span> <span class="ow">in</span> <span class="n">v</span><span class="p">)</span>839</pre></div>840</div>841<p>For backward compatibility, generic type aliases can also be created842through a simple assignment:</p>843<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">collections.abc</span><span class="w"> </span><span class="kn">import</span> <span class="n">Iterable</span>844<span class="kn">from</span><span class="w"> </span><span class="nn">typing</span><span class="w"> </span><span class="kn">import</span> <span class="n">TypeVar</span>845 846<span class="n">S</span> <span class="o">=</span> <span class="n">TypeVar</span><span class="p">(</span><span class="s2">"S"</span><span class="p">)</span>847<span class="n">Response</span> <span class="o">=</span> <span class="n">Iterable</span><span class="p">[</span><span class="n">S</span><span class="p">]</span> <span class="o">|</span> <span class="nb">int</span>848</pre></div>849</div>850<div class="versionchanged">851<p><span class="versionmodified changed">Changed in version 3.7: </span><a class="reference internal" href="#typing.Generic" title="typing.Generic"><code class="xref py py-class docutils literal notranslate"><span class="pre">Generic</span></code></a> no longer has a custom metaclass.</p>852</div>853<div class="versionchanged">854<p><span class="versionmodified changed">Changed in version 3.12: </span>Syntactic support for generics and type aliases is new in version 3.12.855Previously, generic classes had to explicitly inherit from <a class="reference internal" href="#typing.Generic" title="typing.Generic"><code class="xref py py-class docutils literal notranslate"><span class="pre">Generic</span></code></a>856or contain a type variable in one of their bases.</p>857</div>858<p>User-defined generics for parameter expressions are also supported via parameter859specification variables in the form <code class="docutils literal notranslate"><span class="pre">[**P]</span></code>. The behavior is consistent860with type variables’ described above as parameter specification variables are861treated by the <code class="xref py py-mod docutils literal notranslate"><span class="pre">typing</span></code> module as a specialized type variable. The one exception862to this is that a list of types can be used to substitute a <a class="reference internal" href="#typing.ParamSpec" title="typing.ParamSpec"><code class="xref py py-class docutils literal notranslate"><span class="pre">ParamSpec</span></code></a>:</p>863<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="k">class</span><span class="w"> </span><span class="nc">Z</span><span class="p">[</span><span class="n">T</span><span class="p">,</span> <span class="o">**</span><span class="n">P</span><span class="p">]:</span> <span class="o">...</span> <span class="c1"># T is a TypeVar; P is a ParamSpec</span>864<span class="gp">...</span>865<span class="gp">>>> </span><span class="n">Z</span><span class="p">[</span><span class="nb">int</span><span class="p">,</span> <span class="p">[</span><span class="nb">dict</span><span class="p">,</span> <span class="nb">float</span><span class="p">]]</span>866<span class="go">__main__.Z[int, [dict, float]]</span>867</pre></div>868</div>869<p>Classes generic over a <a class="reference internal" href="#typing.ParamSpec" title="typing.ParamSpec"><code class="xref py py-class docutils literal notranslate"><span class="pre">ParamSpec</span></code></a> can also be created using explicit870inheritance from <a class="reference internal" href="#typing.Generic" title="typing.Generic"><code class="xref py py-class docutils literal notranslate"><span class="pre">Generic</span></code></a>. In this case, <code class="docutils literal notranslate"><span class="pre">**</span></code> is not used:</p>871<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">typing</span><span class="w"> </span><span class="kn">import</span> <span class="n">ParamSpec</span><span class="p">,</span> <span class="n">Generic</span>872 873<span class="n">P</span> <span class="o">=</span> <span class="n">ParamSpec</span><span class="p">(</span><span class="s1">'P'</span><span class="p">)</span>874 875<span class="k">class</span><span class="w"> </span><span class="nc">Z</span><span class="p">(</span><span class="n">Generic</span><span class="p">[</span><span class="n">P</span><span class="p">]):</span>876 <span class="o">...</span>877</pre></div>878</div>879<p>Another difference between <a class="reference internal" href="#typing.TypeVar" title="typing.TypeVar"><code class="xref py py-class docutils literal notranslate"><span class="pre">TypeVar</span></code></a> and <a class="reference internal" href="#typing.ParamSpec" title="typing.ParamSpec"><code class="xref py py-class docutils literal notranslate"><span class="pre">ParamSpec</span></code></a> is that a880generic with only one parameter specification variable will accept881parameter lists in the forms <code class="docutils literal notranslate"><span class="pre">X[[Type1,</span> <span class="pre">Type2,</span> <span class="pre">...]]</span></code> and also882<code class="docutils literal notranslate"><span class="pre">X[Type1,</span> <span class="pre">Type2,</span> <span class="pre">...]</span></code> for aesthetic reasons. Internally, the latter is converted883to the former, so the following are equivalent:</p>884<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="k">class</span><span class="w"> </span><span class="nc">X</span><span class="p">[</span><span class="o">**</span><span class="n">P</span><span class="p">]:</span> <span class="o">...</span>885<span class="gp">...</span>886<span class="gp">>>> </span><span class="n">X</span><span class="p">[</span><span class="nb">int</span><span class="p">,</span> <span class="nb">str</span><span class="p">]</span>887<span class="go">__main__.X[[int, str]]</span>888<span class="gp">>>> </span><span class="n">X</span><span class="p">[[</span><span class="nb">int</span><span class="p">,</span> <span class="nb">str</span><span class="p">]]</span>889<span class="go">__main__.X[[int, str]]</span>890</pre></div>891</div>892<p>Note that generics with <a class="reference internal" href="#typing.ParamSpec" title="typing.ParamSpec"><code class="xref py py-class docutils literal notranslate"><span class="pre">ParamSpec</span></code></a> may not have correct893<code class="docutils literal notranslate"><span class="pre">__parameters__</span></code> after substitution in some cases because they894are intended primarily for static type checking.</p>895<div class="versionchanged">896<p><span class="versionmodified changed">Changed in version 3.10: </span><a class="reference internal" href="#typing.Generic" title="typing.Generic"><code class="xref py py-class docutils literal notranslate"><span class="pre">Generic</span></code></a> can now be parameterized over parameter expressions.897See <a class="reference internal" href="#typing.ParamSpec" title="typing.ParamSpec"><code class="xref py py-class docutils literal notranslate"><span class="pre">ParamSpec</span></code></a> and <span class="target" id="index-4"></span><a class="pep reference external" href="https://peps.python.org/pep-0612/"><strong>PEP 612</strong></a> for more details.</p>898</div>899<p>A user-defined generic class can have ABCs as base classes without a metaclass900conflict. Generic metaclasses are not supported. The outcome of parameterizing901generics is cached, and most types in the <code class="xref py py-mod docutils literal notranslate"><span class="pre">typing</span></code> module are <a class="reference internal" href="../glossary.html#term-hashable"><span class="xref std std-term">hashable</span></a> and902comparable for equality.</p>903</section>904<section id="the-any-type">905<h2>The <a class="reference internal" href="#typing.Any" title="typing.Any"><code class="xref py py-data docutils literal notranslate"><span class="pre">Any</span></code></a> type<a class="headerlink" href="#the-any-type" title="Link to this heading">¶</a></h2>906<p>A special kind of type is <a class="reference internal" href="#typing.Any" title="typing.Any"><code class="xref py py-data docutils literal notranslate"><span class="pre">Any</span></code></a>. A static type checker will treat907every type as being compatible with <code class="xref py py-data docutils literal notranslate"><span class="pre">Any</span></code> and <code class="xref py py-data docutils literal notranslate"><span class="pre">Any</span></code> as being908compatible with every type.</p>909<p>This means that it is possible to perform any operation or method call on a910value of type <a class="reference internal" href="#typing.Any" title="typing.Any"><code class="xref py py-data docutils literal notranslate"><span class="pre">Any</span></code></a> and assign it to any variable:</p>911<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">typing</span><span class="w"> </span><span class="kn">import</span> <span class="n">Any</span>912 913<span class="n">a</span><span class="p">:</span> <span class="n">Any</span> <span class="o">=</span> <span class="kc">None</span>914<span class="n">a</span> <span class="o">=</span> <span class="p">[]</span> <span class="c1"># OK</span>915<span class="n">a</span> <span class="o">=</span> <span class="mi">2</span> <span class="c1"># OK</span>916 917<span class="n">s</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s1">''</span>918<span class="n">s</span> <span class="o">=</span> <span class="n">a</span> <span class="c1"># OK</span>919 920<span class="k">def</span><span class="w"> </span><span class="nf">foo</span><span class="p">(</span><span class="n">item</span><span class="p">:</span> <span class="n">Any</span><span class="p">)</span> <span class="o">-></span> <span class="nb">int</span><span class="p">:</span>921 <span class="c1"># Passes type checking; 'item' could be any type,</span>922 <span class="c1"># and that type might have a 'bar' method</span>923 <span class="n">item</span><span class="o">.</span><span class="n">bar</span><span class="p">()</span>924 <span class="o">...</span>925</pre></div>926</div>927<p>Notice that no type checking is performed when assigning a value of type928<a class="reference internal" href="#typing.Any" title="typing.Any"><code class="xref py py-data docutils literal notranslate"><span class="pre">Any</span></code></a> to a more precise type. For example, the static type checker did929not report an error when assigning <code class="docutils literal notranslate"><span class="pre">a</span></code> to <code class="docutils literal notranslate"><span class="pre">s</span></code> even though <code class="docutils literal notranslate"><span class="pre">s</span></code> was930declared to be of type <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> and receives an <a class="reference internal" href="functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a> value at931runtime!</p>932<p>Furthermore, all functions without a return type or parameter types will933implicitly default to using <a class="reference internal" href="#typing.Any" title="typing.Any"><code class="xref py py-data docutils literal notranslate"><span class="pre">Any</span></code></a>:</p>934<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">legacy_parser</span><span class="p">(</span><span class="n">text</span><span class="p">):</span>935 <span class="o">...</span>936 <span class="k">return</span> <span class="n">data</span>937 938<span class="c1"># A static type checker will treat the above</span>939<span class="c1"># as having the same signature as:</span>940<span class="k">def</span><span class="w"> </span><span class="nf">legacy_parser</span><span class="p">(</span><span class="n">text</span><span class="p">:</span> <span class="n">Any</span><span class="p">)</span> <span class="o">-></span> <span class="n">Any</span><span class="p">:</span>941 <span class="o">...</span>942 <span class="k">return</span> <span class="n">data</span>943</pre></div>944</div>945<p>This behavior allows <a class="reference internal" href="#typing.Any" title="typing.Any"><code class="xref py py-data docutils literal notranslate"><span class="pre">Any</span></code></a> to be used as an <em>escape hatch</em> when you946need to mix dynamically and statically typed code.</p>947<p>Contrast the behavior of <a class="reference internal" href="#typing.Any" title="typing.Any"><code class="xref py py-data docutils literal notranslate"><span class="pre">Any</span></code></a> with the behavior of <a class="reference internal" href="functions.html#object" title="object"><code class="xref py py-class docutils literal notranslate"><span class="pre">object</span></code></a>.948Similar to <code class="xref py py-data docutils literal notranslate"><span class="pre">Any</span></code>, every type is a subtype of <code class="xref py py-class docutils literal notranslate"><span class="pre">object</span></code>. However,949unlike <code class="xref py py-data docutils literal notranslate"><span class="pre">Any</span></code>, the reverse is not true: <code class="xref py py-class docutils literal notranslate"><span class="pre">object</span></code> is <em>not</em> a950subtype of every other type.</p>951<p>That means when the type of a value is <a class="reference internal" href="functions.html#object" title="object"><code class="xref py py-class docutils literal notranslate"><span class="pre">object</span></code></a>, a type checker will952reject almost all operations on it, and assigning it to a variable (or using953it as a return value) of a more specialized type is a type error. For example:</p>954<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">hash_a</span><span class="p">(</span><span class="n">item</span><span class="p">:</span> <span class="nb">object</span><span class="p">)</span> <span class="o">-></span> <span class="nb">int</span><span class="p">:</span>955 <span class="c1"># Fails type checking; an object does not have a 'magic' method.</span>956 <span class="n">item</span><span class="o">.</span><span class="n">magic</span><span class="p">()</span>957 <span class="o">...</span>958 959<span class="k">def</span><span class="w"> </span><span class="nf">hash_b</span><span class="p">(</span><span class="n">item</span><span class="p">:</span> <span class="n">Any</span><span class="p">)</span> <span class="o">-></span> <span class="nb">int</span><span class="p">:</span>960 <span class="c1"># Passes type checking</span>961 <span class="n">item</span><span class="o">.</span><span class="n">magic</span><span class="p">()</span>962 <span class="o">...</span>963 964<span class="c1"># Passes type checking, since ints and strs are subclasses of object</span>965<span class="n">hash_a</span><span class="p">(</span><span class="mi">42</span><span class="p">)</span>966<span class="n">hash_a</span><span class="p">(</span><span class="s2">"foo"</span><span class="p">)</span>967 968<span class="c1"># Passes type checking, since Any is compatible with all types</span>969<span class="n">hash_b</span><span class="p">(</span><span class="mi">42</span><span class="p">)</span>970<span class="n">hash_b</span><span class="p">(</span><span class="s2">"foo"</span><span class="p">)</span>971</pre></div>972</div>973<p>Use <a class="reference internal" href="functions.html#object" title="object"><code class="xref py py-class docutils literal notranslate"><span class="pre">object</span></code></a> to indicate that a value could be any type in a typesafe974manner. Use <a class="reference internal" href="#typing.Any" title="typing.Any"><code class="xref py py-data docutils literal notranslate"><span class="pre">Any</span></code></a> to indicate that a value is dynamically typed.</p>975</section>976<section id="nominal-vs-structural-subtyping">977<h2>Nominal vs structural subtyping<a class="headerlink" href="#nominal-vs-structural-subtyping" title="Link to this heading">¶</a></h2>978<p>Initially <span class="target" id="index-5"></span><a class="pep reference external" href="https://peps.python.org/pep-0484/"><strong>PEP 484</strong></a> defined the Python static type system as using979<em>nominal subtyping</em>. This means that a class <code class="docutils literal notranslate"><span class="pre">A</span></code> is allowed where980a class <code class="docutils literal notranslate"><span class="pre">B</span></code> is expected if and only if <code class="docutils literal notranslate"><span class="pre">A</span></code> is a subclass of <code class="docutils literal notranslate"><span class="pre">B</span></code>.</p>981<p>This requirement previously also applied to abstract base classes, such as982<a class="reference internal" href="collections.abc.html#collections.abc.Iterable" title="collections.abc.Iterable"><code class="xref py py-class docutils literal notranslate"><span class="pre">Iterable</span></code></a>. The problem with this approach is that a class had983to be explicitly marked to support them, which is unpythonic and unlike984what one would normally do in idiomatic dynamically typed Python code.985For example, this conforms to <span class="target" id="index-6"></span><a class="pep reference external" href="https://peps.python.org/pep-0484/"><strong>PEP 484</strong></a>:</p>986<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">collections.abc</span><span class="w"> </span><span class="kn">import</span> <span class="n">Sized</span><span class="p">,</span> <span class="n">Iterable</span><span class="p">,</span> <span class="n">Iterator</span>987 988<span class="k">class</span><span class="w"> </span><span class="nc">Bucket</span><span class="p">(</span><span class="n">Sized</span><span class="p">,</span> <span class="n">Iterable</span><span class="p">[</span><span class="nb">int</span><span class="p">]):</span>989 <span class="o">...</span>990 <span class="k">def</span><span class="w"> </span><span class="fm">__len__</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">-></span> <span class="nb">int</span><span class="p">:</span> <span class="o">...</span>991 <span class="k">def</span><span class="w"> </span><span class="fm">__iter__</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">-></span> <span class="n">Iterator</span><span class="p">[</span><span class="nb">int</span><span class="p">]:</span> <span class="o">...</span>992</pre></div>993</div>994<p><span class="target" id="index-7"></span><a class="pep reference external" href="https://peps.python.org/pep-0544/"><strong>PEP 544</strong></a> solves this problem by allowing users to write995the above code without explicit base classes in the class definition,996allowing <code class="docutils literal notranslate"><span class="pre">Bucket</span></code> to be implicitly considered a subtype of both <code class="docutils literal notranslate"><span class="pre">Sized</span></code>997and <code class="docutils literal notranslate"><span class="pre">Iterable[int]</span></code> by static type checkers. This is known as998<em>structural subtyping</em> (or static duck-typing):</p>999<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">collections.abc</span><span class="w"> </span><span class="kn">import</span> <span class="n">Iterator</span><span class="p">,</span> <span class="n">Iterable</span>1000 1001<span class="k">class</span><span class="w"> </span><span class="nc">Bucket</span><span class="p">:</span> <span class="c1"># Note: no base classes</span>1002 <span class="o">...</span>1003 <span class="k">def</span><span class="w"> </span><span class="fm">__len__</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">-></span> <span class="nb">int</span><span class="p">:</span> <span class="o">...</span>1004 <span class="k">def</span><span class="w"> </span><span class="fm">__iter__</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">-></span> <span class="n">Iterator</span><span class="p">[</span><span class="nb">int</span><span class="p">]:</span> <span class="o">...</span>1005 1006<span class="k">def</span><span class="w"> </span><span class="nf">collect</span><span class="p">(</span><span class="n">items</span><span class="p">:</span> <span class="n">Iterable</span><span class="p">[</span><span class="nb">int</span><span class="p">])</span> <span class="o">-></span> <span class="nb">int</span><span class="p">:</span> <span class="o">...</span>1007<span class="n">result</span> <span class="o">=</span> <span class="n">collect</span><span class="p">(</span><span class="n">Bucket</span><span class="p">())</span> <span class="c1"># Passes type check</span>1008</pre></div>1009</div>1010<p>Moreover, by subclassing a special class <a class="reference internal" href="#typing.Protocol" title="typing.Protocol"><code class="xref py py-class docutils literal notranslate"><span class="pre">Protocol</span></code></a>, a user1011can define new custom protocols to fully enjoy structural subtyping1012(see examples below).</p>1013</section>1014<section id="module-contents">1015<h2>Module contents<a class="headerlink" href="#module-contents" title="Link to this heading">¶</a></h2>1016<p>The <code class="docutils literal notranslate"><span class="pre">typing</span></code> module defines the following classes, functions and decorators.</p>1017<section id="special-typing-primitives">1018<h3>Special typing primitives<a class="headerlink" href="#special-typing-primitives" title="Link to this heading">¶</a></h3>1019<section id="special-types">1020<h4>Special types<a class="headerlink" href="#special-types" title="Link to this heading">¶</a></h4>1021<p>These can be used as types in annotations. They do not support subscription1022using <code class="docutils literal notranslate"><span class="pre">[]</span></code>.</p>1023<dl class="py data">1024<dt class="sig sig-object py" id="typing.Any">1025<span class="sig-prename descclassname"><span class="pre">typing.</span></span><span class="sig-name descname"><span class="pre">Any</span></span><a class="headerlink" href="#typing.Any" title="Link to this definition">¶</a></dt>1026<dd><p>Special type indicating an unconstrained type.</p>1027<ul class="simple">1028<li><p>Every type is compatible with <code class="xref py py-data docutils literal notranslate"><span class="pre">Any</span></code>.</p></li>1029<li><p><code class="xref py py-data docutils literal notranslate"><span class="pre">Any</span></code> is compatible with every type.</p></li>1030</ul>1031<div class="versionchanged">1032<p><span class="versionmodified changed">Changed in version 3.11: </span><code class="xref py py-data docutils literal notranslate"><span class="pre">Any</span></code> can now be used as a base class. This can be useful for1033avoiding type checker errors with classes that can duck type anywhere or1034are highly dynamic.</p>1035</div>1036</dd></dl>1037 1038<dl class="py data">1039<dt class="sig sig-object py" id="typing.AnyStr">1040<span class="sig-prename descclassname"><span class="pre">typing.</span></span><span class="sig-name descname"><span class="pre">AnyStr</span></span><a class="headerlink" href="#typing.AnyStr" title="Link to this definition">¶</a></dt>1041<dd><p>A <a class="reference internal" href="#typing-constrained-typevar"><span class="std std-ref">constrained type variable</span></a>.</p>1042<p>Definition:</p>1043<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">AnyStr</span> <span class="o">=</span> <span class="n">TypeVar</span><span class="p">(</span><span class="s1">'AnyStr'</span><span class="p">,</span> <span class="nb">str</span><span class="p">,</span> <span class="nb">bytes</span><span class="p">)</span>1044</pre></div>1045</div>1046<p><code class="docutils literal notranslate"><span class="pre">AnyStr</span></code> is meant to be used for functions that may accept <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> or1047<a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> arguments but cannot allow the two to mix.</p>1048<p>For example:</p>1049<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">concat</span><span class="p">(</span><span class="n">a</span><span class="p">:</span> <span class="n">AnyStr</span><span class="p">,</span> <span class="n">b</span><span class="p">:</span> <span class="n">AnyStr</span><span class="p">)</span> <span class="o">-></span> <span class="n">AnyStr</span><span class="p">:</span>1050 <span class="k">return</span> <span class="n">a</span> <span class="o">+</span> <span class="n">b</span>1051 1052<span class="n">concat</span><span class="p">(</span><span class="s2">"foo"</span><span class="p">,</span> <span class="s2">"bar"</span><span class="p">)</span> <span class="c1"># OK, output has type 'str'</span>1053<span class="n">concat</span><span class="p">(</span><span class="sa">b</span><span class="s2">"foo"</span><span class="p">,</span> <span class="sa">b</span><span class="s2">"bar"</span><span class="p">)</span> <span class="c1"># OK, output has type 'bytes'</span>1054<span class="n">concat</span><span class="p">(</span><span class="s2">"foo"</span><span class="p">,</span> <span class="sa">b</span><span class="s2">"bar"</span><span class="p">)</span> <span class="c1"># Error, cannot mix str and bytes</span>1055</pre></div>1056</div>1057<p>Note that, despite its name, <code class="docutils literal notranslate"><span class="pre">AnyStr</span></code> has nothing to do with the1058<a class="reference internal" href="#typing.Any" title="typing.Any"><code class="xref py py-class docutils literal notranslate"><span class="pre">Any</span></code></a> type, nor does it mean “any string”. In particular, <code class="docutils literal notranslate"><span class="pre">AnyStr</span></code>1059and <code class="docutils literal notranslate"><span class="pre">str</span> <span class="pre">|</span> <span class="pre">bytes</span></code> are different from each other and have different use1060cases:</p>1061<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="c1"># Invalid use of AnyStr:</span>1062<span class="c1"># The type variable is used only once in the function signature,</span>1063<span class="c1"># so cannot be "solved" by the type checker</span>1064<span class="k">def</span><span class="w"> </span><span class="nf">greet_bad</span><span class="p">(</span><span class="n">cond</span><span class="p">:</span> <span class="nb">bool</span><span class="p">)</span> <span class="o">-></span> <span class="n">AnyStr</span><span class="p">:</span>1065 <span class="k">return</span> <span class="s2">"hi there!"</span> <span class="k">if</span> <span class="n">cond</span> <span class="k">else</span> <span class="sa">b</span><span class="s2">"greetings!"</span>1066 1067<span class="c1"># The better way of annotating this function:</span>1068<span class="k">def</span><span class="w"> </span><span class="nf">greet_proper</span><span class="p">(</span><span class="n">cond</span><span class="p">:</span> <span class="nb">bool</span><span class="p">)</span> <span class="o">-></span> <span class="nb">str</span> <span class="o">|</span> <span class="nb">bytes</span><span class="p">:</span>1069 <span class="k">return</span> <span class="s2">"hi there!"</span> <span class="k">if</span> <span class="n">cond</span> <span class="k">else</span> <span class="sa">b</span><span class="s2">"greetings!"</span>1070</pre></div>1071</div>1072<div class="deprecated-removed">1073<p><span class="versionmodified deprecated">Deprecated since version 3.13, will be removed in version 3.18: </span>Deprecated in favor of the new <a class="reference internal" href="../reference/compound_stmts.html#type-params"><span class="std std-ref">type parameter syntax</span></a>.1074Use <code class="docutils literal notranslate"><span class="pre">class</span> <span class="pre">A[T:</span> <span class="pre">(str,</span> <span class="pre">bytes)]:</span> <span class="pre">...</span></code> instead of importing <code class="docutils literal notranslate"><span class="pre">AnyStr</span></code>. See1075<span class="target" id="index-8"></span><a class="pep reference external" href="https://peps.python.org/pep-0695/"><strong>PEP 695</strong></a> for more details.</p>1076<p>In Python 3.16, <code class="docutils literal notranslate"><span class="pre">AnyStr</span></code> will be removed from <code class="docutils literal notranslate"><span class="pre">typing.__all__</span></code>, and1077deprecation warnings will be emitted at runtime when it is accessed or1078imported from <code class="docutils literal notranslate"><span class="pre">typing</span></code>. <code class="docutils literal notranslate"><span class="pre">AnyStr</span></code> will be removed from <code class="docutils literal notranslate"><span class="pre">typing</span></code>1079in Python 3.18.</p>1080</div>1081</dd></dl>1082 1083<dl class="py data">1084<dt class="sig sig-object py" id="typing.LiteralString">1085<span class="sig-prename descclassname"><span class="pre">typing.</span></span><span class="sig-name descname"><span class="pre">LiteralString</span></span><a class="headerlink" href="#typing.LiteralString" title="Link to this definition">¶</a></dt>1086<dd><p>Special type that includes only literal strings.</p>1087<p>Any string1088literal is compatible with <code class="docutils literal notranslate"><span class="pre">LiteralString</span></code>, as is another1089<code class="docutils literal notranslate"><span class="pre">LiteralString</span></code>. However, an object typed as just <code class="docutils literal notranslate"><span class="pre">str</span></code> is not.1090A string created by composing <code class="docutils literal notranslate"><span class="pre">LiteralString</span></code>-typed objects1091is also acceptable as a <code class="docutils literal notranslate"><span class="pre">LiteralString</span></code>.</p>1092<p>Example:</p>1093<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">run_query</span><span class="p">(</span><span class="n">sql</span><span class="p">:</span> <span class="n">LiteralString</span><span class="p">)</span> <span class="o">-></span> <span class="kc">None</span><span class="p">:</span>1094 <span class="o">...</span>1095 1096<span class="k">def</span><span class="w"> </span><span class="nf">caller</span><span class="p">(</span><span class="n">arbitrary_string</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">literal_string</span><span class="p">:</span> <span class="n">LiteralString</span><span class="p">)</span> <span class="o">-></span> <span class="kc">None</span><span class="p">:</span>1097 <span class="n">run_query</span><span class="p">(</span><span class="s2">"SELECT * FROM students"</span><span class="p">)</span> <span class="c1"># OK</span>1098 <span class="n">run_query</span><span class="p">(</span><span class="n">literal_string</span><span class="p">)</span> <span class="c1"># OK</span>1099 <span class="n">run_query</span><span class="p">(</span><span class="s2">"SELECT * FROM "</span> <span class="o">+</span> <span class="n">literal_string</span><span class="p">)</span> <span class="c1"># OK</span>1100 <span class="n">run_query</span><span class="p">(</span><span class="n">arbitrary_string</span><span class="p">)</span> <span class="c1"># type checker error</span>1101 <span class="n">run_query</span><span class="p">(</span> <span class="c1"># type checker error</span>1102 <span class="sa">f</span><span class="s2">"SELECT * FROM students WHERE name = </span><span class="si">{</span><span class="n">arbitrary_string</span><span class="si">}</span><span class="s2">"</span>1103 <span class="p">)</span>1104</pre></div>1105</div>1106<p><code class="docutils literal notranslate"><span class="pre">LiteralString</span></code> is useful for sensitive APIs where arbitrary user-generated1107strings could generate problems. For example, the two cases above1108that generate type checker errors could be vulnerable to an SQL1109injection attack.</p>1110<p>See <span class="target" id="index-9"></span><a class="pep reference external" href="https://peps.python.org/pep-0675/"><strong>PEP 675</strong></a> for more details.</p>1111<div class="versionadded">1112<p><span class="versionmodified added">Added in version 3.11.</span></p>1113</div>1114</dd></dl>1115 1116<dl class="py data">1117<dt class="sig sig-object py" id="typing.Never">1118<span class="sig-prename descclassname"><span class="pre">typing.</span></span><span class="sig-name descname"><span class="pre">Never</span></span><a class="headerlink" href="#typing.Never" title="Link to this definition">¶</a></dt>1119<dt class="sig sig-object py" id="typing.NoReturn">1120<span class="sig-prename descclassname"><span class="pre">typing.</span></span><span class="sig-name descname"><span class="pre">NoReturn</span></span><a class="headerlink" href="#typing.NoReturn" title="Link to this definition">¶</a></dt>1121<dd><p><code class="xref py py-data docutils literal notranslate"><span class="pre">Never</span></code> and <code class="xref py py-data docutils literal notranslate"><span class="pre">NoReturn</span></code> represent the1122<a class="reference external" href="https://en.wikipedia.org/wiki/Bottom_type">bottom type</a>,1123a type that has no members.</p>1124<p>They can be used to indicate that a function never returns,1125such as <a class="reference internal" href="sys.html#sys.exit" title="sys.exit"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.exit()</span></code></a>:</p>1126<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">typing</span><span class="w"> </span><span class="kn">import</span> <span class="n">Never</span> <span class="c1"># or NoReturn</span>1127 1128<span class="k">def</span><span class="w"> </span><span class="nf">stop</span><span class="p">()</span> <span class="o">-></span> <span class="n">Never</span><span class="p">:</span>1129 <span class="k">raise</span> <span class="ne">RuntimeError</span><span class="p">(</span><span class="s1">'no way'</span><span class="p">)</span>1130</pre></div>1131</div>1132<p>Or to define a function that should never be1133called, as there are no valid arguments, such as1134<a class="reference internal" href="#typing.assert_never" title="typing.assert_never"><code class="xref py py-func docutils literal notranslate"><span class="pre">assert_never()</span></code></a>:</p>1135<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">typing</span><span class="w"> </span><span class="kn">import</span> <span class="n">Never</span> <span class="c1"># or NoReturn</span>1136 1137<span class="k">def</span><span class="w"> </span><span class="nf">never_call_me</span><span class="p">(</span><span class="n">arg</span><span class="p">:</span> <span class="n">Never</span><span class="p">)</span> <span class="o">-></span> <span class="kc">None</span><span class="p">:</span>1138 <span class="k">pass</span>1139 1140<span class="k">def</span><span class="w"> </span><span class="nf">int_or_str</span><span class="p">(</span><span class="n">arg</span><span class="p">:</span> <span class="nb">int</span> <span class="o">|</span> <span class="nb">str</span><span class="p">)</span> <span class="o">-></span> <span class="kc">None</span><span class="p">:</span>1141 <span class="n">never_call_me</span><span class="p">(</span><span class="n">arg</span><span class="p">)</span> <span class="c1"># type checker error</span>1142 <span class="k">match</span> <span class="n">arg</span><span class="p">:</span>1143 <span class="k">case</span> <span class="nb">int</span><span class="p">():</span>1144 <span class="nb">print</span><span class="p">(</span><span class="s2">"It's an int"</span><span class="p">)</span>1145 <span class="k">case</span> <span class="nb">str</span><span class="p">():</span>1146 <span class="nb">print</span><span class="p">(</span><span class="s2">"It's a str"</span><span class="p">)</span>1147 <span class="k">case</span><span class="w"> </span><span class="k">_</span><span class="p">:</span>1148 <span class="n">never_call_me</span><span class="p">(</span><span class="n">arg</span><span class="p">)</span> <span class="c1"># OK, arg is of type Never (or NoReturn)</span>1149</pre></div>1150</div>1151<p><code class="xref py py-data docutils literal notranslate"><span class="pre">Never</span></code> and <code class="xref py py-data docutils literal notranslate"><span class="pre">NoReturn</span></code> have the same meaning in the type system1152and static type checkers treat both equivalently.</p>1153<div class="versionadded">1154<p><span class="versionmodified added">Added in version 3.6.2: </span>Added <code class="xref py py-data docutils literal notranslate"><span class="pre">NoReturn</span></code>.</p>1155</div>1156<div class="versionadded">1157<p><span class="versionmodified added">Added in version 3.11: </span>Added <code class="xref py py-data docutils literal notranslate"><span class="pre">Never</span></code>.</p>1158</div>1159</dd></dl>1160 1161<dl class="py data">1162<dt class="sig sig-object py" id="typing.Self">1163<span class="sig-prename descclassname"><span class="pre">typing.</span></span><span class="sig-name descname"><span class="pre">Self</span></span><a class="headerlink" href="#typing.Self" title="Link to this definition">¶</a></dt>1164<dd><p>Special type to represent the current enclosed class.</p>1165<p>For example:</p>1166<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">typing</span><span class="w"> </span><span class="kn">import</span> <span class="n">Self</span><span class="p">,</span> <span class="n">reveal_type</span>1167 1168<span class="k">class</span><span class="w"> </span><span class="nc">Foo</span><span class="p">:</span>1169 <span class="k">def</span><span class="w"> </span><span class="nf">return_self</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">-></span> <span class="n">Self</span><span class="p">:</span>1170 <span class="o">...</span>1171 <span class="k">return</span> <span class="bp">self</span>1172 1173<span class="k">class</span><span class="w"> </span><span class="nc">SubclassOfFoo</span><span class="p">(</span><span class="n">Foo</span><span class="p">):</span> <span class="k">pass</span>1174 1175<span class="n">reveal_type</span><span class="p">(</span><span class="n">Foo</span><span class="p">()</span><span class="o">.</span><span class="n">return_self</span><span class="p">())</span> <span class="c1"># Revealed type is "Foo"</span>1176<span class="n">reveal_type</span><span class="p">(</span><span class="n">SubclassOfFoo</span><span class="p">()</span><span class="o">.</span><span class="n">return_self</span><span class="p">())</span> <span class="c1"># Revealed type is "SubclassOfFoo"</span>1177</pre></div>1178</div>1179<p>This annotation is semantically equivalent to the following,1180albeit in a more succinct fashion:</p>1181<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">typing</span><span class="w"> </span><span class="kn">import</span> <span class="n">TypeVar</span>1182 1183<span class="n">Self</span> <span class="o">=</span> <span class="n">TypeVar</span><span class="p">(</span><span class="s2">"Self"</span><span class="p">,</span> <span class="n">bound</span><span class="o">=</span><span class="s2">"Foo"</span><span class="p">)</span>1184 1185<span class="k">class</span><span class="w"> </span><span class="nc">Foo</span><span class="p">:</span>1186 <span class="k">def</span><span class="w"> </span><span class="nf">return_self</span><span class="p">(</span><span class="bp">self</span><span class="p">:</span> <span class="n">Self</span><span class="p">)</span> <span class="o">-></span> <span class="n">Self</span><span class="p">:</span>1187 <span class="o">...</span>1188 <span class="k">return</span> <span class="bp">self</span>1189</pre></div>1190</div>1191<p>In general, if something returns <code class="docutils literal notranslate"><span class="pre">self</span></code>, as in the above examples, you1192should use <code class="docutils literal notranslate"><span class="pre">Self</span></code> as the return annotation. If <code class="docutils literal notranslate"><span class="pre">Foo.return_self</span></code> was1193annotated as returning <code class="docutils literal notranslate"><span class="pre">"Foo"</span></code>, then the type checker would infer the1194object returned from <code class="docutils literal notranslate"><span class="pre">SubclassOfFoo.return_self</span></code> as being of type <code class="docutils literal notranslate"><span class="pre">Foo</span></code>1195rather than <code class="docutils literal notranslate"><span class="pre">SubclassOfFoo</span></code>.</p>1196<p>Other common use cases include:</p>1197<ul class="simple">1198<li><p><a class="reference internal" href="functions.html#classmethod" title="classmethod"><code class="xref py py-class docutils literal notranslate"><span class="pre">classmethod</span></code></a>s that are used as alternative constructors and return instances1199of the <code class="docutils literal notranslate"><span class="pre">cls</span></code> parameter.</p></li>1200<li><p>Annotating an <a class="reference internal" href="../reference/datamodel.html#object.__enter__" title="object.__enter__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__enter__()</span></code></a> method which returns self.</p></li>