From ccddbb186bcaec77f52a8c37d8b3f56de4b871dd Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Fri, 4 Dec 2015 15:46:21 -0800 Subject: Issue #23936: Clarify what finders are. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Thanks to Raúl Cumplido for the bug report and Thomas Kluyver for the patch. --- Doc/glossary.rst | 22 ++++++++++++++++------ Doc/library/sys.rst | 39 ++++++++++++++++++++++++++------------- 2 files changed, 42 insertions(+), 19 deletions(-) diff --git a/Doc/glossary.rst b/Doc/glossary.rst index 6808e7a..648c679 100644 --- 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 - implement either a method named :meth:`find_loader` or a method named - :meth:`find_module`. See :pep:`302` and :pep:`420` for details and - :class:`importlib.abc.Finder` for an :term:`abstract base class`. + An object that tries to find the :term:`loader` for a module that is + being imported. + + Since Python 3.3, there are two types of finder: :term:`meta path finders + ` for use with :data:`sys.meta_path`, and :term:`path + entry finders ` for use with :data:`sys.path_hooks`. + + See :pep:`302`, :pep:`420` and :pep:`451` for much more detail. 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 + A :term:`finder` returned by a search of :data:`sys.meta_path`. Meta path finders are related to, but different from :term:`path entry finders `. + See :class:`importlib.abc.MetaPathFinder` for the methods that meta path + finders implement. + 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. + module. An instance of :class:`importlib.machinery.ModuleSpec`. 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 + finders implement. + path entry hook A callable on the :data:`sys.path_hook` list which returns a :term:`path entry finder` if it knows how to find modules on a specific :term:`path diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst index f6325cc..36e8ee4 100644 --- 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`. - - :data:`sys.meta_path` is searched before any implicit default finders or - :data:`sys.path`. - - See :pep:`302` for the original specification. - + 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:: + + :class:`importlib.abc.MetaPathFinder` + The abstract base class defining the interface of finder objects on + :data:`meta_path`. + :class:`importlib.machinery.ModuleSpec` + The concrete class which + :meth:`~importlib.abc.MetaPathFinder.find_spec` should return + instances of. + + .. versionchanged:: 3.4 + + :term:`Module specs ` were introduced in Python 3.4, by + :pep:`451`. Earlier versions of Python looked for a method called + :meth:`~importlib.abc.MetaPathFinder.find_module`. + This is still called as a fallback if a :data:`meta_path` entry doesn't + have a :meth:`~importlib.abc.MetaPathFinder.find_spec` method. .. data:: modules -- cgit v0.12