From a18a37ef19273299224a61e3f3df14532c17bc3d Mon Sep 17 00:00:00 2001 From: Sebastian Rittau Date: Wed, 10 Jan 2024 17:00:35 +0100 Subject: [PATCH] [spec] Update typeshed language to conform to reality * Describe typeshed as a "project", not a "repository". * While typeshed still contains third-party stubs, those are usually not distributed with type checkers, but available from PyPI. Update the language accordingly. * This also means that step 5 of the import resolution ordering should reference the stdlib only. * Fix the reference to another section. * Fix typo in section name. --- docs/spec/distributing.rst | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/spec/distributing.rst b/docs/spec/distributing.rst index d6f602065..5d9d5ba7d 100644 --- a/docs/spec/distributing.rst +++ b/docs/spec/distributing.rst @@ -73,13 +73,14 @@ Additional notes on stub files: Any identifier not defined in the stub is therefore assumed to be of type ``Any``. -The Typeshed Repo -^^^^^^^^^^^^^^^^^ - -There is a `shared repository `_ where useful stubs are being -collected. Policies regarding the stubs collected here are -decided separately and reported in the repo's documentation. +The Typeshed Project +^^^^^^^^^^^^^^^^^^^^ +The `typeshed project `_ contains type +annotations for the standard library and a selection of third-party libraries +that don't ship their own type annotations or stubs. Policies regarding the +stubs collected there are decided separately and reported in the project's +documentation. Type information in libraries ----------------------------- @@ -194,13 +195,13 @@ 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 parts four and five of the module resolution -order above, namely inline packages and typeshed. +package SHOULD be searched for in part four of the module resolution +order below, namely inline packages. -Type checkers should merge the stub package and runtime package or typeshed +Type checkers should merge the stub package and runtime package directories. This can be thought of as the functional equivalent of copying the -stub package into the same directory as the corresponding runtime package or -typeshed folder and type checking the combined directory structure. Thus type +stub package into the same directory as the corresponding runtime package +and type checking the combined directory structure. Thus type checkers MUST maintain the normal resolution order of checking ``*.pyi`` before ``*.py`` files. @@ -216,8 +217,8 @@ are considered complete unless a ``py.typed`` with ``partial\n`` is included. .. _mro: -Import resolutiong ordering -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Import resolution ordering +^^^^^^^^^^^^^^^^^^^^^^^^^^ The following is the order in which type checkers supporting this specification SHOULD resolve modules containing type information: @@ -238,8 +239,7 @@ resolve modules containing type information: bundled with the package SHOULD be used (be they in ``.pyi`` type stub files or inline in ``.py`` files). -5. Typeshed (if used) - Provides the stdlib types and several third party - libraries. +5. Typeshed (if used) - Provides the stdlib types. 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