Issue 19713: Add PEP 451-related deprecations.

1 files changed, 99 insertions, 25 deletions

diff --git a/Lib/importlib/_bootstrap.py b/Lib/importlib/_bootstrap.py
index 98ecc66..a9d4885 100644
--- a/Lib/importlib/_bootstrap.py
+++ b/Lib/importlib/_bootstrap.py
@@ -564,7 +564,11 @@ def _requires_frozen(fxn):
 
 def _find_module_shim(self, fullname):
     """Try to find a loader for the specified module by delegating to
-    self.find_loader()."""
+    self.find_loader().
+
+    This method is deprecated in favor of finder.find_spec().
+
+    """
     # Call find_loader(). If it returns a string (indicating this
     # is a namespace package portion), generate a warning and
     # return None.
@@ -576,8 +580,11 @@ def _find_module_shim(self, fullname):
 
 
 def _load_module_shim(self, fullname):
-    """Load the specified module into sys.modules and return it."""
-    # XXX Deprecation Warning here...
+    """Load the specified module into sys.modules and return it.
+
+    This method is deprecated.  Use loader.exec_module instead.
+
+    """
     spec = spec_from_loader(fullname, self)
     methods = _SpecMethods(spec)
     if fullname in sys.modules:
@@ -683,7 +690,9 @@ def _module_repr(module):
     # The implementation of ModuleType__repr__().
     loader = getattr(module, '__loader__', None)
     if hasattr(loader, 'module_repr'):
-        # XXX Deprecation Warning here...
+        # As soon as BuiltinImporter, FrozenImporter, and NamespaceLoader
+        # drop their implementations for module_repr. we can add a
+        # deprecation warning here.
         try:
             return loader.module_repr(module)
         except Exception:
@@ -1149,17 +1158,27 @@ class _SpecMethods:
                 return module
             self.init_module_attrs(module, _override=True)
             if not hasattr(self.spec.loader, 'exec_module'):
-                # XXX DeprecationWarning goes here...
+                # (issue19713) Once BuiltinImporter and ExtensionFileLoader
+                # have exec_module() implemented, we can add a deprecation
+                # warning here.
                 self.spec.loader.load_module(name)
             else:
                 self._exec(module)
         return sys.modules[name]
 
     def _load_backward_compatible(self):
-        # XXX DeprecationWarning goes here...
+        # (issue19713) Once BuiltinImporter and ExtensionFileLoader
+        # have exec_module() implemented, we can add a deprecation
+        # warning here.
         spec = self.spec
         # The module must be in sys.modules!
-        spec.loader.load_module(spec.name)
+        try:
+            _warnings
+        except NameError:
+            # We must be importing builtins in setup().
+            spec.loader.load_module(spec.name)
+        else:
+            spec.loader.load_module(spec.name)
         module = sys.modules[spec.name]
         if getattr(module, '__loader__', None) is None:
             try:
@@ -1233,7 +1252,11 @@ class BuiltinImporter:
 
     @staticmethod
     def module_repr(module):
-        # XXX deprecate
+        """Return repr for the module.
+
+        The method is deprecated.  The import machinery does the job itself.
+
+        """
         return '<module {!r} (built-in)>'.format(module.__name__)
 
     @classmethod
@@ -1251,6 +1274,8 @@ class BuiltinImporter:
 
         If 'path' is ever specified then the search is considered a failure.
 
+        This method is deprecated.  Use find_spec() instead.
+
         """
         spec = cls.find_spec(fullname, path)
         return spec.loader if spec is not None else None
@@ -1259,6 +1284,8 @@ class BuiltinImporter:
     @_requires_builtin
     def load_module(cls, fullname):
         """Load a built-in module."""
+        # Once an exec_module() implementation is added we can also
+        # add a deprecation warning here.
         with _ManageReload(fullname):
             module = _call_with_frames_removed(_imp.init_builtin, fullname)
         module.__loader__ = cls
@@ -1281,7 +1308,6 @@ class BuiltinImporter:
     @_requires_builtin
     def is_package(cls, fullname):
         """Return False as built-in modules are never packages."""
-        # XXX DeprecationWarning here...
         return False
 
 
@@ -1296,7 +1322,11 @@ class FrozenImporter:
 
     @staticmethod
     def module_repr(m):
-        # XXX deprecate
+        """Return repr for the module.
+
+        The method is deprecated.  The import machinery does the job itself.
+
+        """
         return '<module {!r} (frozen)>'.format(m.__name__)
 
     @classmethod
@@ -1308,7 +1338,11 @@ class FrozenImporter:
 
     @classmethod
     def find_module(cls, fullname, path=None):
-        """Find a frozen module."""
+        """Find a frozen module.
+
+        This method is deprecated.  Use find_spec() instead.
+
+        """
         return cls if _imp.is_frozen(fullname) else None
 
     @staticmethod
@@ -1322,7 +1356,11 @@ class FrozenImporter:
 
     @classmethod
     def load_module(cls, fullname):
