Update PEP 366 to reflect proposed implementation (and point to it on the tracker)

pep-0366.txt

@@ -8,7 +8,7 @@ Type: Standards Track
 Content-Type: text/x-rst
 Created: 1-May-2007
 Python-Version: 2.6, 3.0
-Post-History: 1-May-2007, 4-Jul-2007, 7-Jul-2007
+Post-History: 1-May-2007, 4-Jul-2007, 7-Jul-2007, 23-Nov-2007
 
 
 Abstract
@@ -36,22 +36,29 @@ attribute.
 As with the current ``__name__`` attribute, setting ``__package__`` will
 be the responsibility of the PEP 302 loader used to import a module.
 Loaders which use ``imp.new_module()`` to create the module object will
-have the new attribute set automatically to
-``__name__.rpartition('.')[0]``.
+have the new attribute set automatically to ``None``. When the import
+system encounters an explicit relative import in a module without
+``__package__`` set (or with it set to ``None``), it will calculate and
+store the correct value (``__name__.rpartition('.')[0]`` for normal
+modules and ``__name__`` for package initialisation modules). If
+``__package__`` has already been set then the import system will use
+it in preference to recalculating the package name from the
+``__name__`` and ``__path__`` attributes.
 
-``runpy.run_module`` will also set the new attribute, basing it off the
-``mod_name`` argument, rather than the ``run_name`` argument. This will
-allow relative imports to work correctly from main modules executed with
-the ``-m`` switch.
+The ``runpy`` module will explicitly set the new attribute, basing it off
+the name used to locate the module to be executed rather than the name
+used to set the module's ``__name__`` attribute. This will allow relative
+imports to work correctly from main modules executed with the ``-m``
+switch.
 
 When the main module is specified by its filename, then the
-``__package__`` attribute will be set to the empty string. To allow
+``__package__`` attribute will be set to ``None``. To allow
 relative imports when the module is executed directly, boilerplate
 similar to the following would be needed before the first relative
 import statement::
 
-  if __name__ == "__main__" and not __package_name__:
-      __package_name__ = "<expected_pacakage_name>"
+  if __name__ == "__main__" and __package__ is None:
+      __package__ = "expected.package.name"
 
 Note that this boilerplate is sufficient only if the top level package
 is already accessible via ``sys.path``. Additional code that manipulates
@@ -61,7 +68,8 @@ without the top level package already being importable.
 This approach also has the same disadvantage as the use of absolute
 imports of sibling modules - if the script is moved to a different
 package or subpackage, the boilerplate will need to be updated
-manually.
+manually. It has the advantage that this change need only be made
+once per file, regardless of the number of relative imports.
 
 
 Rationale for Change
@@ -88,9 +96,7 @@ which stored the main module's real module name in the
 ``__module_name__`` attribute. It was reverted due to the fact
 that 2.5 was already in beta by that time.
 
-A new patch will be developed for 2.6, and forward ported to
-Py3k via svnmerge.
-
+Patch 1487 [4] is the proposed implementation for this PEP.
 
 Alternative Proposals
 =====================
@@ -103,7 +109,7 @@ scheme of things, and the PEP was rejected [3]_.
 The advantage of the proposal in this PEP is that its only impact on
 normal code is the small amount of time needed to set the extra
 attribute when importing a module. Relative imports themselves should
-be sped up fractionally, as the package name is stored in the module
+be sped up fractionally, as the package name is cached in the module
 globals, rather than having to be worked out again for each relative
 import.
 
@@ -120,6 +126,8 @@ References
 .. [3] Guido's rejection of PEP 3122
    (http://mail.python.org/pipermail/python-3000/2007-April/006793.html)
 
+.. [4] PEP 366 implementation patch
+   (http://bugs.python.org/issue1487)
 
 Copyright
 =========