diff --git a/pep-0420.txt b/pep-0420.txt index 75e02e641..37cc3e829 100644 --- a/pep-0420.txt +++ b/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, )`` +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 =========