Update PEP text

pep-0561.rst

@@ -1,7 +1,7 @@
 PEP: 561 
 Title: Distributing and Packaging Type Information
 Author: Ethan Smith <[email protected]>
-Status: Draft
+Status: Accepted
 Type: Standards Track
 Content-Type: text/x-rst
 Created: 09-Sep-2017
@@ -49,24 +49,28 @@ Definition of Terms
 The definition of "MAY", "MUST", and "SHOULD", and "SHOULD NOT" are
 to be interpreted as described in RFC 2119.
 
-"inline" - the types are part of the runtime code using PEP 526 and 3107 
-syntax.
+"inline" - the types are part of the runtime code using PEP 526 and
+PEP 3107 syntax (the filename ends in ``.py``).
 
-"stubs" - files containing only type information, empty of runtime code.
+"stubs" - files containing only type information, empty of runtime code
+(the filename ends in ``.pyi``).
 
 "Distributions" are the packaged files which are used to publish and distribute
 a release. [3]_
 
 "Module" a file containing Python runtime code or stubbed type information.
 
 "Package" a directory or directories that namespace Python modules.
+(Note the distinction between packages and distributions.  While most
+distributions are named after the one package they install, some
+distributions install multiple packages.)
 
 
 Specification
 =============
 
 There are several motivations and methods of supporting typing in a package.
-This PEP recognizes three (3) types of packages that users of typing wish to
+This PEP recognizes three types of packages that users of typing wish to
 create:
 
 1. The package maintainer would like to add type information inline.
@@ -77,7 +81,7 @@ create:
    a package, but the maintainer does not want to include them in the source
    of the package.
 
-This PEP aims to support these scenarios and make them simple to add to
+This PEP aims to support all three scenarios and make them simple to add to
 packaging and deployment.
 
 The two major parts of this specification are the packaging specifications
@@ -115,15 +119,15 @@ Distutils option example::
         ...,
         )
 
-For namespace packages, the ``py.typed`` file should be in the submodules of
-the namespace, to avoid conflicts and for clarity.
+For namespace packages (see PEP 420), the ``py.typed`` file should be in the
+submodules of the namespace, to avoid conflicts and for clarity.
 
 This PEP does not support distributing typing information as part of
 module-only distributions. The code should be refactored into a package-based
 distribution and indicate that the package supports typing as described
 above.
 
-Stub Only Packages
+Stub-only Packages
 ''''''''''''''''''
 
 For package maintainers wishing to ship stub files containing all of their
@@ -132,14 +136,14 @@ 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``. Note that for stub only packages adding a py.typed marker is not
+``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
 maintainer does not wish to maintain or package stub files or type information
-inline, then a third party stub only package can be created.
+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
@@ -159,17 +163,19 @@ Type Checker Module Resolution Order
 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.
 
-2. Stubs or Python source manually put in the beginning of the path. Type
+1. Stubs or Python source manually put in the beginning of the path. Type
    checkers SHOULD provide this to allow the user complete control of which
-   stubs to use, and patch broken stubs/inline types from packages.
+   stubs to use, and to patch broken stubs/inline types from packages.
+   In mypy the ``$MYPYPATH`` environment variable can be used for this.
+
+2. User code - the files the type checker is running on.
 
 3. Stub packages - these packages SHOULD supersede any installed inline
    package. 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.
+   package, *and* it opts into type checking, inline types SHOULD be used.
 
 5. Typeshed (if used) - Provides the stdlib types and several third party
    libraries.
@@ -188,30 +194,36 @@ 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 the corresponding runtime package.
+package SHOULD be searched for in parts four and five of the module resolution
+order above, namely inline packages and 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 and type checking
-the combined directory structure. Thus type checkers MUST maintain the normal
-resolution order of checking ``*.pyi`` before ``*.py`` files. 
+Type checkers should merge the stub package and runtime package or typeshed
+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
+checkers MUST maintain the normal resolution order of checking ``*.pyi`` before
+``*.py`` files.
 
-Stub packages can opt into declaring themselves as partial by including
-``partial\n`` in the package's ``py.typed`` file.
+If a stub package is partial it MUST include ``partial\n`` in a top level
+``py.typed`` file.
 
 
 Implementation
 ==============
 
 The proposed scheme of indicating support for typing is completely backwards
 compatible, and requires no modification to package tooling. A sample package
-with inline types is available [typed_pkg]_, as well as a sample package
-checker [pkg_checker]_ which reads the metadata of installed packages and
-reports on their status as either not typed, inline typed, or a stub package.
+with inline types is available [typed_package]_, as well as a [stub_package]_. A
+sample package checker [pkg_checker]_ which reads the metadata of installed
+packages and reports on their status as either not typed, inline typed, or a
+stub package.
 
 The mypy type checker has an implementation of PEP 561 searching which can be
 read about in the mypy docs [4]_.
 
+[numpy-stubs]_ is an example of a real stub-only package for the numpy
+distribution.
+
 
 Acknowledgements
 ================
@@ -224,7 +236,16 @@ Vlasovskikh, Nathaniel Smith, and Guido van Rossum.
 Version History
 ===============
 
+* 2018-07-09
+
+    * Add links to sample stub-only packages
+
+* 2018-06-19
+
+    * Partial stub packages can look at typeshed as well as runtime packages
+
 * 2018-05-15
+
     * Add partial stub package spec.
 
 * 2018-04-09
@@ -234,8 +255,8 @@ 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.
+    * 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
@@ -248,7 +269,7 @@ Version History
 
     * Specification re-written to use package metadata instead of distribution
       metadata.
-    * Removed stub only packages and merged into third party packages spec.
+    * Removed stub-only packages and merged into third party packages spec.
     * Removed suggestion for typecheckers to consider checking runtime versions
     * Implementations updated to reflect PEP changes.
 
@@ -281,9 +302,15 @@ References
 .. [4] Example implementation in a type checker
    (https://mypy.readthedocs.io/en/latest/installed_packages.html)
 
-.. [typed_pkg] Sample typed package
+.. [stub_package] A stub-only package
+   (https://github.com/ethanhs/stub-package)
+
+.. [typed_package] Sample typed package
    (https://github.com/ethanhs/sample-typed-package)
 
+.. [numpy-stubs] Stubs for numpy
+   (https://github.com/numpy/numpy-stubs)
+
 .. [pkg_checker] Sample package checker
    (https://github.com/ethanhs/check_typedpkg)