From 79f69c53a09b15af9c46c6870b582b515c718858 Mon Sep 17 00:00:00 2001 From: Nipunn Koorapati Date: Mon, 20 Sep 2021 12:56:45 -0700 Subject: [PATCH 1/5] Clarify stub-only namespace package behavior in PEP561 --- pep-0561.rst | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/pep-0561.rst b/pep-0561.rst index 454b258d8ed..82c97bbec29 100644 --- a/pep-0561.rst +++ b/pep-0561.rst @@ -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 +avoid conflicts and for clarity. + +For example, if the ``pentagon`` and ``hexagon`` are separate distributions +installing within the namespace package ``shapes.polygon`` +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 ------------------------------------ @@ -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. @@ -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 From 538d8eeee82dfe61311e3257cb4e69a99af6b2f1 Mon Sep 17 00:00:00 2001 From: Nipunn Koorapati Date: Mon, 20 Sep 2021 13:54:38 -0700 Subject: [PATCH 2/5] Clarify single file modules inside namespace packages --- pep-0561.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/pep-0561.rst b/pep-0561.rst index 82c97bbec29..592abb3ad5c 100644 --- a/pep-0561.rst +++ b/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. This PEP does not support distributing typing information as part of -module-only distributions. The code should be refactored into a package-based -distribution and indicate that the package supports typing as described +module-only distributions or single-file modules within namespace packages. + +The single-file module should be refactored into a package +and indicate that the package supports typing as described above. Stub-only Packages From 9267be7c02ee6529032a9015653ff8128c925f9b Mon Sep 17 00:00:00 2001 From: Nipunn Koorapati Date: Sun, 26 Sep 2021 11:27:02 -0400 Subject: [PATCH 3/5] Apply suggestions from code review Co-authored-by: Ethan Smith --- pep-0561.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pep-0561.rst b/pep-0561.rst index 592abb3ad5c..82caaeca520 100644 --- a/pep-0561.rst +++ b/pep-0561.rst @@ -162,11 +162,11 @@ 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 +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.polygon`` +installing within the namespace package ``shapes.polygons`` The corresponding types-only distributions should produce packages laid out as follows:: From 7141d80db2335eee93b54d26aaf112d2de22c1c5 Mon Sep 17 00:00:00 2001 From: Nipunn Koorapati Date: Sun, 26 Sep 2021 11:43:21 -0400 Subject: [PATCH 4/5] Add note to changelog about handling of single file modules --- pep-0561.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/pep-0561.rst b/pep-0561.rst index 82caaeca520..b0db4171fed 100644 --- a/pep-0561.rst +++ b/pep-0561.rst @@ -268,6 +268,7 @@ 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 From b3accc1e84733d570a15fd01510078301bce4449 Mon Sep 17 00:00:00 2001 From: Nipunn Koorapati Date: Fri, 1 Oct 2021 23:03:34 -0700 Subject: [PATCH 5/5] Clarify partial packages for namespace packages --- pep-0561.rst | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/pep-0561.rst b/pep-0561.rst index b0db4171fed..31aaae236a5 100644 --- a/pep-0561.rst +++ b/pep-0561.rst @@ -233,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 ``*.py`` files. -If a stub package is partial it MUST include ``partial\n`` in a top level -``py.typed`` file. +If a stub package distribution is partial it MUST include ``partial\n`` in a +``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