cpython: 88cee7d16ccb (original) (raw)

Mercurial > cpython

changeset 99434:88cee7d16ccb 3.5

Issue #23936: Clarify what finders are. Thanks to Raúl Cumplido for the bug report and Thomas Kluyver for the patch. [#23936]

Brett Cannon brett@python.org
date	Fri, 04 Dec 2015 15:46:21 -0800
parents	567baf74ebad
children	1b1900d2a537 ae27ad306dbf
files	Doc/glossary.rst Doc/library/sys.rst
diffstat	2 files changed, 39 insertions(+), 16 deletions(-)[+] [-] Doc/glossary.rst 22 Doc/library/sys.rst 33

line wrap: on

line diff

--- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -308,10 +308,14 @@ Glossary A synonym for :term:file object. finder

 An object that tries to find the :term:`loader` for a module. It must[](#l1.7)

 implement either a method named :meth:`find_loader` or a method named[](#l1.8)

 :meth:`find_module`. See :pep:`302` and :pep:`420` for details and[](#l1.9)

 :class:`importlib.abc.Finder` for an :term:`abstract base class`.[](#l1.10)

 An object that tries to find the :term:`loader` for a module that is[](#l1.11)

```
 being imported.[](#l1.12)
```

 Since Python 3.3, there are two types of finder: :term:`meta path finders[](#l1.14)

 <meta path finder>` for use with :data:`sys.meta_path`, and :term:`path[](#l1.15)

 entry finders <path entry finder>` for use with :data:`sys.path_hooks`.[](#l1.16)

 See :pep:`302`, :pep:`420` and :pep:`451` for much more detail.[](#l1.18)

floor division Mathematical division that rounds down to nearest integer. The floor @@ -593,10 +597,13 @@ Glossary :class:collections.OrderedDict and :class:collections.Counter. meta path finder

 A finder returned by a search of :data:`sys.meta_path`.  Meta path[](#l1.26)

 A :term:`finder` returned by a search of :data:`sys.meta_path`.  Meta path[](#l1.27)
 finders are related to, but different from :term:`path entry finders[](#l1.28)
 <path entry finder>`.[](#l1.29)

 See :class:`importlib.abc.MetaPathFinder` for the methods that meta path[](#l1.31)

```
 finders implement.[](#l1.32)
```

+ metaclass The class of a class. Class definitions create a class name, a class dictionary, and a list of base classes. The metaclass is responsible for @@ -630,7 +637,7 @@ Glossary module spec A namespace containing the import-related information used to load a

```
 module.[](#l1.41)
```

 module. An instance of :class:`importlib.machinery.ModuleSpec`.[](#l1.42)

MRO See :term:method resolution order. @@ -757,6 +764,9 @@ Glossary (i.e. a :term:path entry hook) which knows how to locate modules given a :term:path entry.

 See :class:`importlib.abc.PathEntryFinder` for the methods that path entry[](#l1.50)

```
 finders implement.[](#l1.51)
```

+ path entry hook A callable on the :data:sys.path_hook list which returns a :term:path[](#l1.54) entry finder if it knows how to find modules on a specific :term:`path

--- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@ -774,19 +774,32 @@ always available. .. data:: meta_path

A list of :term:finder objects that have their :meth:find_module
methods called to see if one of the objects can find the module to be
imported. The :meth:find_module method is called at least with the
absolute name of the module being imported. If the module to be imported is
contained in package then the parent package's :attr:__path__ attribute
is passed in as a second argument. The method returns None if
the module cannot be found, else returns a :term:loader.

A list of :term:meta path finder objects that have their
:meth:~importlib.abc.MetaPathFinder.find_spec methods called to see if one
of the objects can find the module to be imported. The
:meth:~importlib.abc.MetaPathFinder.find_spec method is called with at
least the absolute name of the module being imported. If the module to be
imported is contained in a package, then the parent package's :attr:__path__
attribute is passed in as a second argument. The method returns a
:term:module spec, or None if the module cannot be found.

.. seealso::

:data:sys.meta_path is searched before any implicit default finders or
:data:sys.path.

   :class:`importlib.abc.MetaPathFinder`[](#l2.27)

     The abstract base class defining the interface of finder objects on[](#l2.28)

```
     :data:`meta_path`.[](#l2.29)
```

   :class:`importlib.machinery.ModuleSpec`[](#l2.30)

```
     The concrete class which[](#l2.31)
```

     :meth:`~importlib.abc.MetaPathFinder.find_spec` should return[](#l2.32)

```
     instances of.[](#l2.33)
```

See :pep:302 for the original specification.

.. versionchanged:: 3.4

   :term:`Module specs <module spec>` were introduced in Python 3.4, by[](#l2.38)

   :pep:`451`. Earlier versions of Python looked for a method called[](#l2.39)

   :meth:`~importlib.abc.MetaPathFinder.find_module`.[](#l2.40)

   This is still called as a fallback if a :data:`meta_path` entry doesn't[](#l2.41)

   have a :meth:`~importlib.abc.MetaPathFinder.find_spec` method.[](#l2.42)

.. data:: modules