Skip to content

Commit

Permalink
gh-98040: Remove find_loader, find_module and other deprecated APIs (#…
Browse files Browse the repository at this point in the history 
…98059)

* Remove deprecated classes from pkgutil
* Remove some other PEP 302 obsolescence
* Use find_spec instead of load_module
* Remove more tests of PEP 302 obsolete APIs
* Remove another bunch of tests using obsolete load_modules()
* Remove deleted names from __all__
* Remove obsolete footnote
* imp is removed
* Remove `imp` from generated stdlib names
* What's new and blurb
* Update zipimport documentation for the removed methods
* Fix some Windows tests
* Remove any test (or part of a test) that references `find_module()`.
* Use assertIsNone() / assertIsNotNone() consistently.
* Update Doc/reference/import.rst
* We don't need pkgutil._get_spec() any more either
*  test.test_importlib.fixtures.NullFinder
* ...BadLoaderFinder.find_module
* ...test_api.InvalidatingNullFinder.find_module
* ...test.test_zipimport test of z.find_module
* Suppress cross-references to find_loader and find_module
* Suppress cross-references to Finder
* Suppress cross-references to pkgutil.ImpImporter and pkgutil.ImpLoader

---------

Co-authored-by: Oleg Iarygin <[email protected]>
Co-authored-by: Adam Turner <[email protected]>
  • Loading branch information
@warsaw @arhadthedev @AA-Turner
3 people authored May 3, 2023
1 parent bcea36f commit 3269978
Show file tree
Hide file tree
Showing 39 changed files with 137 additions and 1,047 deletions.
112 changes: 2 additions & 110 deletions Doc/library/importlib.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -127,28 +127,6 @@ Functions
.. versionchanged:: 3.3
Parent packages are automatically imported.

.. function:: find_loader(name, path=None)

