bpo-26131: Deprecate usage of load_module() (GH-23469)

Raise an ImportWarning when the import system falls back on load_module(). As for implementations of load_module(), raise a DeprecationWarning.

Author: brettcannon

Doc/whatsnew/3.10.rst

@@ -394,7 +394,8 @@ Optimizations
  with ``gcc`` by up to 30%. See `this article
 <https://developers.redhat.com/blog/2020/06/25/red-hat-enterprise-linux-8-2-brings-faster-python-3-8-run-speeds/>`_
  for more details. (Contributed by Victor Stinner and Pablo Galindo in
-:issue:`38980`)
+:issue:`38980`.)
+
 
 * Function parameters and their annotations are no longer computed at runtime,
  but rather at compilation time. They are stored as a tuple of strings at the
@@ -421,6 +422,21 @@ Deprecated
  as appropriate to help identify code which needs updating during
  this transition.
 
+* The various ``load_module()`` methods of :mod:`importlib` have been
+ documented as deprecated since Python 3.6, but will now also trigger
+ a :exc:`DeprecationWarning`. Use
+:meth:`~importlib.abc.Loader.exec_module` instead.
+ (Contributed by Brett Cannon in :issue:`26131`.)
+
+* :meth:`zimport.zipimporter.load_module` has been deprecated in
+ preference for :meth:`~zipimport.zipimporter.exec_module`.
+ (Contributed by Brett Cannon in :issue:`26131`.)
+
+* The use of :meth:`~importlib.abc.Loader.load_module` by the import
+ system now triggers an :exc:`ImportWarning` as
+:meth:`~importlib.abc.Loader.exec_module` is preferred.
+ (Contributed by Brett Cannon in :issue:`26131`.)
+
 * ``sqlite3.OptimizedUnicode`` has been undocumented and obsolete since Python
  3.3, when it was made an alias to :class:`str`. It is now deprecated,
  scheduled for removal in Python 3.12.

Lib/importlib/_abc.py

@@ -35,6 +35,7 @@ def load_module(self, fullname):
  """
 ifnothasattr(self, 'exec_module'):
 raiseImportError
+# Warning implemented in _load_module_shim().
 return_bootstrap._load_module_shim(self, fullname)
 
 defmodule_repr(self, module):

Lib/importlib/_bootstrap.py

@@ -20,6 +20,12 @@
 # reference any injected objects! This includes not only global code but also
 # anything specified at the class level.
 
+def_object_name(obj):
+try:
+returnobj.__qualname__
+exceptAttributeError:
+returntype(obj).__qualname__
+
 # Bootstrap-related code ######################################################
 
 # Modules injected manually by _setup()
@@ -272,6 +278,9 @@ def _load_module_shim(self, fullname):
  This method is deprecated. Use loader.exec_module instead.
 
  """
+msg= ("the load_module() method is deprecated and slated for removal in "
+"Python 3.12; use exec_module() instead")
+_warnings.warn(msg, DeprecationWarning)
 spec=spec_from_loader(fullname, self)
 iffullnameinsys.modules:
 module=sys.modules[fullname]
@@ -612,9 +621,9 @@ def _exec(spec, module):
 else:
 _init_module_attrs(spec, module, override=True)
 ifnothasattr(spec.loader, 'exec_module'):
-# (issue19713) Once BuiltinImporter and ExtensionFileLoader
-# have exec_module() implemented, we can add a deprecation
-# warning here.
+msg= (f"{_object_name(spec.loader)}.exec_module() not found; "
+"falling back to load_module()")
+_warnings.warn(msg, ImportWarning)
 spec.loader.load_module(name)
 else:
 spec.loader.exec_module(module)
@@ -627,9 +636,8 @@ def _exec(spec, module):
 
 
 def_load_backward_compatible(spec):
-# (issue19713) Once BuiltinImporter and ExtensionFileLoader
-# have exec_module() implemented, we can add a deprecation
-# warning here.
+# It is assumed that all callers have been warned about using load_module()
+# appropriately before calling this function.
 try:
 spec.loader.load_module(spec.name)
 except:
@@ -668,6 +676,9 @@ def _load_unlocked(spec):
 ifspec.loaderisnotNone:
 # Not a namespace package.
 ifnothasattr(spec.loader, 'exec_module'):
+msg= (f"{_object_name(spec.loader)}.exec_module() not found; "
+"falling back to load_module()")
+_warnings.warn(msg, ImportWarning)
 return_load_backward_compatible(spec)
 
 module=module_from_spec(spec)
