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

Proposed small tweaks to the text of PEP 561 (#467)

This commit is contained in:
Guido van Rossum 2017-11-13 15:50:14 -08:00 committed by GitHub
parent 794178d6e0
commit 78dc4b19a3
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 18 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
pep-0561.rst
View File

@ -99,19 +99,21 @@ easy as possible, packaging and distribution is done through existing
frameworks.
Package maintainers who wish to support type checking of their code MUST add
a ``py.typed`` file to their package supporting typing. This marker is
recursive, if a top-level package includes it, all sub-packages MUST support
a marker file named ``py.typed`` to their package supporting typing. This marker applies
recursively: if a top-level package includes it, all its sub-packages MUST support
type checking as well. To have this file installed with the package,
maintainers can use existing packaging options such as ``package_data`` in
distutils, shown below.
Distutils option example::
...
package_data = {
'pkg': ['py.typed'],
},
...
setup(
...,
package_data = {
foopkg': ['py.typed'],
},
...,
)
For namespace packages, the ``py.typed`` file should be in the submodules of
the namespace, to avoid conflicts and for clarity.
@ -124,8 +126,8 @@ 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 ``pkg_stubs`` for type stubs for the package named
``pkg``. The normal resolution order of checking ``*.pyi`` before ``*.py``
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.
Third parties seeking to distribute stub files are encouraged to contact the
@ -133,18 +135,18 @@ maintainer of the package about distribution alongside the package. If the
maintainer does not wish to maintain or package stub files or type information
inline, then a third party stub only package can be created.
In addition, stub only distributions SHOULD indicate which version(s)
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, if there was a
stub package ``flyingcircus_stubs``, it can indicate the versions of the
runtime ``Flyingcircus`` distribution supported through ``install_requires``
in distutils based tools, or the equivalent in other packaging tools.
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.
Type Checker Module Resolution Order
------------------------------------
The following is the order that type checkers supporting this PEP SHOULD
The following is the order in which type checkers supporting this PEP SHOULD
resolve modules containing type information:
1. User code - the files the type checker is running on.
@ -154,7 +156,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 ``pkg_stubs`` for package ``pkg``.
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.