From 51e88986b041f291e2e71e68762a94e8f8f4dd53 Mon Sep 17 00:00:00 2001
From: Matthias Bussonnier <bussonniermatthias@gmail.com>
Date: Sat, 11 Feb 2017 16:06:25 -0800
Subject: [PATCH] Improve some deprecations in the importlib

Add the python version since the functionality is deprecated,
and raise a couple of deprecation warnings in a few places.

Theses functions are marked as deprecated in the documentation, but
especially in existing codebase, programmers tends to not re-check
whether functions are deprecated. So trigger the warning when possible.

It's also more probable that a developer will drop deprecated
functionality if we immediately give them information about
replacement API, and not have them to go find it in the documentation.

Include deprecation information in DocString as well as many tools pull
documentation from there and not from docs.python.org.

Add test making sure `find_loader()` and `find_module()` Both emit a
deprecation warning.
---
 Lib/importlib/__init__.py           |  3 ++-
 Lib/importlib/abc.py                | 25 +++++++++++++++++++------
 Lib/test/test_importlib/test_abc.py |  6 ++++++
 3 files changed, 27 insertions(+), 7 deletions(-)

diff --git a/Lib/importlib/__init__.py b/Lib/importlib/__init__.py
index b6a9f82e05f268..f87e20e4045dc3 100644
--- a/Lib/importlib/__init__.py
+++ b/Lib/importlib/__init__.py
@@ -79,7 +79,8 @@ def find_loader(name, path=None):
     This function is deprecated in favor of importlib.util.find_spec().
 
     """
-    warnings.warn('Use importlib.util.find_spec() instead.',
+    warnings.warn('Deprecated since Python 3.4. '
+                  'Use importlib.util.find_spec() instead.',
                   DeprecationWarning, stacklevel=2)
     try:
         loader = sys.modules[name].__loader__
diff --git a/Lib/importlib/abc.py b/Lib/importlib/abc.py
index daff681e69689f..661bd76e077f74 100644
--- a/Lib/importlib/abc.py
+++ b/Lib/importlib/abc.py
@@ -13,6 +13,7 @@
 except ImportError as exc:
     _frozen_importlib_external = _bootstrap_external
 import abc
+import warnings
 
 
 def _register(abstract_cls, *classes):
@@ -34,6 +35,8 @@ class Finder(metaclass=abc.ABCMeta):
     reimplementations of the import system.  Otherwise, finder
     implementations should derive from the more specific MetaPathFinder
     or PathEntryFinder ABCs.
+
+    Deprecated since Python 3.3
     """
 
     @abc.abstractmethod
@@ -57,11 +60,16 @@ def find_module(self, fullname, path):
         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(). If find_spec()
-        exists then backwards-compatible functionality is provided for this
-        method.
+        This method is deprecated since Python 3.4 in favor of
+        finder.find_spec(). If find_spec() exists then backwards-compatible
+        functionality is provided for this method.
 
         """
+        warnings.warn("MetaPathFinder.find_module() is deprecated since Python "
+                      "3.4 in favor of MetaPathFinder.find_spec()"
+                      "(available since 3.4)",
+                      DeprecationWarning,
+                      stacklevel=2)
         if not hasattr(self, 'find_spec'):
             return None
         found = self.find_spec(fullname, path)
@@ -94,10 +102,15 @@ def find_loader(self, fullname):
         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(). If find_spec()
-        is provided than backwards-compatible functionality is provided.
-
+        This method is deprecated since Python 3.4 in favor of
+        finder.find_spec(). If find_spec() is provided than backwards-compatible
+        functionality is provided.
         """
+        warnings.warn("PathEntryFinder.find_loader() is deprecated since Python "
+                      "3.4 in favor of PathEntryFinder.find_spec() "
+                      "(available since 3.4)",
+                      DeprecationWarning,
+                      stacklevel=2)
         if not hasattr(self, 'find_spec'):
             return None, []
         found = self.find_spec(fullname)
diff --git a/Lib/test/test_importlib/test_abc.py b/Lib/test/test_importlib/test_abc.py
index 4c090f32de3011..db36204e3b4e79 100644
--- a/Lib/test/test_importlib/test_abc.py
+++ b/Lib/test/test_importlib/test_abc.py
@@ -163,6 +163,9 @@ def test_invalidate_caches(self):
         # Calling the method is a no-op.
         self.ins.invalidate_caches()
 
+    def test_find_module_warns(self):
+        with self.assertWarns(DeprecationWarning):
+            self.ins.find_module('something', None)
 
 (Frozen_MPFDefaultTests,
  Source_MPFDefaultTests
@@ -189,6 +192,9 @@ def test_invalidate_caches(self):
         # Should be a no-op.
         self.ins.invalidate_caches()
 
+    def test_find_loader_warns(self):
+        with self.assertWarns(DeprecationWarning):
+            self.ins.find_loader('something')
 
 (Frozen_PEFDefaultTests,
  Source_PEFDefaultTests