PEP 561: Add partial stub section (#653)

pep-0561.rst

@@ -6,7 +6,7 @@ Type: Standards Track
 Content-Type: text/x-rst
 Created: 09-Sep-2017
 Python-Version: 3.7
-Post-History: 10-Sep-2017, 12-Sep-2017, 06-Oct-2017, 26-Oct-2017
+Post-History: 10-Sep-2017, 12-Sep-2017, 06-Oct-2017, 26-Oct-2017, 12-Apr-2018
 
 
 Abstract
@@ -181,8 +181,23 @@ 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.
+
+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.
+
+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. 
+
+Stub packages can opt into declaring themselves as partial by including
+``partial\n`` in the package's ``py.typed`` file.
 
 
 Implementation
@@ -202,13 +217,16 @@ Acknowledgements
 ================
 
 This PEP would not have been possible without the ideas, feedback, and support
-of Ivan Levkivskyi, Jelle Zijlstra, Nick Coghlan, Daniel F Moisset, Nathaniel
-Smith, and Guido van Rossum.
+of Ivan Levkivskyi, Jelle Zijlstra, Nick Coghlan, Daniel F Moisset, Andrey
+Vlasovskikh, Nathaniel Smith, and Guido van Rossum.
 
 
 Version History
 ===============
 
+* 2018-05-15
+    * Add partial stub package spec.
+
 * 2018-04-09
 
     * Add reference to mypy implementation