On Aug 02, 2012, at 03:04 PM, nick.coghlan wrote:

>http://hg.python.org/cpython/rev/1f8351cf00f3
>changeset:   78382:1f8351cf00f3
>user:        Nick Coghlan <ncogh...@gmail.com>
>date:        Thu Aug 02 23:03:58 2012 +1000
>summary:
>  Issue #15502: Bring the importlib.PathFinder docs and docstring more in line 
> with the new import system documentation, and fix various parts of the new 
> docs that weren't quite right given PEP 420 or were otherwise a bit 
> misleading. Also note the key terminology problem still being discussed in 
> the issue
>
>files:
>  Doc/library/importlib.rst   |    15 +-
>  Doc/reference/import.rst    |   221 +-
>  Lib/importlib/_bootstrap.py |     8 +-
>  Python/importlib.h          |  2583 +++++++++++-----------
>  4 files changed, 1449 insertions(+), 1378 deletions(-)
>
>
>diff --git a/Doc/reference/import.rst b/Doc/reference/import.rst
>--- a/Doc/reference/import.rst
>+++ b/Doc/reference/import.rst
>@@ -69,7 +75,7 @@
> 
> It's important to keep in mind that all packages are modules, but not all
> modules are packages.  Or put another way, packages are just a special kind of
>-module.  Specifically, any module that contains an ``__path__`` attribute is
>+module.  Specifically, any module that contains a ``__path__`` attribute is

I find this change hilarious!  Is it "an under-under path" or "a dunder path"?
Personally, I think word "dunder" should never be used unless it's followed by
the word "mifflin", but that might be a bit too regional.  Or maybe too old
skool (yeah, I know all the kids love the dunder).

I suppose I don't care that much, but it would be useful to have some
consistency, like whether we use American or British spellings.

>@@ -90,7 +96,7 @@
> packages are traditional packages as they existed in Python 3.2 and earlier.
> A regular package is typically implemented as a directory containing an
> ``__init__.py`` file.  When a regular package is imported, this
>-``__init__.py`` file is implicitly imported, and the objects it defines are
>+``__init__.py`` file is implicitly executed, and the objects it defines are

Perhaps "loaded" instead of either "imported" or "executed"?

>@@ -107,9 +113,9 @@
>         three/
>             __init__.py
> 
>-Importing ``parent.one`` will implicitly import ``parent/__init__.py`` and
>+Importing ``parent.one`` will implicitly execute ``parent/__init__.py`` and

Same.

> ``parent/one/__init__.py``.  Subsequent imports of ``parent.two`` or
>-``parent.three`` will import ``parent/two/__init__.py`` and
>+``parent.three`` will execute ``parent/two/__init__.py`` and

And here.

> ``parent/three/__init__.py`` respectively.
> 
> 
>@@ -128,6 +134,12 @@
> objects on the file system; they may be virtual modules that have no concrete
> representation.
> 
>+Namespace packages do not use an ordinary list for their ``__path__``
>+attribute. They instead use a custom iterable type which will automatically
>+perform a new search for package portions on the next import attempt within
>+that package if the path of their parent package (or :data:`sys.path` for a
>+top level package) changes.

Nice addition.  I can't help but suggest a slight rephrasing:

Namespace packages use a custom iterable type for their ``__path__``
attribute, so that changes in their parent package's path (or :data:`sys.path`
for a top level package) are handled automatically.

>@@ -172,14 +184,18 @@
> :exc:`ImportError` is raised.  If the module name is missing, Python will
> continue searching for the module.
> 
>-:data:`sys.modules` is writable.  Deleting a key will not destroy the
>-associated module, but it will invalidate the cache entry for the named
>-module, causing Python to search anew for the named module upon its next
>-import.  Beware though, because if you keep a reference to the module object,
>+:data:`sys.modules` is writable.  Deleting a key may not destroy the
>+associated module (as other modules may hold references to it),

s/as other modules may hold references to it/due to circular references/

>@@ -369,7 +404,7 @@
> 
> Here are the exact rules used:
> 
>- * If the module has an ``__loader__`` and that loader has a
>+ * If the module has a ``__loader__`` and that loader has a
>    :meth:`module_repr()` method, call it with a single argument, which is the
>    module object.  The value returned is used as the module's repr.
> 
>@@ -377,10 +412,10 @@
>    and discarded, and the calculation of the module's repr continues as if
>    :meth:`module_repr()` did not exist.
> 
>- * If the module has an ``__file__`` attribute, this is used as part of the
>+ * If the module has a ``__file__`` attribute, this is used as part of the
>    module's repr.
> 
>- * If the module has no ``__file__`` but does have an ``__loader__``, then the
>+ * If the module has no ``__file__`` but does have a ``__loader__``, then the
>    loader's repr is used as part of the module's repr.
> 
>  * Otherwise, just use the module's ``__name__`` in the repr.

