From 69eb6508e1ff1527f0d295c6b4d7bcc3dada4ac1 Mon Sep 17 00:00:00 2001 From: Ethan Smith Date: Mon, 5 Feb 2018 15:30:57 -0800 Subject: [PATCH] Change to -stubs over _stubs (#568) Also note that a py.typed file is not needed for stub only packages. --- pep-0561.rst | 26 ++++++++++++++++++++------ 1 file changed, 20 insertions(+), 6 deletions(-) diff --git a/pep-0561.rst b/pep-0561.rst index 289d28bc4..53d05ef26 100644 --- a/pep-0561.rst +++ b/pep-0561.rst @@ -131,9 +131,10 @@ type information, it is preferred that the ``*.pyi`` stubs are alongside the corresponding ``*.py`` files. However, the stubs can also be put in a separate package and distributed separately. Third parties can also find this method useful if they wish to distribute stub files. The name of the stub package -MUST follow the scheme ``foopkg_stubs`` for type stubs for the package named -``foopkg``. The normal resolution order of checking ``*.pyi`` before ``*.py`` -will be maintained. +MUST follow the scheme ``foopkg-stubs`` for type stubs for the package named +``foopkg``. Note that for stub only packages adding a py.typed marker is not +needed since the name ``*-stubs`` is enough to indicate it is a source of typing +information. Third parties seeking to distribute stub files are encouraged to contact the maintainer of the package about distribution alongside the package. If the @@ -143,9 +144,13 @@ inline, then a third party stub only package can be created. In addition, stub-only distributions SHOULD indicate which version(s) of the runtime package are supported by indicating the runtime distribution's version(s) through normal dependency data. For example, the -stub package ``flyingcircus_stubs`` can indicate the versions of the +stub package ``flyingcircus-stubs`` can indicate the versions of the runtime ``flyingcircus`` distribution it supports through ``install_requires`` -in distutils-based tools, or the equivalent in other packaging tools. +in distutils-based tools, or the equivalent in other packaging tools. Note that +in pip 9.0, if you update ``flyingcircus-stubs``, it will update +``flyingcircus``. In pip 9.0, you can use the +``--upgrade-strategy=only-if-needed`` flag. In pip 10.0 this is the default +behavior. Type Checker Module Resolution Order @@ -161,7 +166,7 @@ resolve modules containing type information: stubs to use, and patch broken stubs/inline types from packages. 3. Stub packages - these packages can supersede the installed packages. - They can be found at ``foopkg_stubs`` for package ``foopkg``. + They can be found at ``foopkg-stubs`` for package ``foopkg``. 4. Inline packages - if there is nothing overriding the installed package, and it opts into type checking, inline types SHOULD be used. @@ -176,6 +181,9 @@ of that Python version. This can be queried e.g. that the type checker allow for the user to point to a particular Python binary, in case it is not in the path. +The normal resolution order of checking ``*.pyi`` before ``*.py`` +will be maintained. + Implementation ============== @@ -198,6 +206,12 @@ Smith, and Guido van Rossum. Version History =============== +* 2018-02-02 + + * Change stub only package suffix to be -stubs not _stubs. + * Note that py.typed is not needed for stub only packages. + * Add note about pip and upgrading stub packages. + * 2017-11-12 * Rewritten to use existing tooling only