mirror of https://github.com/python/peps
500 lines
32 KiB
HTML
500 lines
32 KiB
HTML
|
||
<!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: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="Python Enhancement Proposals (PEPs)">
|
||
<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">Ethan Smith <ethan at ethanhs.me></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>
|
||
<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/ethanhs/stub-package">https://github.com/ethanhs/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/ethanhs/sample-typed-package">https://github.com/ethanhs/sample-typed-package</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/ethanhs/check_typedpkg">https://github.com/ethanhs/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">2023-10-11 12:05:51 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> |