Updated to discuss find_loader method on finders.

pep-0420.txt

@@ -163,21 +163,39 @@ Impact on Import Finders and Loaders
 ------------------------------------
 
 PEP 302 defines "finders" that are called to search path elements.
-These finders' ``find_module`` methods currently return either a
-"loader" object or None.  For a finder to contribute to namespace
-packages, ``find_module`` will return a third type: a string.  This is
-the string that will be recorded and later used as a component of the
-namespace module's ``__path__``, as described above. This string must
-not contain a trailing path separator.
+These finders' ``find_module`` methods return either a "loader" object
+or None.
+
+For a finder to contribute to namespace packages, it must implement a
+new ``find_loader(fullname)`` method.  ``fullname`` has the same
+meaning as for ``find_module``.  ``find_loader`` has 3 possible return
+values, depending on whether it found a normal package, a namespace
+package portion, or neither.  In all cases the return value is a
+2-tuple.
+
+===== =======================  ============
+Case  Meaning                  Return value
+----- -----------------------  ------------
+1     normal package found     ``(loader, None)``
+2     portion(s) found         ``(None, <sequence of strings>)``
+3     neither found            ``(None, None)``
+===== =======================  ============
+
+Note that in case 2 a sequence of strings is returned.  This is to
+support the case where a finder discovers multiple namespace portions
+for a given ``fullname``.  Many finders will support only a single
+namespace package portion per ``find_loader`` call, in which case this
+will normally be a list containing only a single string.
+
+Legacy finders which implement ``find_module`` but not ``find_loader``
+will be unable to contribute portions to a namespace package.  The
+import machinery will call ``find_loader`` if it exists, else fall
+back to ``find_module``.
 
 The specification expands PEP 302 loaders to include an optional method called
 ``module_repr()`` which if present, is used to generate module object reprs.
 See the section below for further details.
 
-If an existing finder is not updated to support returning a string
-from ``find_module``, the only impact is that such a finder will be
-unable to provide portions of a namespace package.
-
 Packaging Implications
 ======================
 
@@ -259,6 +277,26 @@ simplest possible solution working.  It will be possible at a later
 date to add such features.  Several possible ways to do so were
 discussed in the referenced email thread.
 
+``find_module`` versus ``find_loader``
+--------------------------------------
+
+An early draft of this PEP specified a change to the ``find_module``
+method in order to support namespace packages.  It would be modified
+to return a string in the case where a namespace package portion was
+discovered.
+
+However, this caused a problem with existing code outside of the
+standard library which calls ``find_module``.  Because this code would
+not be upgraded in concert with changes required by this PEP, it would
+fail when it would receive unexpected return values from
+``find_module``.  Because of this incompatibility, this PEP now
+specifies that finders that want to provide namespace portions must
+implement the ``find_loader`` method, described above.
+
+The use case for supporting multiple portions per ``find_loader`` call
+is given in [6]_.
+
+
 Module reprs
 ============
 
@@ -316,6 +354,9 @@ References
 .. [5] Phillip Eby's question about auto-updating __path__
        (http://mail.python.org/pipermail/import-sig/2012-April/000468.html)
 
+.. [6] Use case for multiple portions per ``find_loader`` call
+       (http://mail.python.org/pipermail/import-sig/2012-May/000585.html)
+
 Copyright
 =========