From ca2d854df89c764296999f98b39008fe37ef21a3 Mon Sep 17 00:00:00 2001 From: Eric Snow Date: Mon, 16 Dec 2013 23:06:52 -0700 Subject: [PATCH] Issue #19713: Update importlib docs for module spec changes, including deprecations. --- Doc/glossary.rst | 4 + Doc/library/importlib.rst | 172 +++++++++++++++++++++++++++++++++----- 2 files changed, 154 insertions(+), 22 deletions(-) diff --git a/Doc/glossary.rst b/Doc/glossary.rst index 8de347bd910..2f658aca097 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -539,6 +539,10 @@ Glossary See also :term:`package`. + module spec + A namespace containing the import-related information used to load a + module. + MRO See :term:`method resolution order`. diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index 867674edf3f..82d6d6d7482 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -89,6 +89,22 @@ Functions .. versionchanged:: 3.3 Parent packages are automatically imported. +.. function:: find_spec(name, path=None) + + Find the :term:`spec ` for a module, optionally within the + specified *path*. If the module is in :attr:`sys.modules`, then + ``sys.modules[name].__spec__`` is returned (unless the spec would be + ``None`` or is not set, in which case :exc:`ValueError` is raised). + Otherwise a search using :attr:`sys.meta_path` is done. ``None`` is + returned if no spec is found. + + A dotted name does not have its parent implicitly imported as that requires + loading them and that may not be desired. To properly import a submodule you + will need to import all parent packages of the submodule and use the correct + argument to *path*. + + .. versionadded:: 3.4 + .. function:: find_loader(name, path=None) Find the loader for a module, optionally within the specified *path*. If the @@ -108,6 +124,9 @@ Functions If ``__loader__`` is not set, raise :exc:`ValueError`, just like when the attribute is set to ``None``. + .. deprecated:: 3.4 + Use :func:`find_spec` instead. + .. function:: invalidate_caches() Invalidate the internal caches of finders stored at @@ -236,9 +255,21 @@ ABC hierarchy:: .. versionadded:: 3.3 + .. method:: find_spec(fullname, path, target=None) + + An abstract method for finding a :term:`spec ` for + the specified module. If this is a top-level import, *path* will + be ``None``. Otherwise, this is a search for a subpackage or + module and *path* will be the value of :attr:`__path__` from the + parent package. If a spec cannot be found, ``None`` is returned. + When passed in, ``target`` is a module object that the finder may + use to make a more educated about what spec to return. + + .. versionadded:: 3.4 + .. method:: find_module(fullname, path) - An abstract method for finding a :term:`loader` for the specified + A legacy method for finding a :term:`loader` for the specified module. If this is a top-level import, *path* will be ``None``. Otherwise, this is a search for a subpackage or module and *path* will be the value of :attr:`__path__` from the parent @@ -248,6 +279,9 @@ ABC hierarchy:: Returns ``None`` when called instead of raising :exc:`NotImplementedError`. + .. deprecated:: 3.4 + Use :meth:`find_spec` instead. + .. method:: invalidate_caches() An optional method which, when called, should invalidate any internal @@ -268,9 +302,20 @@ ABC hierarchy:: .. versionadded:: 3.3 + .. method:: find_spec(fullname, target=None) + + An abstract method for finding a :term:`spec ` for + the specified module. The finder will search for the module only + within the :term:`path entry` to which it is assigned. If a spec + cannot be found, ``None`` is returned. When passed in, ``target`` + is a module object that the finder may use to make a more educated + about what spec to return. + + .. versionadded:: 3.4 + .. method:: find_loader(fullname) - An abstract method for finding a :term:`loader` for the specified + A legacy method for finding a :term:`loader` for the specified module. Returns a 2-tuple of ``(loader, portion)`` where ``portion`` is a sequence of file system locations contributing to part of a namespace package. The loader may be ``None`` while specifying ``portion`` to @@ -283,11 +328,17 @@ ABC hierarchy:: .. versionchanged:: 3.4 Returns ``(None, [])`` instead of raising :exc:`NotImplementedError`. + .. deprecated:: 3.4 + Use :meth:`find_spec` instead. + .. method:: find_module(fullname) A concrete implementation of :meth:`Finder.find_module` which is equivalent to ``self.find_loader(fullname)[0]``. + .. deprecated:: 3.4 + Use :meth:`find_spec` instead. + .. method:: invalidate_caches() An optional method which, when called, should invalidate any internal @@ -300,9 +351,26 @@ ABC hierarchy:: An abstract base class for a :term:`loader`. See :pep:`302` for the exact definition for a loader. + .. method:: create_module(spec) + + An optional method that returns the module object to use when + importing a module. create_module() may also return ``None``, + indicating that the default module creation should take place + instead. + + .. versionadded:: 3.4 + + .. method:: exec_module(module) + + An abstract method that executes the module in its own namespace + when a module is imported or reloaded. The module should already + be initialized when exec_module() is called. + + .. versionadded:: 3.4 + .. method:: load_module(fullname) - An abstract method for loading a module. If the module cannot be + A legacy method for loading a module. If the module cannot be loaded, :exc:`ImportError` is raised, otherwise the loaded module is returned. @@ -349,9 +417,16 @@ ABC hierarchy:: Raise :exc:`ImportError` when called instead of :exc:`NotImplementedError`. + .. deprecated:: 3.4 + The recommended API for loading a module is :meth:`exec_module` + (and optionally :meth:`create_module`). Loaders should implement + it instead of load_module(). The import machinery takes care of + all the other responsibilities of load_module() when exec_module() + is implemented. + .. method:: module_repr(module) - An optional method which when implemented calculates and returns the + A legacy method which when implemented calculates and returns the given module's repr, as a string. The module type's default repr() will use the result of this method as appropriate. @@ -360,6 +435,9 @@ ABC hierarchy:: .. versionchanged:: 3.4 Made optional instead of an abstractmethod. + .. deprecated:: 3.4 + The import machinery now takes care of this automatically. + .. class:: ResourceLoader @@ -434,9 +512,18 @@ ABC hierarchy:: .. versionadded:: 3.4 + .. method:: exec_module(module) + + Implementation of :meth:`Loader.exec_module`. + + .. versionadded:: 3.4 + .. method:: load_module(fullname) - Implementation of :meth:`Loader.load_module`. + Implementation of :meth:`Loader.load_module`. + + .. deprecated:: 3.4 + use :meth:`exec_module` instead. .. class:: ExecutionLoader @@ -482,6 +569,9 @@ ABC hierarchy:: Calls super's ``load_module()``. + .. deprecated:: 3.4 + Use :meth:`Loader.exec_module` instead. + .. method:: get_filename(fullname) Returns :attr:`path`. @@ -558,9 +648,18 @@ ABC hierarchy:: Concrete implementation of :meth:`InspectLoader.get_code`. + .. method:: exec_module(module) + + Concrete implementation of :meth:`Loader.exec_module`. + + .. versionadded:: 3.4 + .. method:: load_module(fullname) - Concrete implementation of :meth:`Loader.load_module`. + Concrete implementation of :meth:`Loader.load_module`. + + .. deprecated:: 3.4 + Use :meth:`exec_module` instead. .. method:: get_source(fullname) @@ -641,6 +740,10 @@ find and load modules. Only class methods are defined by this class to alleviate the need for instantiation. + .. note:: + Due to limitations in the extension module C-API, for now + BuiltinImporter does not implement :meth:`Loader.exec_module`. + .. class:: FrozenImporter @@ -671,28 +774,37 @@ find and load modules. Only class methods are defined by this class to alleviate the need for instantiation. + .. classmethod:: find_spec(fullname, path=None, target=None) + + Class method that attempts to find a :term:`spec ` + for the module specified by *fullname* on :data:`sys.path` or, if + defined, on *path*. For each path entry that is searched, + :data:`sys.path_importer_cache` is checked. If a non-false object + is found then it is used as the :term:`path entry finder` to look + for the module being searched for. If no entry is found in + :data:`sys.path_importer_cache`, then :data:`sys.path_hooks` is + searched for a finder for the path entry and, if found, is stored + in :data:`sys.path_importer_cache` along with being queried about + the module. If no finder is ever found then ``None`` is both + stored in the cache and returned. + + .. versionadded:: 3.4 + .. classmethod:: find_module(fullname, path=None) - Class method that attempts to find a :term:`loader` for the module - specified by *fullname* on :data:`sys.path` or, if defined, on - *path*. For each path entry that is searched, - :data:`sys.path_importer_cache` is checked. If a non-false object is - found then it is used as the :term:`path entry finder` to look for the - module being searched for. If no entry is found in - :data:`sys.path_importer_cache`, then :data:`sys.path_hooks` is - searched for a finder for the path entry and, if found, is stored in - :data:`sys.path_importer_cache` along with being queried about the - module. If no finder is ever found then ``None`` is both stored in - the cache and returned. + A legacy wrapper around :meth:`find_spec`. + + .. deprecated:: 3.4 + Use :meth:`find_spec` instead. .. classmethod:: invalidate_caches() - Calls :meth:`importlib.abc.PathEntryFinder.invalidate_caches` on all - finders stored in :attr:`sys.path_importer_cache`. + Calls :meth:`importlib.abc.PathEntryFinder.invalidate_caches` on all + finders stored in :attr:`sys.path_importer_cache`. - .. versionchanged:: 3.4 - Calls objects in :data:`sys.path_hooks` with the current working directory - for ``''`` (i.e. the empty string). + .. versionchanged:: 3.4 + Calls objects in :data:`sys.path_hooks` with the current working + directory for ``''`` (i.e. the empty string). .. class:: FileFinder(path, \*loader_details) @@ -724,6 +836,12 @@ find and load modules. The path the finder will search in. + .. method:: find_spec(fullname, target=None) + + Attempt to find the spec to handle *fullname* within :attr:`path`. + + .. versionadded:: 3.4 + .. method:: find_loader(fullname) Attempt to find the loader to handle *fullname* within :attr:`path`. @@ -829,6 +947,10 @@ find and load modules. Loads the extension module if and only if *fullname* is the same as :attr:`name` or is ``None``. + .. note:: + Due to limitations in the extension module C-API, for now + ExtensionFileLoader does not implement :meth:`Loader.exec_module`. + .. method:: is_package(fullname) Returns ``True`` if the file path points to a package's ``__init__`` @@ -1026,11 +1148,17 @@ an :term:`importer`. Set ``__loader__`` if set to ``None``, as if the attribute does not exist. + .. deprecated:: 3.4 + The import machinery takes care of this automatically. + .. decorator:: set_package A :term:`decorator` for :meth:`importlib.abc.Loader.load_module` to set the :attr:`__package__` attribute on the returned module. If :attr:`__package__` is set and has a value other than ``None`` it will not be changed. + .. deprecated:: 3.4 + The import machinery takes care of this automatically. + .. function:: spec_from_loader(name, loader, *, origin=None, is_package=None) A factory function for creating a :class:`ModuleSpec` instance based