iSharkFly-Open
/
python-peps
mirror of https://github.com/python/peps.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Change to -stubs over _stubs (#568) 

Also note that a py.typed file is not needed for stub only packages.
This commit is contained in:
Ethan Smith 2018-02-05 15:30:57 -08:00 committed by Guido van Rossum
parent 8c4563933f
commit 69eb6508e1
1 changed files with 20 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
pep-0561.rst
View File

@ -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