diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -86,6 +86,21 @@ that was imported (e.g. ``pkg.mod``), while :func:`__import__` returns the top-level package or module (e.g. ``pkg``). +.. function:: find_spec(name, path=None) + + Find the 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 @@ -105,6 +120,9 @@ 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 @@ -233,9 +251,19 @@ .. versionadded:: 3.3 + .. method:: find_spec(fullname, path) + + 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. + + .. 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 @@ -245,6 +273,9 @@ Returns ``None`` when called instead of raising :exc:`NotImplementedError`. + .. deprecated:: 3.4 + Implement :meth:`find_spec` instead. + .. method:: invalidate_caches() An optional method which, when called, should invalidate any internal @@ -265,9 +296,19 @@ .. versionadded:: 3.3 + .. method:: find_spec(fullname, path) + + 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. + + .. 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 @@ -280,11 +321,17 @@ .. versionchanged:: 3.4 Returns ``(None, [])`` instead of raising :exc:`NotImplementedError`. + .. deprecated:: 3.4 + Implement :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 @@ -297,9 +344,26 @@ 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. @@ -346,9 +410,16 @@ Raise :exc:`ImportError` when called instead of :exc:`NotImplementedError`. + .. deprecated:: 3.4 + The recommended APIs 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. @@ -357,6 +428,9 @@ .. versionchanged:: 3.4 Made optional instead of an abstractmethod. + .. deprecated:: 3.4 + The import machinery now takes care of this automatically. + .. class:: ResourceLoader @@ -479,6 +553,9 @@ Calls super's ``load_module()``. + .. deprecated:: 3.4 + Use :meth:`exec_module` instead. + .. method:: get_filename(fullname) Returns :attr:`path`. @@ -1023,11 +1100,17 @@ Set ``__loader__`` if set to ``None``, as if the attribute does not exist. + .. deprecated:: 3.4 + The import machinery take 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 take 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