[Python-checkins] r72146 - peps/trunk/pep-0382.txt

[martin.v.loewis]

Author: martin.v.loewis
Date: Thu Apr 30 11:05:00 2009
New Revision: 72146

Log:
Rename proposed files from .pkg into .pth. Drop
claims that this extends the .pkg mechanism.


Modified:
   peps/trunk/pep-0382.txt

Modified: peps/trunk/pep-0382.txt
==============================================================================
--- peps/trunk/pep-0382.txt	(original)
+++ peps/trunk/pep-0382.txt	Thu Apr 30 11:05:00 2009
@@ -49,8 +49,8 @@
 first. As a consequence, the package's ``__init__.py`` cannot
 practically define any names as it depends on the order of the package
 fragments on sys.path which portion is imported first. As a special
-feature, extend_path reads files named ``*.pkg`` which allow to
-declare additional portions.
+feature, extend_path reads files named ``<packagename>.pkg`` which
+allow to declare additional portions.
 
 setuptools provides a similar function pkg_resources.declare_namespace
 that is used in the form::
@@ -91,29 +91,27 @@
 
 Rather than using an imperative mechanism for importing packages, a
 declarative approach is proposed here, as an extension to the existing
-``*.pkg`` mechanism.
+``*.pth`` mechanism available on the top-level python path.
 
-The import statement is extended so that it directly considers ``*.pkg``
-files during import; a directory is considered a package if it either
-contains a file named __init__.py, or a file whose name ends with
-".pkg".
+The import statement is extended so that it directly considers
+``*.pth`` files during import; a directory is considered a package if
+it either contains a file named __init__.py, or a file whose name ends
+with ".pth". Unlike .pth files on the top level, lines starting with
+"import" are not supported in per-package .pth files.
 
-In addition, the format of the ``*.pkg`` file is extended: a line with
+In addition, the format of the ``*.pth`` file is extended: a line with
 the single character ``*`` indicates that the entire sys.path will
 be searched for portions of the namespace package at the time the
 namespace packages is imported.
 
 Importing a package will immediately compute the package's __path__;
-the ``*.pkg`` files are not considered anymore after the initial import.
-If a ``*.pkg`` package contains an asterisk, this asterisk is prepended
-to the package's __path__ to indicate that the package is a namespace
-package (and that thus further extensions to sys.path might also
-want to extend __path__). At most one such asterisk gets prepended
-to the path. In addition, the (possibly dotted) names of all namespace
-packages are added to the set sys.namespace_packages.
-
-extend_path will be extended to recognize namespace packages according
-to this PEP, and avoid adding directories twice to __path__.
+the ``*.pth`` files are not considered anymore after the initial
+import.  If a ``*.pth`` package contains an asterisk, this asterisk is
+prepended to the package's __path__ to indicate that the package is a
+namespace package (and that thus further extensions to sys.path might
+also want to extend __path__). At most one such asterisk gets
+prepended to the path. In addition, the (possibly dotted) names of all
+namespace packages are added to the set sys.namespace_packages.
 
 No other change to the importing mechanism is made; searching modules
 (including __init__.py) will continue to stop at the first module
@@ -122,22 +120,22 @@
 
  1. sys.path is search for a directory foo, or a file foo.<ext>.
     If a file is found, it is treated as a module, and imported.
- 2. if it is a directory, it checks for \*.pkg files. If it finds
+ 2. if it is a directory, it checks for \*.pth files. If it finds
     any, a package is created, and its __path__ is extended.
  3. The __init__ module is imported; this import will search the
     __path__ that got computed already.
- 4. If neither a \*.pkg file nor an __init__.py was found, the
+ 4. If neither a \*.pth file nor an __init__.py was found, the
     directory is skipped, and search for the module/package
     continues.
 
 Discussion
 ==========
 
-With the addition of ``*.pkg`` files to the import mechanism, namespace
+With the addition of ``*.pth`` files to the import mechanism, namespace
 packages can stop filling out the namespace package's __init__.py.
 As a consequence, extend_path and declare_namespace become obsolete.
 
-It is recommended that distributions put a file <distribution>.pkg
+It is recommended that distributions put a file <distribution>.pth
 into their namespace packages, with a single asterisk. This allows
 vendor packages to install multiple portions of namespace package
 into a single directory, with no risk of overlapping files.
@@ -160,9 +158,6 @@
 users of this feature are encouraged to comment on this particular
 question.
 
-It also has been proposed to rename the extension from .pkg to
-something else.
-
 Copyright
 =========