@@ -851,6 +862,7 @@ def load_module(cls, fullname):
  This method is deprecated. Use exec_module() instead.
 
  """
+# Warning about deprecation implemented in _load_module_shim().
 return_load_module_shim(cls, fullname)
 
 @classmethod

Lib/importlib/_bootstrap_external.py

@@ -832,7 +832,8 @@ def exec_module(self, module):
 _bootstrap._call_with_frames_removed(exec, code, module.__dict__)
 
 defload_module(self, fullname):
-"""This module is deprecated."""
+"""This method is deprecated."""
+# Warning implemented in _load_module_shim().
 return_bootstrap._load_module_shim(self, fullname)
 
 
@@ -1007,7 +1008,7 @@ def load_module(self, fullname):
  """
 # The only reason for this method is for the name check.
 # Issue #14857: Avoid the zero-argument form of super so the implementation
-# of that form can be updated without breaking the frozen module
+# of that form can be updated without breaking the frozen module.
 returnsuper(FileLoader, self).load_module(fullname)
 
 @_check_name
@@ -1253,6 +1254,7 @@ def load_module(self, fullname):
 # The import system never calls this method.
 _bootstrap._verbose_message('namespace module loaded with path {!r}',
 self._path)
+# Warning implemented in _load_module_shim().
 return_bootstrap._load_module_shim(self, fullname)
 
 

Lib/test/test_importlib/builtin/test_loader.py

@@ -6,6 +6,7 @@
 importsys
 importtypes
 importunittest
+importwarnings
 
 @unittest.skipIf(util.BUILTINS.good_nameisNone, 'no reasonable builtin module')
 classLoaderTests(abc.LoaderTests):
@@ -24,7 +25,9 @@ def verify(self, module):
 self.assertIn(module.__name__, sys.modules)
 
 defload_module(self, name):
-returnself.machinery.BuiltinImporter.load_module(name)
+withwarnings.catch_warnings():
+warnings.simplefilter("ignore", DeprecationWarning)
+returnself.machinery.BuiltinImporter.load_module(name)
 
 deftest_module(self):
 # Common case.

Lib/test/test_importlib/extension/test_loader.py

@@ -1,3 +1,4 @@
+fromwarningsimportcatch_warnings
 from .. importabc
 from .. importutil
 
@@ -7,6 +8,7 @@
 importsys
 importtypes
 importunittest
+importwarnings
 importimportlib.util
 importimportlib
 fromtest.support.script_helperimportassert_python_failure
@@ -20,14 +22,18 @@ def setUp(self):
 util.EXTENSIONS.file_path)
 
 defload_module(self, fullname):
-returnself.loader.load_module(fullname)
+withwarnings.catch_warnings():
+warnings.simplefilter("ignore", DeprecationWarning)
+returnself.loader.load_module(fullname)
 
 deftest_load_module_API(self):
 # Test the default argument for load_module().
-self.loader.load_module()
-self.loader.load_module(None)
-withself.assertRaises(ImportError):
-self.load_module('XXX')
+withwarnings.catch_warnings():
+warnings.simplefilter("ignore", DeprecationWarning)
+self.loader.load_module()
+self.loader.load_module(None)
+withself.assertRaises(ImportError):
+self.load_module('XXX')
 
 deftest_equality(self):
 other=self.machinery.ExtensionFileLoader(util.EXTENSIONS.name,
@@ -94,6 +100,21 @@ def setUp(self):
 self.loader=self.machinery.ExtensionFileLoader(
 self.name, self.spec.origin)
 
+defload_module(self):
+'''Load the module from the test extension'''
+withwarnings.catch_warnings():
+warnings.simplefilter("ignore", DeprecationWarning)
+returnself.loader.load_module(self.name)
+
+defload_module_by_name(self, fullname):
+'''Load a module from the test extension by name'''
+origin=self.spec.origin
+loader=self.machinery.ExtensionFileLoader(fullname, origin)
+spec=importlib.util.spec_from_loader(fullname, loader)
+module=importlib.util.module_from_spec(spec)
+loader.exec_module(module)
+returnmodule
+
 # No extension module as __init__ available for testing.
 test_package=None
 
@@ -157,19 +178,6 @@ def test_try_registration(self):
 withself.assertRaises(SystemError):
 module.call_state_registration_func(2)
 
-defload_module(self):
-'''Load the module from the test extension'''
-returnself.loader.load_module(self.name)
-
-defload_module_by_name(self, fullname):
-'''Load a module from the test extension by name'''
-origin=self.spec.origin
-loader=self.machinery.ExtensionFileLoader(fullname, origin)
-spec=importlib.util.spec_from_loader(fullname, loader)
-module=importlib.util.module_from_spec(spec)
-loader.exec_module(module)
-returnmodule
-
 deftest_load_submodule(self):
 '''Test loading a simulated submodule'''
 module=self.load_module_by_name('pkg.'+self.name)

Lib/test/test_importlib/frozen/test_loader.py

@@ -161,19 +161,23 @@ def test_module_repr(self):
 "<module '__hello__' (frozen)>")
 
 deftest_module_repr_indirect(self):
