PEP561: Clarify stub-only namespace package behavior (#2083)

Co-authored-by: Ethan Smith <ethan@ethanhs.me>

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
@@ -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
 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
 ------------------------------------
@@ -180,6 +204,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.
@@ -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
 ``*.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
@@ -236,6 +272,11 @@ Vlasovskikh, Nathaniel Smith, and Guido van Rossum.
 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
 
     * Add links to sample stub-only packages