CINXE.COM

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta name="color-scheme" content="light dark"> <title>PEP 561 – Distributing and Packaging Type Information | peps.python.org</title> <link rel="shortcut icon" href="../_static/py.png"> <link rel="canonical" href="https://peps.python.org/pep-0561/"> <link rel="stylesheet" href="../_static/style.css" type="text/css"> <link rel="stylesheet" href="../_static/mq.css" type="text/css"> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" media="(prefers-color-scheme: light)" id="pyg-light"> <link rel="stylesheet" href="../_static/pygments_dark.css" type="text/css" media="(prefers-color-scheme: dark)" id="pyg-dark"> <link rel="alternate" type="application/rss+xml" title="Latest PEPs" href="https://peps.python.org/peps.rss"> <meta property="og:title" content='PEP 561 – Distributing and Packaging Type Information | peps.python.org'> <meta property="og:description" content="PEP 484 introduced type hinting to Python, with goals of making typing gradual and easy to adopt. Currently, typing information must be distributed manually. This PEP provides a standardized means to leverage existing tooling to package and distribute t..."> <meta property="og:type" content="website"> <meta property="og:url" content="https://peps.python.org/pep-0561/"> <meta property="og:site_name" content="Python Enhancement Proposals (PEPs)"> <meta property="og:image" content="https://peps.python.org/_static/og-image.png"> <meta property="og:image:alt" content="Python PEPs"> <meta property="og:image:width" content="200"> <meta property="og:image:height" content="200"> <meta name="description" content="PEP 484 introduced type hinting to Python, with goals of making typing gradual and easy to adopt. Currently, typing information must be distributed manually. This PEP provides a standardized means to leverage existing tooling to package and distribute t..."> <meta name="theme-color" content="#3776ab"> </head> <body> <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> <symbol id="svg-sun-half" viewBox="0 0 24 24" pointer-events="all"> <title>Following system colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="9"></circle> <path d="M12 3v18m0-12l4.65-4.65M12 14.3l7.37-7.37M12 19.6l8.85-8.85"></path> </svg> </symbol> <symbol id="svg-moon" viewBox="0 0 24 24" pointer-events="all"> <title>Selected dark colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <path stroke="none" d="M0 0h24v24H0z" fill="none"></path> <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z"></path> </svg> </symbol> <symbol id="svg-sun" viewBox="0 0 24 24" pointer-events="all"> <title>Selected light colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="5"></circle> <line x1="12" y1="1" x2="12" y2="3"></line> <line x1="12" y1="21" x2="12" y2="23"></line> <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line> <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line> <line x1="1" y1="12" x2="3" y2="12"></line> <line x1="21" y1="12" x2="23" y2="12"></line> <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line> <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line> </svg> </symbol> </svg> <script> document.documentElement.dataset.colour_scheme = localStorage.getItem("colour_scheme") || "auto" </script> <section id="pep-page-section"> <header> <h1>Python Enhancement Proposals</h1> <ul class="breadcrumbs"> <li><a href="https://www.python.org/" title="The Python Programming Language">Python</a> » </li> <li><a href="../pep-0000/">PEP Index</a> » </li> <li>PEP 561</li> </ul> <button id="colour-scheme-cycler" onClick="setColourScheme(nextColourScheme())"> <svg aria-hidden="true" class="colour-scheme-icon-when-auto"><use href="#svg-sun-half"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-dark"><use href="#svg-moon"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-light"><use href="#svg-sun"></use></svg> <span class="visually-hidden">Toggle light / dark / auto colour theme</span> </button> </header> <article> <section id="pep-content"> <h1 class="page-title">PEP 561 – Distributing and Packaging Type Information</h1> <dl class="rfc2822 field-list simple"> <dt class="field-odd">Author<span class="colon">:</span></dt> <dd class="field-odd">Emma Harper Smith <emma at python.org></dd> <dt class="field-even">Status<span class="colon">:</span></dt> <dd class="field-even"><abbr title="Accepted and implementation complete, or no longer active">Final</abbr></dd> <dt class="field-odd">Type<span class="colon">:</span></dt> <dd class="field-odd"><abbr title="Normative PEP with a new feature for Python, implementation change for CPython or interoperability standard for the ecosystem">Standards Track</abbr></dd> <dt class="field-even">Topic<span class="colon">:</span></dt> <dd class="field-even"><a class="reference external" href="../topic/packaging/">Packaging</a>, <a class="reference external" href="../topic/typing/"> Typing</a></dd> <dt class="field-odd">Created<span class="colon">:</span></dt> <dd class="field-odd">09-Sep-2017</dd> <dt class="field-even">Python-Version<span class="colon">:</span></dt> <dd class="field-even">3.7</dd> <dt class="field-odd">Post-History<span class="colon">:</span></dt> <dd class="field-odd">10-Sep-2017, 12-Sep-2017, 06-Oct-2017, 26-Oct-2017, 12-Apr-2018</dd> </dl> <hr class="docutils" /> <section id="contents"> <details><summary>Table of Contents</summary><ul class="simple"> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#rationale">Rationale</a></li> <li><a class="reference internal" href="#definition-of-terms">Definition of Terms</a></li> <li><a class="reference internal" href="#specification">Specification</a><ul> <li><a class="reference internal" href="#packaging-type-information">Packaging Type Information</a><ul> <li><a class="reference internal" href="#stub-only-packages">Stub-only Packages</a></li> </ul> </li> <li><a class="reference internal" href="#type-checker-module-resolution-order">Type Checker Module Resolution Order</a></li> <li><a class="reference internal" href="#partial-stub-packages">Partial Stub Packages</a></li> </ul> </li> <li><a class="reference internal" href="#implementation">Implementation</a></li> <li><a class="reference internal" href="#acknowledgements">Acknowledgements</a></li> <li><a class="reference internal" href="#version-history">Version History</a></li> <li><a class="reference internal" href="#references">References</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> </details></section> <div class="pep-banner canonical-typing-spec sticky-banner admonition important"> <p class="admonition-title">Important</p> <p>This PEP is a historical document: see <a class="reference external" href="https://typing.python.org/en/latest/spec/distributing.html#packaging-typed-libraries" title="(in typing)"><span>Type information in libraries</span></a> for up-to-date specs and documentation. Canonical typing specs are maintained at the <a class="reference external" href="https://typing.python.org/en/latest/spec/">typing specs site</a>; runtime typing behaviour is described in the CPython documentation.</p> <p class="close-button">×</p> <p>See the <a class="reference external" href="https://typing.python.org/en/latest/spec/meta.html">typing specification update process</a> for how to propose changes to the typing spec.</p> </div> <section id="abstract"> <h2><a class="toc-backref" href="#abstract" role="doc-backlink">Abstract</a></h2> <p><a class="pep reference internal" href="../pep-0484/" title="PEP 484 – Type Hints">PEP 484</a> introduced type hinting to Python, with goals of making typing gradual and easy to adopt. Currently, typing information must be distributed manually. This PEP provides a standardized means to leverage existing tooling to package and distribute type information with minimal work and an ordering for type checkers to resolve modules and collect this information for type checking.</p> </section> <section id="rationale"> <h2><a class="toc-backref" href="#rationale" role="doc-backlink">Rationale</a></h2> <p>Currently, package authors wish to distribute code that has inline type information. Additionally, maintainers would like to distribute stub files to keep Python 2 compatibility while using newer annotation syntax. However, there is no standard method to distribute packages with type information. Also, if one wished to ship stub files privately the only method available would be via setting <code class="docutils literal notranslate"><span class="pre">MYPYPATH</span></code> or the equivalent to manually point to stubs. If the package can be released publicly, it can be added to typeshed <a class="footnote-reference brackets" href="#id7" id="id1">[1]</a>. However, this does not scale and becomes a burden on the maintainers of typeshed. In addition, it ties bug fixes in stubs to releases of the tool using typeshed.</p> <p><a class="pep reference internal" href="../pep-0484/" title="PEP 484 – Type Hints">PEP 484</a> has a brief section on distributing typing information. In this <a class="pep reference internal" href="../pep-0484/#storing-and-distributing-stub-files" title="PEP 484 – Type Hints § Storing and distributing stub files">section</a> the PEP recommends using <code class="docutils literal notranslate"><span class="pre">shared/typehints/pythonX.Y/</span></code> for shipping stub files. However, manually adding a path to stub files for each third party library does not scale. The simplest approach people have taken is to add <code class="docutils literal notranslate"><span class="pre">site-packages</span></code> to their <code class="docutils literal notranslate"><span class="pre">MYPYPATH</span></code>, but this causes type checkers to fail on packages that are highly dynamic (e.g. sqlalchemy and Django).</p> </section> <section id="definition-of-terms"> <h2><a class="toc-backref" href="#definition-of-terms" role="doc-backlink">Definition of Terms</a></h2> <p>The definition of “MAY”, “MUST”, and “SHOULD”, and “SHOULD NOT” are to be interpreted as described in <span class="target" id="index-0"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2119.html"><strong>RFC 2119</strong></a>.</p> <p>“inline” - the types are part of the runtime code using <a class="pep reference internal" href="../pep-0526/" title="PEP 526 – Syntax for Variable Annotations">PEP 526</a> and <a class="pep reference internal" href="../pep-3107/" title="PEP 3107 – Function Annotations">PEP 3107</a> syntax (the filename ends in <code class="docutils literal notranslate"><span class="pre">.py</span></code>).</p> <p>“stubs” - files containing only type information, empty of runtime code (the filename ends in <code class="docutils literal notranslate"><span class="pre">.pyi</span></code>).</p> <p>“Distributions” are the packaged files which are used to publish and distribute a release. (<a class="pep reference internal" href="../pep-0426/" title="PEP 426 – Metadata for Python Software Packages 2.0">PEP 426</a>)</p> <p>“Module” a file containing Python runtime code or stubbed type information.</p> <p>“Package” a directory or directories that namespace Python modules. (Note the distinction between packages and distributions. While most distributions are named after the one package they install, some distributions install multiple packages.)</p> </section> <section id="specification"> <h2><a class="toc-backref" href="#specification" role="doc-backlink">Specification</a></h2> <p>There are several motivations and methods of supporting typing in a package. This PEP recognizes three types of packages that users of typing wish to create:</p> <ol class="arabic simple"> <li>The package maintainer would like to add type information inline.</li> <li>The package maintainer would like to add type information via stubs.</li> <li>A third party or package maintainer would like to share stub files for a package, but the maintainer does not want to include them in the source of the package.</li> </ol> <p>This PEP aims to support all three scenarios and make them simple to add to packaging and deployment.</p> <p>The two major parts of this specification are the packaging specifications and the resolution order for resolving module type information. The type checking spec is meant to replace the <code class="docutils literal notranslate"><span class="pre">shared/typehints/pythonX.Y/</span></code> <a class="pep reference internal" href="../pep-0484/#storing-and-distributing-stub-files" title="PEP 484 – Type Hints § Storing and distributing stub files">spec of PEP 484</a>.</p> <p>New third party stub libraries SHOULD distribute stubs via the third party packaging methods proposed in this PEP in place of being added to typeshed. Typeshed will remain in use, but if maintainers are found, third party stubs in typeshed MAY be split into their own package.</p> <section id="packaging-type-information"> <h3><a class="toc-backref" href="#packaging-type-information" role="doc-backlink">Packaging Type Information</a></h3> <p>In order to make packaging and distributing type information as simple and easy as possible, packaging and distribution is done through existing frameworks.</p> <p>Package maintainers who wish to support type checking of their code MUST add a marker file named <code class="docutils literal notranslate"><span class="pre">py.typed</span></code> to their package supporting typing. This marker applies recursively: if a top-level package includes it, all its sub-packages MUST support type checking as well. To have this file installed with the package, maintainers can use existing packaging options such as <code class="docutils literal notranslate"><span class="pre">package_data</span></code> in distutils, shown below.</p> <p>Distutils option example:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="p">(</span> <span class="o">...</span><span class="p">,</span> <span class="n">package_data</span> <span class="o">=</span> <span class="p">{</span> <span class="s1">'foopkg'</span><span class="p">:</span> <span class="p">[</span><span class="s1">'py.typed'</span><span class="p">],</span> <span class="p">},</span> <span class="o">...</span><span class="p">,</span> <span class="p">)</span> </pre></div> </div> <p>For namespace packages (see <a class="pep reference internal" href="../pep-0420/" title="PEP 420 – Implicit Namespace Packages">PEP 420</a>), the <code class="docutils literal notranslate"><span class="pre">py.typed</span></code> file should be in the submodules of the namespace, to avoid conflicts and for clarity.</p> <p>This PEP does not support distributing typing information as part of module-only distributions or single-file modules within namespace packages.</p> <p>The single-file module should be refactored into a package and indicate that the package supports typing as described above.</p> <section id="stub-only-packages"> <h4><a class="toc-backref" href="#stub-only-packages" role="doc-backlink">Stub-only Packages</a></h4> <p>For package maintainers wishing to ship stub files containing all of their type information, it is preferred that the <code class="docutils literal notranslate"><span class="pre">*.pyi</span></code> stubs are alongside the corresponding <code class="docutils literal notranslate"><span class="pre">*.py</span></code> files. However, the stubs can also be put in a separate package and distributed separately. Third parties can also find this method useful if they wish to distribute stub files. The name of the stub package MUST follow the scheme <code class="docutils literal notranslate"><span class="pre">foopkg-stubs</span></code> for type stubs for the package named <code class="docutils literal notranslate"><span class="pre">foopkg</span></code>. Note that for stub-only packages adding a <code class="docutils literal notranslate"><span class="pre">py.typed</span></code> marker is not needed since the name <code class="docutils literal notranslate"><span class="pre">*-stubs</span></code> is enough to indicate it is a source of typing information.</p> <p>Third parties seeking to distribute stub files are encouraged to contact the maintainer of the package about distribution alongside the package. If the maintainer does not wish to maintain or package stub files or type information inline, then a third party stub-only package can be created.</p> <p>In addition, stub-only distributions SHOULD indicate which version(s) of the runtime package are supported by indicating the runtime distribution’s version(s) through normal dependency data. For example, the stub package <code class="docutils literal notranslate"><span class="pre">flyingcircus-stubs</span></code> can indicate the versions of the runtime <code class="docutils literal notranslate"><span class="pre">flyingcircus</span></code> distribution it supports through <code class="docutils literal notranslate"><span class="pre">install_requires</span></code> in distutils-based tools, or the equivalent in other packaging tools. Note that in pip 9.0, if you update <code class="docutils literal notranslate"><span class="pre">flyingcircus-stubs</span></code>, it will update <code class="docutils literal notranslate"><span class="pre">flyingcircus</span></code>. In pip 9.0, you can use the <code class="docutils literal notranslate"><span class="pre">--upgrade-strategy=only-if-needed</span></code> flag. In pip 10.0 this is the default behavior.</p> <p>For namespace packages (see <a class="pep reference internal" href="../pep-0420/" title="PEP 420 – Implicit Namespace Packages">PEP 420</a>), stub-only packages should use the <code class="docutils literal notranslate"><span class="pre">-stubs</span></code> suffix on only the root namespace package. All stub-only namespace packages should omit <code class="docutils literal notranslate"><span class="pre">__init__.pyi</span></code> files. <code class="docutils literal notranslate"><span class="pre">py.typed</span></code> marker files are not necessary for stub-only packages, but similarly to packages with inline types, if used, they should be in submodules of the namespace to avoid conflicts and for clarity.</p> <p>For example, if the <code class="docutils literal notranslate"><span class="pre">pentagon</span></code> and <code class="docutils literal notranslate"><span class="pre">hexagon</span></code> are separate distributions installing within the namespace package <code class="docutils literal notranslate"><span class="pre">shapes.polygons</span></code> The corresponding types-only distributions should produce packages laid out as follows:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>shapes-stubs └── polygons └── pentagon └── __init__.pyi shapes-stubs └── polygons └── hexagon └── __init__.pyi </pre></div> </div> </section> </section> <section id="type-checker-module-resolution-order"> <span id="mro"></span><h3><a class="toc-backref" href="#type-checker-module-resolution-order" role="doc-backlink">Type Checker Module Resolution Order</a></h3> <p>The following is the order in which type checkers supporting this PEP SHOULD resolve modules containing type information:</p> <ol class="arabic simple"> <li>Stubs or Python source manually put in the beginning of the path. Type checkers SHOULD provide this to allow the user complete control of which stubs to use, and to patch broken stubs/inline types from packages. In mypy the <code class="docutils literal notranslate"><span class="pre">$MYPYPATH</span></code> environment variable can be used for this.</li> <li>User code - the files the type checker is running on.</li> <li>Stub packages - these packages SHOULD supersede any installed inline package. They can be found at <code class="docutils literal notranslate"><span class="pre">foopkg-stubs</span></code> for package <code class="docutils literal notranslate"><span class="pre">foopkg</span></code>.</li> <li>Packages with a <code class="docutils literal notranslate"><span class="pre">py.typed</span></code> marker file - if there is nothing overriding the installed package, <em>and</em> it opts into type checking, the types bundled with the package SHOULD be used (be they in <code class="docutils literal notranslate"><span class="pre">.pyi</span></code> type stub files or inline in <code class="docutils literal notranslate"><span class="pre">.py</span></code> files).</li> <li>Typeshed (if used) - Provides the stdlib types and several third party libraries.</li> </ol> <p>If typecheckers identify a stub-only namespace package without the desired module in step 3, they should continue to step 4/5. Typecheckers should identify namespace packages by the absence of <code class="docutils literal notranslate"><span class="pre">__init__.pyi</span></code>. This allows different subpackages to independently opt for inline vs stub-only.</p> <p>Type checkers that check a different Python version than the version they run on MUST find the type information in the <code class="docutils literal notranslate"><span class="pre">site-packages</span></code>/<code class="docutils literal notranslate"><span class="pre">dist-packages</span></code> of that Python version. This can be queried e.g. <code class="docutils literal notranslate"><span class="pre">pythonX.Y</span> <span class="pre">-c</span> <span class="pre">'import</span> <span class="pre">site;</span> <span class="pre">print(site.getsitepackages())'</span></code>. It is also recommended that the type checker allow for the user to point to a particular Python binary, in case it is not in the path.</p> </section> <section id="partial-stub-packages"> <h3><a class="toc-backref" href="#partial-stub-packages" role="doc-backlink">Partial Stub Packages</a></h3> <p>Many stub packages will only have part of the type interface for libraries completed, especially initially. For the benefit of type checking and code editors, packages can be “partial”. This means modules not found in the stub package SHOULD be searched for in parts four and five of the module resolution order above, namely inline packages and typeshed.</p> <p>Type checkers should merge the stub package and runtime package or typeshed directories. This can be thought of as the functional equivalent of copying the stub package into the same directory as the corresponding runtime package or typeshed folder and type checking the combined directory structure. Thus type checkers MUST maintain the normal resolution order of checking <code class="docutils literal notranslate"><span class="pre">*.pyi</span></code> before <code class="docutils literal notranslate"><span class="pre">*.py</span></code> files.</p> <p>If a stub package distribution is partial it MUST include <code class="docutils literal notranslate"><span class="pre">partial\n</span></code> in a <code class="docutils literal notranslate"><span class="pre">py.typed</span></code> file. For stub-packages distributing within a namespace package (see <a class="pep reference internal" href="../pep-0420/" title="PEP 420 – Implicit Namespace Packages">PEP 420</a>), the <code class="docutils literal notranslate"><span class="pre">py.typed</span></code> file should be in the submodules of the namespace.</p> <p>Type checkers should treat namespace packages within stub-packages as incomplete since multiple distributions may populate them. Regular packages within namespace packages in stub-package distributions are considered complete unless a <code class="docutils literal notranslate"><span class="pre">py.typed</span></code> with <code class="docutils literal notranslate"><span class="pre">partial\n</span></code> is included.</p> </section> </section> <section id="implementation"> <h2><a class="toc-backref" href="#implementation" role="doc-backlink">Implementation</a></h2> <p>The proposed scheme of indicating support for typing is completely backwards compatible, and requires no modification to package tooling. A sample package with inline types is available <a class="reference internal" href="#typed-package" id="id2"><span>[typed_package]</span></a>, as well as a <a class="reference internal" href="#stub-package" id="id3"><span>[stub_package]</span></a>. A sample package checker <a class="reference internal" href="#pkg-checker" id="id4"><span>[pkg_checker]</span></a> which reads the metadata of installed packages and reports on their status as either not typed, inline typed, or a stub package.</p> <p>The mypy type checker has an implementation of <a class="pep reference internal" href="../pep-0561/" title="PEP 561 – Distributing and Packaging Type Information">PEP 561</a> searching which can be read about in the mypy docs <a class="footnote-reference brackets" href="#id8" id="id5">[4]</a>.</p> <p><a class="reference internal" href="#numpy-stubs" id="id6"><span>[numpy-stubs]</span></a> is an example of a real stub-only package for the numpy distribution.</p> </section> <section id="acknowledgements"> <h2><a class="toc-backref" href="#acknowledgements" role="doc-backlink">Acknowledgements</a></h2> <p>This PEP would not have been possible without the ideas, feedback, and support of Ivan Levkivskyi, Jelle Zijlstra, Alyssa Coghlan, Daniel F Moisset, Andrey Vlasovskikh, Nathaniel Smith, and Guido van Rossum.</p> </section> <section id="version-history"> <h2><a class="toc-backref" href="#version-history" role="doc-backlink">Version History</a></h2> <ul> <li>2023-01-13<blockquote> <div><ul class="simple"> <li>Clarify that the 4th step of the <a class="reference internal" href="#mro"><span class="std std-ref">Module Resolution Order</span></a> applies to any package with a <code class="docutils literal notranslate"><span class="pre">py.typed</span></code> marker file (and not just inline packages).</li> </ul> </div></blockquote> </li> <li>2021-09-20<blockquote> <div><ul class="simple"> <li>Clarify expectations and typechecker behavior for stub-only namespace packages</li> <li>Clarify handling of single-file modules within namespace packages.</li> </ul> </div></blockquote> </li> <li>2018-07-09<blockquote> <div><ul class="simple"> <li>Add links to sample stub-only packages</li> </ul> </div></blockquote> </li> <li>2018-06-19<blockquote> <div><ul class="simple"> <li>Partial stub packages can look at typeshed as well as runtime packages</li> </ul> </div></blockquote> </li> <li>2018-05-15<blockquote> <div><ul class="simple"> <li>Add partial stub package spec.</li> </ul> </div></blockquote> </li> <li>2018-04-09<blockquote> <div><ul class="simple"> <li>Add reference to mypy implementation</li> <li>Clarify stub package priority.</li> </ul> </div></blockquote> </li> <li>2018-02-02<blockquote> <div><ul class="simple"> <li>Change stub-only package suffix to be -stubs not _stubs.</li> <li>Note that py.typed is not needed for stub-only packages.</li> <li>Add note about pip and upgrading stub packages.</li> </ul> </div></blockquote> </li> <li>2017-11-12<blockquote> <div><ul class="simple"> <li>Rewritten to use existing tooling only</li> <li>No need to indicate kind of type information in metadata</li> <li>Name of marker file changed from <code class="docutils literal notranslate"><span class="pre">.typeinfo</span></code> to <code class="docutils literal notranslate"><span class="pre">py.typed</span></code></li> </ul> </div></blockquote> </li> <li>2017-11-10<blockquote> <div><ul class="simple"> <li>Specification re-written to use package metadata instead of distribution metadata.</li> <li>Removed stub-only packages and merged into third party packages spec.</li> <li>Removed suggestion for typecheckers to consider checking runtime versions</li> <li>Implementations updated to reflect PEP changes.</li> </ul> </div></blockquote> </li> <li>2017-10-26<blockquote> <div><ul class="simple"> <li>Added implementation references.</li> <li>Added acknowledgements and version history.</li> </ul> </div></blockquote> </li> <li>2017-10-06<blockquote> <div><ul class="simple"> <li>Rewritten to use .distinfo/METADATA over a distutils specific command.</li> <li>Clarify versioning of third party stub packages.</li> </ul> </div></blockquote> </li> <li>2017-09-11<blockquote> <div><ul class="simple"> <li>Added information about current solutions and typeshed.</li> <li>Clarify rationale.</li> </ul> </div></blockquote> </li> </ul> </section> <section id="references"> <h2><a class="toc-backref" href="#references" role="doc-backlink">References</a></h2> <aside class="footnote-list brackets"> <aside class="footnote brackets" id="id7" role="doc-footnote"> <dt class="label" id="id7">[<a href="#id1">1</a>]</dt> <dd>Typeshed (<a class="reference external" href="https://github.com/python/typeshed">https://github.com/python/typeshed</a>)</aside> <aside class="footnote brackets" id="id8" role="doc-footnote"> <dt class="label" id="id8">[<a href="#id5">4</a>]</dt> <dd>Example implementation in a type checker (<a class="reference external" href="https://mypy.readthedocs.io/en/latest/installed_packages.html">https://mypy.readthedocs.io/en/latest/installed_packages.html</a>)</aside> </aside> <div role="list" class="citation-list"> <div class="citation" id="stub-package" role="doc-biblioentry"> <dt class="label" id="stub-package">[<a href="#id3">stub_package</a>]</dt> <dd>A stub-only package (<a class="reference external" href="https://github.com/emmatyping/stub-package">https://github.com/emmatyping/stub-package</a>)</div> <div class="citation" id="typed-package" role="doc-biblioentry"> <dt class="label" id="typed-package">[<a href="#id2">typed_package</a>]</dt> <dd>Sample typed package (<a class="reference external" href="https://github.com/emmatyping/pep-561">https://github.com/emmatyping/pep-561</a>)</div> <div class="citation" id="numpy-stubs" role="doc-biblioentry"> <dt class="label" id="numpy-stubs">[<a href="#id6">numpy-stubs</a>]</dt> <dd>Stubs for numpy (<a class="reference external" href="https://github.com/numpy/numpy-stubs">https://github.com/numpy/numpy-stubs</a>)</div> <div class="citation" id="pkg-checker" role="doc-biblioentry"> <dt class="label" id="pkg-checker">[<a href="#id4">pkg_checker</a>]</dt> <dd>Sample package checker (<a class="reference external" href="https://github.com/emmatyping/check_typedpkg">https://github.com/emmatyping/check_typedpkg</a>)</div> </div> </section> <section id="copyright"> <h2><a class="toc-backref" href="#copyright" role="doc-backlink">Copyright</a></h2> <p>This document has been placed in the public domain.</p> </section> </section> <hr class="docutils" /> <p>Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0561.rst">https://github.com/python/peps/blob/main/peps/pep-0561.rst</a></p> <p>Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0561.rst">2025-02-01 08:55:40 GMT</a></p> </article> <nav id="pep-sidebar"> <h2>Contents</h2> <ul> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#rationale">Rationale</a></li> <li><a class="reference internal" href="#definition-of-terms">Definition of Terms</a></li> <li><a class="reference internal" href="#specification">Specification</a><ul> <li><a class="reference internal" href="#packaging-type-information">Packaging Type Information</a><ul> <li><a class="reference internal" href="#stub-only-packages">Stub-only Packages</a></li> </ul> </li> <li><a class="reference internal" href="#type-checker-module-resolution-order">Type Checker Module Resolution Order</a></li> <li><a class="reference internal" href="#partial-stub-packages">Partial Stub Packages</a></li> </ul> </li> <li><a class="reference internal" href="#implementation">Implementation</a></li> <li><a class="reference internal" href="#acknowledgements">Acknowledgements</a></li> <li><a class="reference internal" href="#version-history">Version History</a></li> <li><a class="reference internal" href="#references">References</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> <br> <a id="source" href="https://github.com/python/peps/blob/main/peps/pep-0561.rst">Page Source (GitHub)</a> </nav> </section> <script src="../_static/colour_scheme.js"></script> <script src="../_static/wrap_tables.js"></script> <script src="../_static/sticky_banner.js"></script> </body> </html>