-withutil.uncache('__hello__'), captured_stdout():
-module=self.machinery.FrozenImporter.load_module('__hello__')
-self.assertEqual(repr(module),
-"<module '__hello__' (frozen)>")
+withwarnings.catch_warnings():
+warnings.simplefilter("ignore", DeprecationWarning)
+withutil.uncache('__hello__'), captured_stdout():
+module=self.machinery.FrozenImporter.load_module('__hello__')
+self.assertEqual(repr(module),
+"<module '__hello__' (frozen)>")
 
 # No way to trigger an error in a frozen module.
 test_state_after_failure=None
 
 deftest_unloadable(self):
-assertself.machinery.FrozenImporter.find_module('_not_real') isNone
-withself.assertRaises(ImportError) ascm:
-self.machinery.FrozenImporter.load_module('_not_real')
-self.assertEqual(cm.exception.name, '_not_real')
+withwarnings.catch_warnings():
+warnings.simplefilter("ignore", DeprecationWarning)
+assertself.machinery.FrozenImporter.find_module('_not_real') isNone
+withself.assertRaises(ImportError) ascm:
+self.machinery.FrozenImporter.load_module('_not_real')
+self.assertEqual(cm.exception.name, '_not_real')
 
 
 (Frozen_LoaderTests,

Lib/test/test_importlib/import_/test___loader__.py

@@ -2,6 +2,7 @@
 importsys
 importtypes
 importunittest
+importwarnings
 
 from .. importutil
 
@@ -45,25 +46,29 @@ def load_module(self, fullname):
 classLoaderAttributeTests:
 
 deftest___loader___missing(self):
-module=types.ModuleType('blah')
-try:
-delmodule.__loader__
-exceptAttributeError:
-pass
-loader=LoaderMock()
-loader.module=module
-withutil.uncache('blah'), util.import_state(meta_path=[loader]):
-module=self.__import__('blah')
-self.assertEqual(loader, module.__loader__)
+withwarnings.catch_warnings():
+warnings.simplefilter("ignore", ImportWarning)
+module=types.ModuleType('blah')
+try:
+delmodule.__loader__
+exceptAttributeError:
+pass
+loader=LoaderMock()
+loader.module=module
+withutil.uncache('blah'), util.import_state(meta_path=[loader]):
+module=self.__import__('blah')
+self.assertEqual(loader, module.__loader__)
 
 deftest___loader___is_None(self):
-module=types.ModuleType('blah')
-module.__loader__=None
-loader=LoaderMock()
-loader.module=module
-withutil.uncache('blah'), util.import_state(meta_path=[loader]):
-returned_module=self.__import__('blah')
-self.assertEqual(loader, module.__loader__)
+withwarnings.catch_warnings():
+warnings.simplefilter("ignore", ImportWarning)
+module=types.ModuleType('blah')
+module.__loader__=None
+loader=LoaderMock()
+loader.module=module
+withutil.uncache('blah'), util.import_state(meta_path=[loader]):
+returned_module=self.__import__('blah')
+self.assertEqual(loader, module.__loader__)
 
 
 (Frozen_Tests,

Lib/test/test_importlib/import_/test___package__.py

@@ -98,6 +98,16 @@ def __init__(self, parent):
 classUsing__package__PEP302(Using__package__):
 mock_modules=util.mock_modules
 
+deftest_using___package__(self):
+withwarnings.catch_warnings():
+warnings.simplefilter("ignore", ImportWarning)
+super().test_using___package__()
+
+deftest_spec_fallback(self):
+withwarnings.catch_warnings():
+warnings.simplefilter("ignore", ImportWarning)
+super().test_spec_fallback()
+
 
 (Frozen_UsingPackagePEP302,
 Source_UsingPackagePEP302
@@ -155,6 +165,21 @@ def test_submodule(self):
 classSetting__package__PEP302(Setting__package__, unittest.TestCase):
 mock_modules=util.mock_modules
 
+deftest_top_level(self):
+withwarnings.catch_warnings():
+warnings.simplefilter("ignore", ImportWarning)
+super().test_top_level()
+
+deftest_package(self):
+withwarnings.catch_warnings():
+warnings.simplefilter("ignore", ImportWarning)
+super().test_package()
+
+deftest_submodule(self):
+withwarnings.catch_warnings():
+warnings.simplefilter("ignore", ImportWarning)
+super().test_submodule()
+
 classSetting__package__PEP451(Setting__package__, unittest.TestCase):
 mock_modules=util.mock_spec