From 0f721576a735eabcec4e26cbee47b4a0be7218fb Mon Sep 17 00:00:00 2001 From: Ethan Smith Date: Mon, 5 Feb 2018 14:22:44 -0800 Subject: [PATCH 1/3] Change to -stubs over _stubs Also note that a py.typed file is not needed for stub only packages. --- pep-0561.rst | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/pep-0561.rst b/pep-0561.rst index 289d28bc488..7281fb39582 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,7 +144,7 @@ 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. @@ -161,7 +162,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 +177,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 ============== From b1c483d9a4e0597a6116845072f00bb430cd5ac0 Mon Sep 17 00:00:00 2001 From: Ethan Smith Date: Mon, 5 Feb 2018 14:36:40 -0800 Subject: [PATCH 2/3] PEP 561: Add changlog and note about pip updating --- pep-0561.rst | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/pep-0561.rst b/pep-0561.rst index 7281fb39582..de05f4d4f78 100644 --- a/pep-0561.rst +++ b/pep-0561.rst @@ -146,7 +146,11 @@ 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 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 @@ -202,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 From e7548e6abecf51adcab24061f0f52cfcd36f4a1d Mon Sep 17 00:00:00 2001 From: Ethan Smith Date: Mon, 5 Feb 2018 14:42:53 -0800 Subject: [PATCH 3/3] Fix rst errors --- pep-0561.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pep-0561.rst b/pep-0561.rst index de05f4d4f78..53d05ef26f8 100644 --- a/pep-0561.rst +++ b/pep-0561.rst @@ -133,7 +133,7 @@ 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``. 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 +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