Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

PEP561: Clarify stub-only namespace package behavior #2083

Merged
merged 5 commits into from
Oct 6, 2021
Merged

PEP561: Clarify stub-only namespace package behavior #2083

Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
79f69c5
Clarify stub-only namespace package behavior in PEP561
nipunn1313 Sep 20, 2021
538d8ee
Clarify single file modules inside namespace packages
nipunn1313 Sep 20, 2021
9267be7
Apply suggestions from code review
nipunn1313 Sep 26, 2021
7141d80
Add note to changelog about handling of single file modules
nipunn1313 Sep 26, 2021
b3accc1
Clarify partial packages for namespace packages
nipunn1313 Oct 2, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 31 additions & 0 deletions pep-0561.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -156,6 +156,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
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 inline packages, if used, they should be in submodules of the namespace to
nipunn1313 marked this conversation as resolved.
Show resolved Hide resolved
avoid conflicts and for clarity.

For example, if the ``pentagon`` and ``hexagon`` are separate distributions
installing within the namespace package ``shapes.polygon``
nipunn1313 marked this conversation as resolved.
Show resolved Hide resolved
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
------------------------------------
Expand All @@ -180,6 +202,11 @@ resolve modules containing type information:
5. Typeshed (if used) - Provides the stdlib types and several third party
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
on MUST find the type information in the ``site-packages``/``dist-packages``
of that Python version. This can be queried e.g.
Expand Down Expand Up @@ -236,6 +263,10 @@ Vlasovskikh, Nathaniel Smith, and Guido van Rossum.
Version History
===============

* 2021-09-20

* Clarify expectations and typechecker behavior for stub-only namespace packages

* 2018-07-09

* Add links to sample stub-only packages
Expand Down