Issue 19944: Fix importlib.find_spec() so it imports parents as needed.
The function is also moved to importlib.util.
diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst
index a3373e0..e2c826c 100644
--- a/Doc/library/importlib.rst
+++ b/Doc/library/importlib.rst
@@ -89,22 +89,6 @@
.. versionchanged:: 3.3
Parent packages are automatically imported.
-.. function:: find_spec(name, path=None)
-
- Find the :term:`spec <module 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
@@ -125,7 +109,7 @@
attribute is set to ``None``.
.. deprecated:: 3.4
- Use :func:`find_spec` instead.
+ Use :func:`importlib.util.find_spec` instead.
.. function:: invalidate_caches()
@@ -1111,6 +1095,22 @@
.. versionadded:: 3.3
+.. function:: find_spec(name, package=None)
+
+ Find the :term:`spec <module spec>` for a module, optionally relative to
+ the specified **package** name. 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.
+
+ If **name** is for a submodule (contains a dot), the parent module is
+ automatically imported.
+
+ **name** and **package** work the same as for :func:`import_module`.
+
+ .. versionadded:: 3.4
+
.. decorator:: module_for_loader
A :term:`decorator` for :meth:`importlib.abc.Loader.load_module`