[Python-Dev] [Python-checkins] cpython: s/path importer/path based finder/ (because the path based finder is not an

Mon Aug 20 19:08:48 CEST 2012

Should that be "path-based"?

On Sun, Aug 19, 2012 at 11:49 PM, nick.coghlan
<python-checkins at python.org>wrote:

> http://hg.python.org/cpython/rev/2f9f5ab3d754
> changeset:   78664:2f9f5ab3d754
> user:        Nick Coghlan <ncoghlan at 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-checkins at python.org
> http://mail.python.org/mailman/listinfo/python-checkins
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20120820/a06ede02/attachment.html>