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