[Python-checkins] peps: Changes suggested by PJE.

[eric.smith]

http://hg.python.org/peps/rev/c417da431f8e
changeset:   4374:c417da431f8e
user:        Eric V. Smith <eric at trueblade.com>
date:        Mon May 14 10:45:28 2012 -0400
summary:
  Changes suggested by PJE.

files:
  pep-0420.txt |  54 +++++++++++++++++++++++++++++----------
  1 files changed, 40 insertions(+), 14 deletions(-)


diff --git a/pep-0420.txt b/pep-0420.txt
--- a/pep-0420.txt
+++ b/pep-0420.txt
@@ -76,6 +76,10 @@
 ``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 @@
 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 @@
 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 @@
 ``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 @@
 ==========
 
 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 @@
 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 @@
   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 @@
 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 @@
 
 .. [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

-- 
Repository URL: http://hg.python.org/peps