[PEP 451] Clarify about namespace packages and about what ModuleSpec does during loading.

pep-0451.txt

@@ -443,32 +443,34 @@ factory functions nor any the instance methods.
 How Loading Will Work
 =====================
 
-This is an outline of what happens in ModuleSpec's loading
-functionality::
+Here is an outline of what ModuleSpec does during loading::
 
-   def load(spec):
-       if not hasattr(spec.loader, 'exec_module'):
-           module = spec.loader.load_module(spec.name)
-           spec.init_module_attrs(module)
-           return sys.modules[spec.name]
+   def load(self):
+       if not hasattr(self.loader, 'exec_module'):
+           module = self.loader.load_module(self.name)
+           self.init_module_attrs(module)
+           return sys.modules[self.name]
 
        module = None
-       if hasattr(spec.loader, 'create_module'):
-           module = spec.loader.create_module(spec)
+       if hasattr(self.loader, 'create_module'):
+           module = self.loader.create_module(self)
        if module is None:
-           module = ModuleType(spec.name)
-       spec.init_module_attrs(module)
+           module = ModuleType(self.name)
+       self.init_module_attrs(module)
 
-       sys.modues[spec.name] = module
+       sys.modules[self.name] = module
        try:
-           spec.loader.exec_module(module)
+           self.loader.exec_module(module)
        except BaseException:
            try:
-               del sys.modules[spec.name]
+               del sys.modules[self.name]
            except KeyError:
                pass
            raise
-       return sys.modules[spec.name]
+       return sys.modules[self.name]
+
+Note: no "load" method is actually implemented as part of the public
+ModuleSpec API.
 
 These steps are exactly what Loader.load_module() is already
 expected to do.  Loaders will thus be simplified since they will only
@@ -705,6 +707,16 @@ especially considering PathEntryFinder.find_loader() was just
 added in Python 3.3.  However, the extra complexity and a less-than-
 explicit method name aren't worth it.
 
+Namespace Packages
+------------------
+
+Currently a path entry finder may return (None, portions) from
+find_loader() to indicate it found part of a possible namespace
+package.  To achieve the same effect, find_spec() must return a spec
+with "loader" set to None (a.k.a. not set) and with
+submodule_search_locations set to the same portions as were provided by
+find_loader().  It's up to PathFinder how to handle such specs.
+
 Loaders
 -------