Issue 19713: Add PEP 451-related deprecations.

4 files changed, 127 insertions, 36 deletions

diff --git a/Lib/importlib/__init__.py b/Lib/importlib/__init__.py
index a4b1f55..c66e46c 100644
--- a/Lib/importlib/__init__.py
+++ b/Lib/importlib/__init__.py
@@ -12,6 +12,7 @@ __all__ = ['__import__', 'import_module', 'invalidate_caches', 'reload']
 import _imp  # Just the builtin component, NOT the full Python module
 import sys
 import types
+import warnings
 
 try:
     import _frozen_importlib as _bootstrap
@@ -77,13 +78,16 @@ def find_spec(name, path=None):
             return spec
 
 
-# XXX Deprecate...
 def find_loader(name, path=None):
     """Return the loader for the specified module.
 
     This is a backward-compatible wrapper around find_spec().
 
+    This function is deprecated in favor of importlib.find_spec().
+
     """
+    warnings.warn('Use importlib.find_spec() instead.', DeprecationWarning,
+                  stacklevel=2)
     try:
         loader = sys.modules[name].__loader__
         if loader is None:
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:
diff --git a/Lib/importlib/abc.py b/Lib/importlib/abc.py
index 3995ff2..584a41b 100644
--- a/Lib/importlib/abc.py
+++ b/Lib/importlib/abc.py
@@ -43,13 +43,14 @@ class MetaPathFinder(Finder):
     # We don't define find_spec() here since that would break
     # hasattr checks we do to support backward compatibility.
 
-    # XXX Deprecate
     def find_module(self, fullname, path):
         """Return a loader for the module.
 
         If no module is found, return None.  The fullname is a str and
         the path is a list of strings or None.
 
+        This method is deprecated in favor of finder.find_spec().
+
         """
         return None
 
@@ -69,7 +70,6 @@ class PathEntryFinder(Finder):
     # We don't define find_spec() here since that would break
     # hasattr checks we do to support backward compatibility.
 
-    # XXX Deprecate.
     def find_loader(self, fullname):
         """Return (loader, namespace portion) for the path entry.
 
@@ -81,10 +81,11 @@ class PathEntryFinder(Finder):
         The portion will be discarded if another path entry finder
         locates the module as a normal module or package.
 
+        This method is deprecated in favor of finder.find_spec().
+
         """
         return None, []
 
-    # XXX Deprecate.
     find_module = _bootstrap._find_module_shim
 
     def invalidate_caches(self):
@@ -115,7 +116,6 @@ class Loader(metaclass=abc.ABCMeta):
     # We don't define exec_module() here since that would break
     # hasattr checks we do to support backward compatibility.
 
-    # XXX Deprecate.
     def load_module(self, fullname):
         """Return the loaded module.
 
@@ -124,16 +124,19 @@ class Loader(metaclass=abc.ABCMeta):
 
         ImportError is raised on failure.
 
+        This method is deprecated in favor of loader.exec_module().
+
         """
         raise ImportError
 
-    # XXX Deprecate.
     def module_repr(self, module):
         """Return a module's repr.
 
         Used by the module type when the method does not raise
         NotImplementedError.
 
+        This method is deprecated.
+
         """
         # The exception will cause ModuleType.__repr__ to ignore this method.
         raise NotImplementedError
diff --git a/Lib/importlib/util.py b/Lib/importlib/util.py
index 04b1951..42fc9ea 100644
--- a/Lib/importlib/util.py
+++ b/Lib/importlib/util.py
@@ -55,11 +55,16 @@ def _module_to_load(name):
         module.__initializing__ = False
 
 
-# XXX deprecate
 def set_package(fxn):
-    """Set __package__ on the returned module."""
+    """Set __package__ on the returned module.
+
+    This function is deprecated.
+
+    """
     @functools.wraps(fxn)
     def set_package_wrapper(*args, **kwargs):
+        warnings.warn('The import system now takes care of this automatically.',
+                      DeprecationWarning, stacklevel=2)
         module = fxn(*args, **kwargs)
         if getattr(module, '__package__', None) is None:
             module.__package__ = module.__name__
@@ -69,11 +74,16 @@ def set_package(fxn):
     return set_package_wrapper
 
 
-# XXX deprecate
 def set_loader(fxn):
-    """Set __loader__ on the returned module."""
+    """Set __loader__ on the returned module.
+
+    This function is deprecated.
+
+    """
     @functools.wraps(fxn)
     def set_loader_wrapper(self, *args, **kwargs):
+        warnings.warn('The import system now takes care of this automatically.',
+                      DeprecationWarning, stacklevel=2)
         module = fxn(self, *args, **kwargs)
         if getattr(module, '__loader__', None) is None:
             module.__loader__ = self
@@ -100,7 +110,7 @@ def module_for_loader(fxn):
 
     """
     warnings.warn('The import system now takes care of this automatically.',
-                  PendingDeprecationWarning, stacklevel=2)
+                  DeprecationWarning, stacklevel=2)
     @functools.wraps(fxn)
     def module_for_loader_wrapper(self, fullname, *args, **kwargs):
         with _module_to_load(fullname) as module: