update from Aahz

pep-0328.txt

@@ -5,7 +5,7 @@ Last-Modified: $Date$
 Author: Aahz <aahz@pythoncraft.com>
 Status: Accepted
 Type: Standards Track
-Python-Version: 2.4
+Python-Version: 2.4, 2,5, 2.6
 Content-Type: text/x-rst
 Created: 21-Dec-2003
 Post-History: 8-Mar-2004
@@ -21,14 +21,30 @@ The ``import`` statement has two problems:
 
 * Imports can be ambiguous in the face of packages; within a package,
   it's not clear whether ``import foo`` refers to a module within the
-  package or some module outside the package.
+  package or some module outside the package.  (More precisely, a local
+  module or package can shadow another hanging directly off
+  ``sys.path``.)
 
 For the first problem, it is proposed that parentheses be permitted to
 enclose multiple names, thus allowing Python's standard mechanisms for
-multi-line values to apply.  For the second problem, it is proposed
+multi-line values to apply.  For the second problem, it is proposed that
-that all ``import`` statements be absolute by default (more precisely,
+all ``import`` statements be absolute by default (searching ``sys.path``
-relative to ``sys.path``) with special syntax for accessing
+only) with special syntax (leading dots) for accessing package-relative
-package-relative imports.
+imports.
+
+
+Timeline
+========
+
+In Python 2.4, you must enable the new absolute import behavior with ::
+
+    from __future__ import absolute_import
+
+You may use relative imports freely.  In Python 2.5, any ``import``
+statement that results in an intra-package import will generate a
+``PendingDeprecation`` warning (this also applies to ``from <> import``
+that fails to use the relative import syntax).  In Python 2.6, ``import``
+will always be an absolute import.
 
 
 Rationale for Parentheses
@@ -188,10 +204,39 @@ Here are the contenders:
 
 
 Guido's Decision
-================
+----------------
 
 Guido has Pronounced [1]_ that relative imports will use leading dots,
-one per level of parent.
+one per level of parent.  Further discussion led to the following
+clarification of the semantics.  Given a package layout::
+
+    package
+        subpackage1
+            moduleX
+            moduleY
+        subpackage2
+            moduleZ
+        moduleA
+
+Assuming that the current file is ``moduleX.py``, following are correct
+usages of the new syntax::
+
+    from .moduleY import spam
+    from .moduleY import spam as ham
+    from . import moduleY
+    from ..subpackage1 import moduleY
+    from ..subpackage2.moduleZ import eggs
+    from ..moduleA import foo
+    from ...package import bar
+    from ...sys import path
+
+Note that while that last case is legal, it is certainly discouraged
+("insane" was the word Guido used).
+
+Reminder: relative imports must always use ``from <> import``;
+``import <>`` is always absolute.  Of course, absolute imports can use
+``from <> import`` by omitting the leading dots.
+
 
 
 References