Changes suggested by PJE.

pep-0420.txt

@@ -76,6 +76,10 @@ setuptools allows declaring namespace packages in a distribution's
 ``setup.py``, so that distribution developers don't need to put the
 magic ``__path__`` modification into ``__init__.py`` themselves.
 
+See PEP 402's "The Problem" section [2]_ for more details on the
+motivation for namespace packages. Note that PEP 402 has been
+rejected, but the motivating use cases are still valid.
+
 Rationale
 =========
 
@@ -135,8 +139,8 @@ If the scan completes without returning a module or package, and at
 least one directory was recorded, then a namespace package is created.
 The new namespace package:
 
- * Has a ``__path__`` attribute set to the list of directories that
-   were found and recorded during the scan.
+ * Has a ``__path__`` attribute set to an iterable of the path strings
+   that were found and recorded during the scan.
 
  * Does not have a ``__file__`` attribute.
 
@@ -148,10 +152,7 @@ deferred until a sub-level import occurs.
 A namespace package is not fundamentally different from a regular
 package.  It is just a different way of creating packages.  Once a
 namespace package is created, there is no functional difference
-between it and a regular package.  The only observable difference is
-that the namespace package's ``__file__`` attribute will end with a
-path separator (typically a slash or backslash, depending on the
-platform).
+between it and a regular package.
 
 Dynamic path computation
 ------------------------
@@ -198,6 +199,28 @@ 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.
 
+Differences between namespace packages and regular packages
+-----------------------------------------------------------
+
+Namespace packages and regular packages are very similar. The
+differences are:
+
+ * Portions of namespace packages need not all come from the same
+   directory structure, or even from the same loader. Regular packages
+   are self-contained: all parts live in the same directory hierarchy.
+
+ * Namespace packages have no ``__file__`` attribute.
+
+ * Namespace packages' ``__path__`` attribute is a read-only iterable
+   of strings, which is automatically updated when the parent path is
+   modified.
+
+ * Namespace packages have no ``__init__.py`` module.
+
+ * Namespace packages have a different type of object for their
+   ``__loader__`` attribute.
+
+
 Packaging Implications
 ======================
 
@@ -232,7 +255,7 @@ Discussion
 ==========
 
 At PyCon 2012, we had a discussion about namespace packages at which
-PEP 382 and PEP 402 were rejected, to be replaced by this PEP [2]_.
+PEP 382 and PEP 402 were rejected, to be replaced by this PEP [3]_.
 
 There is no intention to remove support of regular packages.  If a
 developer knows that her package will never be a portion of a
@@ -247,7 +270,7 @@ lacking an ``__init__.py`` file.  Such a directory will now be
 imported as a namespace package, whereas in prior Python versions an
 ImportWarning would be raised.
 
-Nick Coghlan presented a list of his objections to this proposal [3]_.
+Nick Coghlan presented a list of his objections to this proposal [4]_.
 They are:
 
   1. Implicit package directories go against the Zen of Python.
@@ -261,7 +284,7 @@ They are:
   4. Implicit package directories will permanently entrench current
      newbie-hostile behaviour in ``__main__``.
 
-Nick gave a detailed response [4]_, which is summarized here:
+Nick gave a detailed response [5]_, which is summarized here:
 
   1. The practicality of this PEP wins over other proposals and the
      status quo.
@@ -290,7 +313,7 @@ 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 [5]_.
+is given in [6]_.
 
 
 Module reprs
@@ -338,16 +361,19 @@ References
 
 .. [1] PEP 420 branch (http://hg.python.org/features/pep-420)
 
-.. [2] PyCon 2012 Namespace Package discussion outcome
+.. [2] PEP 402's description of use cases for namespace packages
+       (http://www.python.org/dev/peps/pep-0402/#the-problem)
+
+.. [3] PyCon 2012 Namespace Package discussion outcome
        (http://mail.python.org/pipermail/import-sig/2012-March/000421.html)
 
-.. [3] Nick Coghlan's objection to the lack of marker files or directories
+.. [4] Nick Coghlan's objection to the lack of marker files or directories
        (http://mail.python.org/pipermail/import-sig/2012-March/000423.html)
 
-.. [4] Nick Coghlan's response to his initial objections
+.. [5] Nick Coghlan's response to his initial objections
        (http://mail.python.org/pipermail/import-sig/2012-April/000464.html)
 
-.. [5] Use case for multiple portions per ``find_loader`` call
+.. [6] Use case for multiple portions per ``find_loader`` call
        (http://mail.python.org/pipermail/import-sig/2012-May/000585.html)
 
 Copyright