Mirrors
/
cpython
mirror of https://github.com/python/cpython
3
0
Fork 0
Code Releases Activity
Browse Source

s/path importer/path based finder/ (because the path based finder is not an importer and the simpler 'path finder' is too ambiguous)

pull/2332/head
Nick Coghlan 14 years ago
parent
48fec05391
commit
1685db011d
3 changed files with 58 additions and 49 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 6
      Doc/glossary.rst
  2. 97
      Doc/reference/import.rst
  3. 4
      Misc/NEWS

6
Doc/glossary.rst
View File

@ -317,7 +317,7 @@ Glossary
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 @@ Glossary
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 @@ Glossary
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.

97
Doc/reference/import.rst
View File

@ -42,6 +42,12 @@ strategies to search for the named module when the import machinery is
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 @@ whatever strategy it knows about. Objects that implement both of these
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 @@ second argument.
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 @@ Loaders must satisfy the following requirements:
* 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 @@ manipulation code; the namespace loader automatically sets ``__path__``
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 @@ module in the standard library, the default path entry finders also handle
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 @@ process, but it's important to keep in mind that they are subtly different.
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 @@ Path entry finders
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 @@ directories on the file system, zip files, and potentially other "locations"
(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]_.
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
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 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 @@ 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 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 @@ related entries in the data model reference page?
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 @@ alternative to :meth:`find_module`.
: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 @@ Footnotes
.. [#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.

4
Misc/NEWS
View File

@ -55,6 +55,10 @@ Tools/Demos
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

Write Preview
Loading…
Cancel
Save