[Python-checkins] peps: Introduce .pyp directories.

martin.v.loewis python-checkins at python.org
Wed Oct 19 20:27:54 CEST 2011 

http://hg.python.org/peps/rev/0a200e493d52
changeset:   3968:0a200e493d52
user:        Martin v. Loewis <martin at v.loewis.de>
date:        Wed Oct 19 20:27:52 2011 +0200
summary:
  Introduce .pyp directories.

files:
  pep-0382.txt |  121 +++++++++++++++++++-------------------
  1 files changed, 62 insertions(+), 59 deletions(-)


diff --git a/pep-0382.txt b/pep-0382.txt
--- a/pep-0382.txt
+++ b/pep-0382.txt
@@ -90,51 +90,31 @@
 =============
 
 Rather than using an imperative mechanism for importing packages, a
-declarative approach is proposed here, as an extension to the existing
-``*.pth`` mechanism available on the top-level python path.
+declarative approach is proposed here: A directory whose name ends 
+with ``.pyp`` (for Python package) contains a portion of a package.
 
-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 ``*.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. For a sub-package, the package's
-__path__ is searched (instead of sys.path).
-
-Importing a package will immediately compute the package's __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.
-
-If the first directory found on the path only contains an __init__.py
-and no \*.pth file, searching the path stops; IOW, namespace packages
-must include at least one .pth file. If both \*.pth files and an
-__init__.py had been found, search continues looking for further
-.pth files.
+The import statement is extended so that computes the package's
+``__path__`` attribute for a package named ``P`` as consisting of all
+directories named ``P.pyp``, plus optionally a single directory named
+``P`` containing a file ``__init__.py``. If either of these are
+found on the path of the parent package (or sys.path for a top-level
+package), search for additional portions of the package continues.
 
 No other change to the importing mechanism is made; searching modules
 (including __init__.py) will continue to stop at the first module
 encountered. In summary, the process import a package foo works like
 this:
 
- 1. sys.path is search for a directory foo, or a file foo.<ext>.
+ 1. sys.path is searched for directories foo or foo.pyp, or a file foo.<ext>.
     If a file is found and no directory, it is treated as a module, and imported.
- 2. if it is a directory, it checks for both \*.pth and an __init__ file. If it finds
-    only \*.pth files, a package is created, and its __path__ is extended.
- 3. If neither a \*.pth file nor an __init__.py was found, the
-    directory is skipped, and search for the module/package
-    continues. If an __init__.py was found, further search only looks
-    for \*.pth files.
+ 2. If a directory foo is found, a check is made whether it contains __init__.py.
+    If so, the location of the __init__.py is remembered. Otherwise, the directory
+    is skipped. Once an __init__.py is found, further directories called foo are
+    skipped.
+ 3. For both directories foo and foo.pyp, the directories are added to the package's
+    __path__.
  4. If an __init__ module was found, it is imported, with __path__
-    being initialized to the path computed from the \*.pth files.
+    being initialized to the path computed all ``.pyp`` directories.
 
 Impact on Import Hooks
 ----------------------
@@ -146,41 +126,63 @@
 AttributeError when the functions below get accessed.
 
 Finders need to support looking for \*.pth files in step 1 of above
-algorithm. To do so, a finder must support a method:
+algorithm. To do so, a finder used as a path hook must support a
+method:
 
-   finder.find_path(fullname, path=None)
+   finder.is_package_portion(fullname)
 
 This method will be called in the same manner as find_module, and it
-must return a list of strings, each representing the contents of one
-\*.pth file. If fullname is not found, is not a package, or does not
-have any \*.pth files, None must be returned.
+must return True if there is a package portion with that name; False
+if fullname indicates a subpackage/submodule that is not a package
+portion; otherwise, it shall raise an ImportError.
 
-If any \*.pth files are found, but no loader was returned from
+If any \*.pyp directories are found, but no loader was returned from
 find_module, a package is created and initialized with the path.
 
-If a loader was return, but no \*.pth files, load_module is called
-as defined in PEP 302.
+If a loader was return, but no \*.pyp directories, load_module is
+called as defined in PEP 302.
 
-If both \*.pth files where found, and a loader was returned, a new
-method is called on the loader:
+If both \*.pyp directories where found, and a loader was returned, a
+new method is called on the loader:
 
    loader.load_module_with_path(load_module, path)
 
-where the path parameter is the list of strings containing the
-contents of all \*.pth files.
+where the path parameter is the list that will become the __path__
+attribute of the new package.
 
 
 Discussion
 ==========
 
-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.
+Original versions of this specification proposed the addition of
+``*.pth`` files, similar to the way those files are used on sys.path.
+With a wildcard marker (``*``), a package could indicate that the
+entire path is derived by looking at the parent path, searching for
+properly-named subdirectories.
 
-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.
+People then observed that the support for the full .pth syntax is
+inappropriate, and the .pth files were changed to be mere marker
+files, indicating that a directories is a package. Peter Tröger
+suggested that .pth is an unsuitable file extension, as all file
+extensions related to Python should start with ``.py``. Therefore, the
+marker file was renamed to be ``.pyp``.
+
+Dinu Gherman then observed that using a marker file is not necessary,
+and that a directoy extension could well serve as a such as a
+marker. This is what this PEP currently proposes.
+
+Phillip Eby designed PEP 402 as an alternative approach to this PEP,
+after comparing Python's package syntax with that found in other
+languages. PEP 402 proposes not to use a marker file at all. At the
+discussion at PyCon DE 2011, people remarked that having an explicit
+declaration of a directory as contributing to a package is a desirable
+property, rather than an obstactle. In particular, Jython developers
+noticed that Jython could easily mistake a directory that is a Java
+package as being a Python package, if there is no need to declare
+Python packages.
+
+packages can stop filling out the namespace package's __init__.py.  As
+a consequence, extend_path and declare_namespace become obsolete.
 
 Namespace packages can start providing non-trivial __init__.py
 implementations; to do so, it is recommended that a single distribution
@@ -195,10 +197,11 @@
 
 It has been proposed to also add this feature to Python 2.7. Given
 that 2.x reaches its end-of-life, it is questionable whether the
-addition of the feature would really do more good than harm (in
-having users and tools starting to special-case 2.7). Prospective
-users of this feature are encouraged to comment on this particular
-question.
+addition of the feature would really do more good than harm (in having
+users and tools starting to special-case 2.7). Prospective users of
+this feature are encouraged to comment on this particular question. In
+addition, Python 2.7 is in bug-fix mode now, so adding new features to
+it would be a violation of the established policies.
 
 
 Copyright

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

More information about the Python-checkins mailing list