PEP561: Clarify stub-only namespace package behavior (#2083)
Co-authored-by: Ethan Smith <ethan@ethanhs.me>
This commit is contained in:
parent
22bf5e5bed
commit
389e8219cb
49
pep-0561.rst
49
pep-0561.rst
|
@ -123,8 +123,10 @@ For namespace packages (see PEP 420), the ``py.typed`` file should be in the
|
||||||
submodules of the namespace, to avoid conflicts and for clarity.
|
submodules of the namespace, to avoid conflicts and for clarity.
|
||||||
|
|
||||||
This PEP does not support distributing typing information as part of
|
This PEP does not support distributing typing information as part of
|
||||||
module-only distributions. The code should be refactored into a package-based
|
module-only distributions or single-file modules within namespace packages.
|
||||||
distribution and indicate that the package supports typing as described
|
|
||||||
|
The single-file module should be refactored into a package
|
||||||
|
and indicate that the package supports typing as described
|
||||||
above.
|
above.
|
||||||
|
|
||||||
Stub-only Packages
|
Stub-only Packages
|
||||||
|
@ -156,6 +158,28 @@ in pip 9.0, if you update ``flyingcircus-stubs``, it will update
|
||||||
``--upgrade-strategy=only-if-needed`` flag. In pip 10.0 this is the default
|
``--upgrade-strategy=only-if-needed`` flag. In pip 10.0 this is the default
|
||||||
behavior.
|
behavior.
|
||||||
|
|
||||||
|
For namespace packages (see PEP 420), stub-only packages should
|
||||||
|
use the ``-stubs`` suffix on only the root namespace package.
|
||||||
|
All stub-only namespace packages should omit ``__init__.pyi`` files. ``py.typed``
|
||||||
|
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.
|
||||||
|
|
||||||
|
For example, if the ``pentagon`` and ``hexagon`` are separate distributions
|
||||||
|
installing within the namespace package ``shapes.polygons``
|
||||||
|
The corresponding types-only distributions should produce packages
|
||||||
|
laid out as follows::
|
||||||
|
|
||||||
|
shapes-stubs
|
||||||
|
└── polygons
|
||||||
|
└── pentagon
|
||||||
|
└── __init__.pyi
|
||||||
|
|
||||||
|
shapes-stubs
|
||||||
|
└── polygons
|
||||||
|
└── hexagon
|
||||||
|
└── __init__.pyi
|
||||||
|
|
||||||
|
|
||||||
Type Checker Module Resolution Order
|
Type Checker Module Resolution Order
|
||||||
------------------------------------
|
------------------------------------
|
||||||
|
@ -180,6 +204,11 @@ resolve modules containing type information:
|
||||||
5. Typeshed (if used) - Provides the stdlib types and several third party
|
5. Typeshed (if used) - Provides the stdlib types and several third party
|
||||||
libraries.
|
libraries.
|
||||||
|
|
||||||
|
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 ``__init__.pyi``. This allows different subpackages to
|
||||||
|
independently opt for inline vs stub-only.
|
||||||
|
|
||||||
Type checkers that check a different Python version than the version they run
|
Type checkers that check a different Python version than the version they run
|
||||||
on MUST find the type information in the ``site-packages``/``dist-packages``
|
on MUST find the type information in the ``site-packages``/``dist-packages``
|
||||||
of that Python version. This can be queried e.g.
|
of that Python version. This can be queried e.g.
|
||||||
|
@ -204,8 +233,15 @@ typeshed folder and type checking the combined directory structure. Thus type
|
||||||
checkers MUST maintain the normal resolution order of checking ``*.pyi`` before
|
checkers MUST maintain the normal resolution order of checking ``*.pyi`` before
|
||||||
``*.py`` files.
|
``*.py`` files.
|
||||||
|
|
||||||
If a stub package is partial it MUST include ``partial\n`` in a top level
|
If a stub package distribution is partial it MUST include ``partial\n`` in a
|
||||||
``py.typed`` file.
|
``py.typed`` file. For stub-packages distributing within a namespace
|
||||||
|
package (see PEP 420), the ``py.typed`` file should be in the
|
||||||
|
submodules of the namespace.
|
||||||
|
|
||||||
|
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 ``py.typed`` with ``partial\n`` is included.
|
||||||
|
|
||||||
|
|
||||||
Implementation
|
Implementation
|
||||||
|
@ -236,6 +272,11 @@ Vlasovskikh, Nathaniel Smith, and Guido van Rossum.
|
||||||
Version History
|
Version History
|
||||||
===============
|
===============
|
||||||
|
|
||||||
|
* 2021-09-20
|
||||||
|
|
||||||
|
* Clarify expectations and typechecker behavior for stub-only namespace packages
|
||||||
|
* Clarify handling of single-file modules within namespace packages.
|
||||||
|
|
||||||
* 2018-07-09
|
* 2018-07-09
|
||||||
|
|
||||||
* Add links to sample stub-only packages
|
* Add links to sample stub-only packages
|
||||||
|
|
Loading…
Reference in New Issue