Find the loader for a module, optionally within the specified *path*. If the
module is in :attr:`sys.modules`, then ``sys.modules[name].__loader__`` is
returned (unless the loader 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 loader is found.

A dotted name does not have its parents 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.3

.. versionchanged:: 3.4
If ``__loader__`` is not set, raise :exc:`ValueError`, just like when the
attribute is set to ``None``.

.. deprecated:: 3.4
Use :func:`importlib.util.find_spec` instead.

.. function:: invalidate_caches()

Invalidate the internal caches of finders stored at
Expand Down Expand Up @@ -247,7 +225,6 @@ are also provided to help in implementing the core ABCs.
ABC hierarchy::

object
+-- Finder (deprecated)
+-- MetaPathFinder
+-- PathEntryFinder
+-- Loader
Expand All @@ -258,36 +235,14 @@ ABC hierarchy::
+-- SourceLoader


.. class:: Finder

An abstract base class representing a :term:`finder`.

.. deprecated:: 3.3
Use :class:`MetaPathFinder` or :class:`PathEntryFinder` instead.

.. abstractmethod:: find_module(fullname, path=None)

An abstract method for finding a :term:`loader` for the specified
module. Originally specified in :pep:`302`, this method was meant
for use in :data:`sys.meta_path` and in the path-based import subsystem.

.. versionchanged:: 3.4
Returns ``None`` when called instead of raising
:exc:`NotImplementedError`.

.. deprecated:: 3.10
Implement :meth:`MetaPathFinder.find_spec` or
:meth:`PathEntryFinder.find_spec` instead.


.. class:: MetaPathFinder

An abstract base class representing a :term:`meta path finder`.

.. versionadded:: 3.3

.. versionchanged:: 3.10
No longer a subclass of :class:`Finder`.
No longer a subclass of :class:`!Finder`.

.. method:: find_spec(fullname, path, target=None)

Expand All @@ -303,25 +258,6 @@ ABC hierarchy::

.. versionadded:: 3.4

.. method:: find_module(fullname, path)

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
package. If a loader cannot be found, ``None`` is returned.

If :meth:`find_spec` is defined, backwards-compatible functionality is
provided.

.. versionchanged:: 3.4
Returns ``None`` when called instead of raising
:exc:`NotImplementedError`. Can use :meth:`find_spec` to provide
functionality.

.. deprecated:: 3.4
Use :meth:`find_spec` instead.

.. method:: invalidate_caches()

An optional method which, when called, should invalidate any internal
Expand All @@ -342,7 +278,7 @@ ABC hierarchy::
.. versionadded:: 3.3

.. versionchanged:: 3.10
No longer a subclass of :class:`Finder`.
No longer a subclass of :class:`!Finder`.

.. method:: find_spec(fullname, target=None)

Expand All @@ -356,36 +292,6 @@ ABC hierarchy::

.. versionadded:: 3.4

.. method:: find_loader(fullname)

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
signify the contribution of the file system locations to a namespace
package. An empty list can be used for ``portion`` to signify the loader
is not part of a namespace package. If ``loader`` is ``None`` and
``portion`` is the empty list then no loader or location for a namespace
package were found (i.e. failure to find anything for the module).

If :meth:`find_spec` is defined then backwards-compatible functionality is
provided.

.. versionchanged:: 3.4
Returns ``(None, [])`` instead of raising :exc:`NotImplementedError`.
Uses :meth:`find_spec` when available to provide functionality.

.. 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
Expand Down Expand Up @@ -881,13 +787,6 @@ find and load modules.
is no longer valid then ``None`` is returned but no value is cached
in :data:`sys.path_importer_cache`.

.. classmethod:: find_module(fullname, path=None)

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
Expand Down Expand Up @@ -938,13 +837,6 @@ find and load modules.

.. versionadded:: 3.4

.. method:: find_loader(fullname)

Attempt to find the loader to handle *fullname* within :attr:`path`.

.. deprecated:: 3.10
Use :meth:`find_spec` instead.

.. method:: invalidate_caches()

Clear out the internal cache.
Expand Down
27 changes: 0 additions & 27 deletions Doc/library/pkgutil.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -48,33 +48,6 @@ support.
this function to raise an exception (in line with :func:`os.path.isdir`
behavior).


.. class:: ImpImporter(dirname=None)

:pep:`302` Finder that wraps Python's "classic" import algorithm.

If *dirname* is a string, a :pep:`302` finder is created that searches that
directory. If *dirname* is ``None``, a :pep:`302` finder is created that
searches the current :data:`sys.path`, plus any modules that are frozen or
built-in.

Note that :class:`ImpImporter` does not currently support being used by
placement on :data:`sys.meta_path`.

.. deprecated:: 3.3
This emulation is no longer needed, as the standard import mechanism
is now fully :pep:`302` compliant and available in :mod:`importlib`.


.. class:: ImpLoader(fullname, file, filename, etc)

:term:`Loader <loader>` that wraps Python's "classic" import algorithm.

.. deprecated:: 3.3
This emulation is no longer needed, as the standard import mechanism
is now fully :pep:`302` compliant and available in :mod:`importlib`.


.. function:: find_loader(fullname)

Retrieve a module :term:`loader` for the given *fullname*.
Expand Down
2 changes: 1 addition & 1 deletion Doc/library/sys.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1177,7 +1177,7 @@ always available.

:term:`Module specs <module spec>` were introduced in Python 3.4, by
:pep:`451`. Earlier versions of Python looked for a method called
:meth:`~importlib.abc.MetaPathFinder.find_module`.
:meth:`!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.

Expand Down
27 changes: 5 additions & 22 deletions Doc/library/zipimport.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,11 @@ zipimporter Objects
:exc:`ZipImportError` is raised if *archivepath* doesn't point to a valid ZIP
archive.

.. versionchanged:: 3.12

Methods ``find_loader()`` and ``find_module()``, deprecated in 3.10 are
now removed. Use :meth:`find_spec` instead.

.. method:: create_module(spec)

Implementation of :meth:`importlib.abc.Loader.create_module` that returns
Expand All @@ -89,28 +94,6 @@ zipimporter Objects
.. versionadded:: 3.10


.. method:: find_loader(fullname, path=None)

An implementation of :meth:`importlib.abc.PathEntryFinder.find_loader`.

.. deprecated:: 3.10

Use :meth:`find_spec` instead.


.. method:: find_module(fullname, path=None)

Search for a module specified by *fullname*. *fullname* must be the fully
qualified (dotted) module name. It returns the zipimporter instance itself
if the module was found, or :const:`None` if it wasn't. The optional
*path* argument is ignored---it's there for compatibility with the
importer protocol.

.. deprecated:: 3.10

Use :meth:`find_spec` instead.


.. method:: find_spec(fullname, target=None)

An implementation of :meth:`importlib.abc.PathEntryFinder.find_spec`.
Expand Down
34 changes: 17 additions & 17 deletions Doc/reference/import.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -324,15 +324,18 @@ modules, and one that knows how to import modules from an :term:`import path`

.. versionchanged:: 3.4
The :meth:`~importlib.abc.MetaPathFinder.find_spec` method of meta path
finders replaced :meth:`~importlib.abc.MetaPathFinder.find_module`, which
finders replaced :meth:`!find_module`, which
is now deprecated. While it will continue to work without change, the
import machinery will try it only if the finder does not implement
``find_spec()``.

.. versionchanged:: 3.10
Use of :meth:`~importlib.abc.MetaPathFinder.find_module` by the import system
Use of :meth:`!find_module` by the import system
now raises :exc:`ImportWarning`.

.. versionchanged:: 3.12
``find_module()`` has been removed. Use :meth:`find_spec` instead.


Loading
=======
Expand Down Expand Up @@ -837,7 +840,7 @@ stores finder objects rather than being limited to :term:`importer` objects).
In this way, the expensive search for a particular :term:`path entry`
location's :term:`path entry finder` need only be done once. User code is
free to remove cache entries from :data:`sys.path_importer_cache` forcing
the path based finder to perform the path entry search again [#fnpic]_.
the path based finder to perform the path entry search again.

If the path entry is not present in the cache, the path based finder iterates
over every callable in :data:`sys.path_hooks`. Each of the :term:`path entry
Expand Down Expand Up @@ -887,21 +890,21 @@ module. ``find_spec()`` returns a fully populated spec for the module.
This spec will always have "loader" set (with one exception).

To indicate to the import machinery that the spec represents a namespace
:term:`portion`, the path entry finder sets "submodule_search_locations" to
:term:`portion`, the path entry finder sets ``submodule_search_locations`` to
a list containing the portion.

.. versionchanged:: 3.4
:meth:`~importlib.abc.PathEntryFinder.find_spec` replaced
:meth:`~importlib.abc.PathEntryFinder.find_loader` and
:meth:`~importlib.abc.PathEntryFinder.find_module`, both of which
:meth:`!find_loader` and
:meth:`!find_module`, both of which
are now deprecated, but will be used if ``find_spec()`` is not defined.

Older path entry finders may implement one of these two deprecated methods
instead of ``find_spec()``. The methods are still respected for the
sake of backward compatibility. However, if ``find_spec()`` is
implemented on the path entry finder, the legacy methods are ignored.

:meth:`~importlib.abc.PathEntryFinder.find_loader` takes one argument, the
:meth:`!find_loader` takes one argument, the
fully qualified name of the module being imported. ``find_loader()``
returns a 2-tuple where the first item is the loader and the second item
is a namespace :term:`portion`.
Expand All @@ -920,10 +923,13 @@ a list containing the portion.
``find_loader()`` in preference to ``find_module()``.

.. versionchanged:: 3.10
Calls to :meth:`~importlib.abc.PathEntryFinder.find_module` and
:meth:`~importlib.abc.PathEntryFinder.find_loader` by the import
Calls to :meth:`!find_module` and
:meth:`!find_loader` by the import
system will raise :exc:`ImportWarning`.

.. versionchanged:: 3.12
``find_module()`` and ``find_loader()`` have been removed.


Replacing the standard import system
====================================
Expand Down Expand Up @@ -1045,8 +1051,8 @@ The original specification for :data:`sys.meta_path` was :pep:`302`, with
subsequent extension in :pep:`420`.

:pep:`420` introduced :term:`namespace packages <namespace package>` for
Python 3.3. :pep:`420` also introduced the :meth:`find_loader` protocol as an
alternative to :meth:`find_module`.
Python 3.3. :pep:`420` also introduced the :meth:`!find_loader` protocol as an
alternative to :meth:`!find_module`.

:pep:`366` describes the addition of the ``__package__`` attribute for
explicit relative imports in main modules.
Expand All @@ -1073,9 +1079,3 @@ methods to finders and loaders.
module may replace itself in :data:`sys.modules`. This is
implementation-specific behavior that is not guaranteed to work in other
Python implementations.
.. [#fnpic] In legacy code, it is possible to find instances of
:class:`imp.NullImporter` in the :data:`sys.path_importer_cache`. It
is recommended that code be changed to use ``None`` instead. See
:ref:`portingpythoncode` for more details. Note that the ``imp`` module
was removed in Python 3.12.
2 changes: 1 addition & 1 deletion Doc/whatsnew/2.3.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -728,7 +728,7 @@ module:

Importer objects must have a single method, ``find_module(fullname,
path=None)``. *fullname* will be a module or package name, e.g. ``string`` or
``distutils.core``. :meth:`find_module` must return a loader object that has a
``distutils.core``. :meth:`!find_module` must return a loader object that has a
single method, ``load_module(fullname)``, that creates and returns the
corresponding module object.

Expand Down
Loading

0 comments on commit 3269978

Please sign in to comment.