Skip to content

Commit

Permalink
Tweak the typing spec's module resolution to more closely emulate Pyt…
Browse files Browse the repository at this point in the history
…hon's runtime semantics (#1772)
  • Loading branch information
AlexWaygood authored Jun 18, 2024
1 parent 21d67ca commit 9642a5a
Showing 1 changed file with 15 additions and 6 deletions.
21 changes: 15 additions & 6 deletions docs/spec/distributing.rst
Original file line number Diff line number Diff line change
Expand Up @@ -199,8 +199,9 @@ Partial Stub Packages
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 part four of the module resolution
order below, namely :term:`inline` packages.
package SHOULD be searched for in parts five and six of the module resolution
order below, namely :term:`inline` packages and any third-party stubs the type
checker chooses to vendor.

Type checkers should merge the stub package and runtime package
directories. This can be thought of as the functional equivalent of copying the
Expand Down Expand Up @@ -235,19 +236,27 @@ resolve modules containing type information:

2. User code - the files the type checker is running on.

3. :term:`Stub <stub>` packages - these packages SHOULD supersede any installed inline
3. Typeshed stubs for the standard library. These will usually be vendored by
type checkers, but type checkers SHOULD provide an option for users to
provide a path to a directory containing a custom or modified version of
typeshed; if this option is provided, type checkers SHOULD use this as the
canonical source for standard-library types in this step.

4. :term:`Stub <stub>` packages - these packages SHOULD supersede any installed inline
package. They can be found in directories named ``foopkg-stubs`` for
package ``foopkg``.

4. Packages with a ``py.typed`` marker file - if there is nothing overriding
5. Packages with a ``py.typed`` marker file - if there is nothing overriding
the installed package, *and* it opts into type checking, the types
bundled with the package SHOULD be used (be they in ``.pyi`` type
stub files or inline in ``.py`` files).

5. Typeshed - only for modules in the standard library.
6. If the type checker chooses to additionally vendor any third-party stubs
(from typeshed or elsewhere), these SHOULD come last in the module
resolution order.

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
in step 4, they should continue to step 5/6. Typecheckers should identify namespace packages
by the absence of ``__init__.pyi``. This allows different subpackages to
independently opt for inline vs stub-only.

Expand Down

0 comments on commit 9642a5a

Please sign in to comment.