-        """Load a frozen module."""
+        """Load a frozen module.
+
+        This method is deprecated.  Use exec_module() instead.
+
+        """
         return _load_module_shim(cls, fullname)
 
     @classmethod
@@ -1395,7 +1433,11 @@ class WindowsRegistryFinder:
 
     @classmethod
     def find_module(cls, fullname, path=None):
-        """Find module named in the registry."""
+        """Find module named in the registry.
+
+        This method is deprecated.  Use exec_module() instead.
+
+        """
         spec = cls.find_spec(fullname, path)
         if spec is not None:
             return spec.loader
@@ -1408,7 +1450,6 @@ class _LoaderBasics:
     """Base class of common code needed by both SourceLoader and
     SourcelessFileLoader."""
 
-    # XXX deprecate?
     def is_package(self, fullname):
         """Concrete implementation of InspectLoader.is_package by checking if
         the path returned by get_filename has a filename of '__init__.py'."""
@@ -1558,9 +1599,12 @@ class FileLoader:
 
     @_check_name
     def load_module(self, fullname):
-        """Load a module from a file."""
-        # The only reason for this method is for the name check.
+        """Load a module from a file.
 
+        This method is deprecated.  Use exec_module() instead.
+
+        """
+        # 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
         return super(FileLoader, self).load_module(fullname)
@@ -1660,6 +1704,8 @@ class ExtensionFileLoader:
     @_check_name
     def load_module(self, fullname):
         """Load an extension module."""
+        # Once an exec_module() implementation is added we can also
+        # add a deprecation warning here.
         with _ManageReload(fullname):
             module = _call_with_frames_removed(_imp.load_dynamic,
                                                fullname, self.path)
@@ -1754,9 +1800,13 @@ class _NamespaceLoader:
     def __init__(self, name, path, path_finder):
         self._path = _NamespacePath(name, path, path_finder)
 
-    # XXX Deprecate
     @classmethod
     def module_repr(cls, module):
+        """Return repr for the module.
+
+        The method is deprecated.  The import machinery does the job itself.
+
+        """
         return '<module {!r} (namespace)>'.format(module.__name__)
 
     def is_package(self, fullname):
@@ -1768,9 +1818,16 @@ class _NamespaceLoader:
     def get_code(self, fullname):
         return compile('', '<string>', 'exec', dont_inherit=True)
 
-    # XXX Deprecate
+    def exec_module(self, module):
+        pass
+
     def load_module(self, fullname):
-        """Load a namespace module."""
+        """Load a namespace module.
+
+        This method is deprecated.  Use exec_module() instead.
+
+        """
+        # The import system never calls this method.
         _verbose_message('namespace module loaded with path {!r}', self._path)
         return _load_module_shim(self, fullname)
 
@@ -1825,6 +1882,8 @@ class PathFinder:
 
     @classmethod
     def _legacy_get_spec(cls, fullname, finder):
+        # This would be a good place for a DeprecationWarning if
+        # we ended up going that route.
         if hasattr(finder, 'find_loader'):
             loader, portions = finder.find_loader(fullname)
         else:
@@ -1893,8 +1952,11 @@ class PathFinder:
     @classmethod
     def find_module(cls, fullname, path=None):
         """find the module on sys.path or 'path' based on sys.path_hooks and
-        sys.path_importer_cache."""
-        # XXX Deprecation warning here.
+        sys.path_importer_cache.
+
+        This method is deprecated.  Use find_spec() instead.
+
+        """
         spec = cls.find_spec(fullname, path)
         if spec is None:
             return None
@@ -1932,7 +1994,11 @@ class FileFinder:
 
     def find_loader(self, fullname):
         """Try to find a loader for the specified module, or the namespace
-        package portions. Returns (loader, list-of-portions)."""
+        package portions. Returns (loader, list-of-portions).
+
+        This method is deprecated.  Use find_spec() instead.
+
+        """
         spec = self.find_spec(fullname)
         if spec is None:
             return None, []
@@ -2065,6 +2131,15 @@ def _resolve_name(name, package, level):
     return '{}.{}'.format(base, name) if name else base
 
 
+def _find_spec_legacy(finder, name, path):
+    # This would be a good place for a DeprecationWarning if
+    # we ended up going that route.
+    loader = finder.find_module(name, path)
+    if loader is None:
+        return None
+    return spec_from_loader(name, loader)
+
+
 def _find_spec(name, path, target=None):
     """Find a module's loader."""
     if not sys.meta_path:
@@ -2078,10 +2153,9 @@ def _find_spec(name, path, target=None):
             try:
                 find_spec = finder.find_spec
             except AttributeError:
-                loader = finder.find_module(name, path)
-                if loader is None:
+                spec = _find_spec_legacy(finder, name, path)
+                if spec is None:
                     continue
-                spec = spec_from_loader(name, loader)
             else:
                 spec = find_spec(name, path, target)
         if spec is not None: