Should that be "path-based"?<br><br><div class="gmail_quote">On Sun, Aug 19, 2012 at 11:49 PM, nick.coghlan <span dir="ltr"><<a href="mailto:python-checkins@python.org" target="_blank">python-checkins@python.org</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><a href="http://hg.python.org/cpython/rev/2f9f5ab3d754" target="_blank">http://hg.python.org/cpython/rev/2f9f5ab3d754</a><br>
changeset: 78664:2f9f5ab3d754<br>
user: Nick Coghlan <<a href="mailto:ncoghlan@gmail.com">ncoghlan@gmail.com</a>><br>
date: Mon Aug 20 13:49:08 2012 +1000<br>
summary:<br>
s/path importer/path based finder/ (because the path based finder is not an importer and the simpler 'path finder' is too ambiguous)<br>
<br>
files:<br>
Doc/glossary.rst | 6 +-<br>
Doc/reference/import.rst | 95 ++++++++++++++-------------<br>
Misc/NEWS | 4 +<br>
3 files changed, 57 insertions(+), 48 deletions(-)<br>
<br>
<br>
diff --git a/Doc/glossary.rst b/Doc/glossary.rst<br>
--- a/Doc/glossary.rst<br>
+++ b/Doc/glossary.rst<br>
@@ -317,7 +317,7 @@<br>
<br>
import path<br>
A list of locations (or :term:`path entries <path entry>`) that are<br>
- searched by the :term:`path importer` for modules to import. During<br>
+ searched by the :term:`path based finder` for modules to import. During<br>
import, this list of locations usually comes from :data:`sys.path`, but<br>
for subpackages it may also come from the parent package's ``__path__``<br>
attribute.<br>
@@ -550,7 +550,7 @@<br>
<br>
path entry<br>
A single location on the :term:`import path` which the :term:`path<br>
- importer` consults to find modules for importing.<br>
+ based finder` consults to find modules for importing.<br>
<br>
path entry finder<br>
A :term:`finder` returned by a callable on :data:`sys.path_hooks`<br>
@@ -562,7 +562,7 @@<br>
entry finder` if it knows how to find modules on a specific :term:`path<br>
entry`.<br>
<br>
- path importer<br>
+ path based finder<br>
One of the default :term:`meta path finders <meta path finder>` which<br>
searches an :term:`import path` for modules.<br>
<br>
diff --git a/Doc/reference/import.rst b/Doc/reference/import.rst<br>
--- a/Doc/reference/import.rst<br>
+++ b/Doc/reference/import.rst<br>
@@ -42,6 +42,12 @@<br>
invoked. These strategies can be modified and extended by using various hooks<br>
described in the sections below.<br>
<br>
+.. versionchanged:: 3.3<br>
+ The import system has been updated to fully implement the second phase<br>
+ of PEP 302. There is no longer any implicit import machinery - the full<br>
+ import system is exposed through :data:`sys.meta_path`. In addition,<br>
+ native namespace package support has been implemented (see PEP 420).<br>
+<br>
<br>
:mod:`importlib`<br>
================<br>
@@ -213,7 +219,7 @@<br>
interfaces are referred to as :term:`importers <importer>` - they return<br>
themselves when they find that they can load the requested module.<br>
<br>
-By default, Python comes with several default finders and importers. One<br>
+Python includes a number of default finders and importers. One<br>
knows how to locate frozen modules, and another knows how to locate<br>
built-in modules. A third default finder searches an :term:`import path`<br>
for modules. The :term:`import path` is a list of locations that may<br>
@@ -307,7 +313,7 @@<br>
Python's default :data:`sys.meta_path` has three meta path finders, one that<br>
knows how to import built-in modules, one that knows how to import frozen<br>
modules, and one that knows how to import modules from an :term:`import path`<br>
-(i.e. the :term:`path importer`).<br>
+(i.e. the :term:`path based finder`).<br>
<br>
<br>
Loaders<br>
@@ -356,14 +362,14 @@<br>
* If the module is a package (either regular or namespace), the loader must<br>
set the module object's ``__path__`` attribute. The value must be<br>
iterable, but may be empty if ``__path__`` has no further significance<br>
- to the importer. If ``__path__`` is not empty, it must produce strings<br>
+ to the loader. If ``__path__`` is not empty, it must produce strings<br>
when iterated over. More details on the semantics of ``__path__`` are<br>
given :ref:`below <package-path-rules>`.<br>
<br>
* The ``__loader__`` attribute must be set to the loader object that loaded<br>
the module. This is mostly for introspection and reloading, but can be<br>
- used for additional importer-specific functionality, for example getting<br>
- data associated with an importer.<br>
+ used for additional loader-specific functionality, for example getting<br>
+ data associated with a loader.<br>
<br>
* The module's ``__package__`` attribute should be set. Its value must be a<br>
string, but it can be the same value as its ``__name__``. If the attribute<br>
@@ -456,18 +462,18 @@<br>
correctly for the namespace package.<br>
<br>
<br>
-The Path Importer<br>
-=================<br>
+The Path Based Finder<br>
+=====================<br>
<br>
.. index::<br>
- single: path importer<br>
+ single: path based finder<br>
<br>
As mentioned previously, Python comes with several default meta path finders.<br>
-One of these, called the :term:`path importer`, searches an :term:`import<br>
+One of these, called the :term:`path based finder`, searches an :term:`import<br>
path`, which contains a list of :term:`path entries <path entry>`. Each path<br>
entry names a location to search for modules.<br>
<br>
-The path importer itself doesn't know how to import anything. Instead, it<br>
+The path based finder itself doesn't know how to import anything. Instead, it<br>
traverses the individual path entries, associating each of them with a<br>
path entry finder that knows how to handle that particular kind of path.<br>
<br>
@@ -479,10 +485,10 @@<br>
loading all of these file types (other than shared libraries) from zipfiles.<br>
<br>
Path entries need not be limited to file system locations. They can refer to<br>
-the URLs, database queries, or any other location that can be specified as a<br>
+URLs, database queries, or any other location that can be specified as a<br>
string.<br>
<br>
-The :term:`path importer` provides additional hooks and protocols so that you<br>
+The path based finder provides additional hooks and protocols so that you<br>
can extend and customize the types of searchable path entries. For example,<br>
if you wanted to support path entries as network URLs, you could write a hook<br>
that implements HTTP semantics to find modules on the web. This hook (a<br>
@@ -498,8 +504,8 @@<br>
In particular, meta path finders operate at the beginning of the import<br>
process, as keyed off the :data:`sys.meta_path` traversal.<br>
<br>
-On the other hand, path entry finders are in a sense an implementation detail<br>
-of the :term:`path importer`, and in fact, if the path importer were to be<br>
+By contrast, path entry finders are in a sense an implementation detail<br>
+of the path based finder, and in fact, if the path based finder were to be<br>
removed from :data:`sys.meta_path`, none of the path entry finder semantics<br>
would be invoked.<br>
<br>
@@ -513,17 +519,17 @@<br>
single: sys.path_importer_cache<br>
single: PYTHONPATH<br>
<br>
-The :term:`path importer` is responsible for finding and loading Python<br>
+The :term:`path based finder` is responsible for finding and loading Python<br>
modules and packages whose location is specified with a string :term:`path<br>
entry`. Most path entries name locations in the file system, but they need<br>
not be limited to this.<br>
<br>
-As a meta path finder, the :term:`path importer` implements the<br>
+As a meta path finder, the :term:`path based finder` implements the<br>
:meth:`find_module()` protocol previously described, however it exposes<br>
additional hooks that can be used to customize how modules are found and<br>
loaded from the :term:`import path`.<br>
<br>
-Three variables are used by the :term:`path importer`, :data:`sys.path`,<br>
+Three variables are used by the :term:`path based finder`, :data:`sys.path`,<br>
:data:`sys.path_hooks` and :data:`sys.path_importer_cache`. The ``__path__``<br>
attributes on package objects are also used. These provide additional ways<br>
that the import machinery can be customized.<br>
@@ -536,38 +542,40 @@<br>
(see the :mod:`site` module) that should be searched for modules, such as<br>
URLs, or database queries.<br>
<br>
-The :term:`path importer` is a :term:`meta path finder`, so the import<br>
+The :term:`path based finder` is a :term:`meta path finder`, so the import<br>
machinery begins the :term:`import path` search by calling the path<br>
-importer's :meth:`find_module()` method as described previously. When<br>
+based finder's :meth:`find_module()` method as described previously. When<br>
the ``path`` argument to :meth:`find_module()` is given, it will be a<br>
list of string paths to traverse - typically a package's ``__path__``<br>
attribute for an import within that package. If the ``path`` argument<br>
is ``None``, this indicates a top level import and :data:`sys.path` is used.<br>
<br>
-The :term:`path importer` iterates over every entry in the search path, and<br>
+The path based finder iterates over every entry in the search path, and<br>
for each of these, looks for an appropriate :term:`path entry finder` for the<br>
path entry. Because this can be an expensive operation (e.g. there may be<br>
-`stat()` call overheads for this search), the :term:`path importer` maintains<br>
+`stat()` call overheads for this search), the path based finder maintains<br>
a cache mapping path entries to path entry finders. This cache is maintained<br>
-in :data:`sys.path_importer_cache`. In this way, the expensive search for a<br>
-particular :term:`path entry` location's :term:`path entry finder` need only<br>
-be done once. User code is free to remove cache entries from<br>
-:data:`sys.path_importer_cache` forcing the :term:`path importer` to perform<br>
-the path entry search again [#fnpic]_.<br>
+in :data:`sys.path_importer_cache` (despite the name, this cache actually<br>
+stores finder objects rather than being limited to :term:`importer` objects).<br>
+In this way, the expensive search for a particular :term:`path entry`<br>
+location's :term:`path entry finder` need only be done once. User code is<br>
+free to remove cache entries from :data:`sys.path_importer_cache` forcing<br>
+the path based finder to perform the path entry search again [#fnpic]_.<br>
<br>
-If the path entry is not present in the cache, the path importer iterates over<br>
-every callable in :data:`sys.path_hooks`. Each of the :term:`path entry hooks<br>
-<path entry hook>` in this list is called with a single argument, the path<br>
-entry being searched. This callable may either return a :term:`path entry<br>
-finder` that can handle the path entry, or it may raise :exc:`ImportError`.<br>
-An :exc:`ImportError` is used by the path importer to signal that the hook<br>
+If the path entry is not present in the cache, the path based finder iterates<br>
+over every callable in :data:`sys.path_hooks`. Each of the<br>
+:term:`path entry hooks <path entry hook>` in this list is called with a<br>
+single argument, the path entry to be searched. This callable may either<br>
+return a :term:`path entry finder` that can handle the path entry, or it may<br>
+raise :exc:`ImportError`.<br>
+An :exc:`ImportError` is used by the path based finder to signal that the hook<br>
cannot find a :term:`path entry finder` for that :term:`path entry`. The<br>
exception is ignored and :term:`import path` iteration continues.<br>
<br>
If :data:`sys.path_hooks` iteration ends with no :term:`path entry finder`<br>
-being returned, then the path importer's :meth:`find_module()` method will<br>
-store ``None`` in :data:`sys.path_importer_cache` (to indicate that there<br>
-is no finder for this path entry) and return ``None``, indicating that<br>
+being returned, then the path based finder's :meth:`find_module()` method<br>
+will store ``None`` in :data:`sys.path_importer_cache` (to indicate that<br>
+there is no finder for this path entry) and return ``None``, indicating that<br>
this :term:`meta path finder` could not find the module.<br>
<br>
If a :term:`path entry finder` *is* returned by one of the :term:`path entry<br>
@@ -594,8 +602,8 @@<br>
must be a sequence, although it can be empty.<br>
<br>
If :meth:`find_loader()` returns a non-``None`` loader value, the portion is<br>
-ignored and the loader is returned from the path importer, terminating the<br>
-search through the path entries.<br>
+ignored and the loader is returned from the path based finder, terminating<br>
+the search through the path entries.<br>
<br>
For backwards compatibility with other implementations of the import<br>
protocol, many path entry finders also support the same,<br>
@@ -645,9 +653,6 @@<br>
XXX runpy, pkgutil, et al in the library manual should all get "See Also"<br>
links at the top pointing to the new import system section.<br>
<br>
-XXX The :term:`path importer` is not, in fact, an :term:`importer`. That's<br>
-why the corresponding implementation class is :class:`importlib.PathFinder`.<br>
-<br>
<br>
References<br>
==========<br>
@@ -667,8 +672,8 @@<br>
:pep:`366` describes the addition of the ``__package__`` attribute for<br>
explicit relative imports in main modules.<br>
<br>
-:pep:`328` introduced absolute and relative imports and initially proposed<br>
-``__name__`` for semantics :pep:`366` would eventually specify for<br>
+:pep:`328` introduced absolute and explicit relative imports and initially<br>
+proposed ``__name__`` for semantics :pep:`366` would eventually specify for<br>
``__package__``.<br>
<br>
:pep:`338` defines executing modules as scripts.<br>
@@ -679,14 +684,14 @@<br>
<br>
.. [#fnmo] See :class:`types.ModuleType`.<br>
<br>
-.. [#fnlo] The importlib implementation appears not to use the return value<br>
+.. [#fnlo] The importlib implementation avoids using the return value<br>
directly. Instead, it gets the module object by looking the module name up<br>
- in :data:`sys.modules`.) The indirect effect of this is that an imported<br>
+ in :data:`sys.modules`. The indirect effect of this is that an imported<br>
module may replace itself in :data:`sys.modules`. This is<br>
implementation-specific behavior that is not guaranteed to work in other<br>
Python implementations.<br>
<br>
.. [#fnpic] In legacy code, it is possible to find instances of<br>
:class:`imp.NullImporter` in the :data:`sys.path_importer_cache`. It<br>
- recommended that code be changed to use ``None`` instead. See<br>
+ is recommended that code be changed to use ``None`` instead. See<br>
:ref:`portingpythoncode` for more details.<br>
diff --git a/Misc/NEWS b/Misc/NEWS<br>
--- a/Misc/NEWS<br>
+++ b/Misc/NEWS<br>
@@ -55,6 +55,10 @@<br>
Documentation<br>
-------------<br>
<br>
+- The "path importer" misnomer has been replaced with Eric Snow's<br>
+ more-awkward-but-at-least-not-wrong suggestion of "path based finder" in<br>
+ the import system reference docs<br>
+<br>
- Issue #15640: Document importlib.abc.Finder as deprecated.<br>
<br>
- Issue #15630: Add an example for "continue" stmt in the tutorial. Patch by<br>
<span class="HOEnZb"><font color="#888888"><br>
--<br>
Repository URL: <a href="http://hg.python.org/cpython" target="_blank">http://hg.python.org/cpython</a><br>
</font></span><br>_______________________________________________<br>
Python-checkins mailing list<br>
<a href="mailto:Python-checkins@python.org">Python-checkins@python.org</a><br>
<a href="http://mail.python.org/mailman/listinfo/python-checkins" target="_blank">http://mail.python.org/mailman/listinfo/python-checkins</a><br>
<br></blockquote></div><br>