C'mon Michael Scott, make it stop!  Do you remember the episode where Dwight
and Jim team up to...  Oh, I was in stitches!

>@@ -430,15 +467,20 @@
> path`, which contains a list of :term:`path entries <path entry>`.  Each path
> entry names a location to search for modules.
> 
>-Path entries may name file system locations, and by default the :term:`path
>-importer` knows how to provide traditional file system imports.  It implements
>-all the semantics for finding modules on the file system, handling special
>-file types such as Python source code (``.py`` files), Python byte code
>-(``.pyc`` and ``.pyo`` files) and shared libraries (e.g. ``.so`` files).
>+The path importer itself doesn't know how to import anything. Instead, it
>+traverses the individual path entries, associating each of them with a
>+path entry finder that knows how to handle that particular kind of path.
>+
>+The default set of path entry finders implement all the semantics for finding
>+modules on the file system, handling special file types such as Python source
>+code (``.py`` files), Python byte code (``.pyc`` and ``.pyo`` files) and
>+shared libraries (e.g. ``.so`` files). When supported by the :mod:`zipimport`
>+module in the standard library, the default path entry finders also handle
>+loading all of these file types (other than shared libraries) from zipfiles.

s/zipfiles/zip files/

> 
> Path entries need not be limited to file system locations.  They can refer to
>-the contents of zip files, URLs, database queries, or any other location that
>-can be specified as a string.
>+the URLs, database queries, or any other location that can be specified as a
>+string.

s/the URLs/URLs/

> 
> The :term:`path importer` provides additional hooks and protocols so that you
> can extend and customize the types of searchable path entries.  For example,
>@@ -534,29 +578,59 @@
> Path entry finder protocol
> --------------------------
> 
>-Path entry finders support the same :meth:`find_module()` method that meta
>-path finders support, however path entry finder's :meth:`find_module()`
>-methods are never called with a ``path`` argument.
>-
>-The :meth:`find_module()` method on path entry finders is deprecated though,
>-and instead path entry finders should implement the :meth:`find_loader()`
>-method.  If it exists on the path entry finder, :meth:`find_loader()` will
>-always be called instead of :meth:`find_module()`.
>+In order to support imports of modules and initialized packages and also to
>+contribute portions to namespace packages, path entry finders must implement
>+the :meth:`find_loader()` method.

This is an improvement, because it de-emphasizes the deprecated API.  Perhaps
add a footnote that describes the legacy API?

> :meth:`find_loader()` takes one argument, the fully qualified name of the
> module being imported.  :meth:`find_loader()` returns a 2-tuple where the
> first item is the loader and the second item is a namespace :term:`portion`.
> When the first item (i.e. the loader) is ``None``, this means that while the
>-path entry finder does not have a loader for the named module, it knows that
>-the :term:`path entry` contributes to a namespace portion for the named
>-module.  This will almost always be the case where Python is asked to import a
>-:term:`namespace package` that has no physical presence on the file system.
>-When a path entry finder returns ``None`` for the loader, the second item of
>-the 2-tuple return value must be a sequence, although it can be empty.
>+path entry finder does not have a loader for the named module, it knows that 
>the
>+path entry contributes to a namespace portion for the named module.  This will
>+almost always be the case where Python is asked to import a namespace package
>+that has no physical presence on the file system.  When a path entry finder
>+returns ``None`` for the loader, the second item of the 2-tuple return value
>+must be a sequence, although it can be empty.
> 
> If :meth:`find_loader()` returns a non-``None`` loader value, the portion is
>-ignored and the loader is returned from the :term:`path importer`, terminating
>-the :term:`import path` search.
>+ignored and the loader is returned from the path importer, terminating the
>+search through the path entries.
>+
>+For backwards compatibility with other implementations of the import
>+protocol, many path entry finders also support the same,
>+traditional :meth:`find_module()` method that meta path finders support.
>+However path entry finder :meth:`find_module()` methods are never called
>+with a ``path`` argument (they are expected to record the appropriate
>+path information from the initial call to the path hook).
>+
>+The :meth:`find_module()` method on path entry finders is deprecated,
>+as it does not allow the path entry finder to contribute portions to
>+namespace packages. Instead path entry finders should implement the
>+:meth:`find_loader()` method as described above. If it exists on the path
>+entry finder, the import system will always call :meth:`find_loader()`
>+in preference to :meth:`find_module()`.

The above is what could be moved to the footnote.

Cheers,
-Barry
_______________________________________________
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: 
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com

Reply via email to