bpo-45514: Deprecate importlib resources legacy functions. (GH-29036)

* bpo-45514: Apply changes from importlib_resources@a3ef4128c6

* Mark legacy functions as deprecated in the docs and link to the migration docs in importlib_resources docs.

* Apply changes from importlib_resources@329ae9d5f2c.

* Indicate importlib.resources as a module.

Co-authored-by: Filipe Laíns <lains@riseup.net>

6 files changed, 144 insertions, 81 deletions

diff --git a/Lib/test/test_importlib/resources/util.py b/Lib/test/test_importlib/resources/util.py
index d7a049b..7192632 100644
--- a/Lib/test/test_importlib/resources/util.py
+++ b/Lib/test/test_importlib/resources/util.py
@@ -1,8 +1,10 @@
 import abc
+import contextlib
 import importlib
 import io
 import sys
 import types
+import warnings
 from pathlib import Path, PurePath
 
 from .. import data01
@@ -67,6 +69,13 @@ def create_package(file=None, path=None, is_package=True, contents=()):
     )
 
 
+@contextlib.contextmanager
+def suppress_known_deprecation():
+    with warnings.catch_warnings(record=True) as ctx:
+        warnings.simplefilter('default', category=DeprecationWarning)
+        yield ctx
+
+
 class CommonTests(metaclass=abc.ABCMeta):
     """
     Tests shared by test_open, test_path, and test_read.
diff --git a/Lib/test/test_importlib/test_contents.py b/Lib/test/test_importlib/test_contents.py
index 0f3aa84..575dcd2 100644
--- a/Lib/test/test_importlib/test_contents.py
+++ b/Lib/test/test_importlib/test_contents.py
@@ -15,7 +15,8 @@ class ContentsTests:
     }
 
     def test_contents(self):
-        assert self.expected <= set(resources.contents(self.data))
+        with util.suppress_known_deprecation():
+            assert self.expected <= set(resources.contents(self.data))
 
 
 class ContentsDiskTests(ContentsTests, unittest.TestCase):
diff --git a/Lib/test/test_importlib/test_open.py b/Lib/test/test_importlib/test_open.py
index 6f88ff7..a9c4a70 100644
--- a/Lib/test/test_importlib/test_open.py
+++ b/Lib/test/test_importlib/test_open.py
@@ -7,38 +7,47 @@ from .resources import util
 
 class CommonBinaryTests(util.CommonTests, unittest.TestCase):
     def execute(self, package, path):
-        with resources.open_binary(package, path):
-            pass
+        with util.suppress_known_deprecation():
+            with resources.open_binary(package, path):
+                pass
 
 
 class CommonTextTests(util.CommonTests, unittest.TestCase):
     def execute(self, package, path):
-        with resources.open_text(package, path):
-            pass
+        with util.suppress_known_deprecation():
+            with resources.open_text(package, path):
+                pass
 
 
 class OpenTests:
     def test_open_binary(self):
-        with resources.open_binary(self.data, 'binary.file') as fp:
-            result = fp.read()
-            self.assertEqual(result, b'\x00\x01\x02\x03')
+        with util.suppress_known_deprecation():
+            with resources.open_binary(self.data, 'binary.file') as fp:
+                result = fp.read()
+                self.assertEqual(result, b'\x00\x01\x02\x03')
 
     def test_open_text_default_encoding(self):
-        with resources.open_text(self.data, 'utf-8.file') as fp:
-            result = fp.read()
+        with util.suppress_known_deprecation():
+            with resources.open_text(self.data, 'utf-8.file') as fp:
+                result = fp.read()
             self.assertEqual(result, 'Hello, UTF-8 world!\n')
 
     def test_open_text_given_encoding(self):
-        with resources.open_text(self.data, 'utf-16.file', 'utf-16', 'strict') as fp:
-            result = fp.read()
+        with util.suppress_known_deprecation():
+            with resources.open_text(
+                self.data, 'utf-16.file', 'utf-16', 'strict'
+            ) as fp:
+                result = fp.read()
         self.assertEqual(result, 'Hello, UTF-16 world!\n')
 
     def test_open_text_with_errors(self):
         # Raises UnicodeError without the 'errors' argument.
-        with resources.open_text(self.data, 'utf-16.file', 'utf-8', 'strict') as fp:
-            self.assertRaises(UnicodeError, fp.read)
-        with resources.open_text(self.data, 'utf-16.file', 'utf-8', 'ignore') as fp:
-            result = fp.read()
+        with util.suppress_known_deprecation():
+            with resources.open_text(self.data, 'utf-16.file', 'utf-8', 'strict') as fp:
+                self.assertRaises(UnicodeError, fp.read)
+        with util.suppress_known_deprecation():
+            with resources.open_text(self.data, 'utf-16.file', 'utf-8', 'ignore') as fp:
+                result = fp.read()
         self.assertEqual(
             result,
             'H\x00e\x00l\x00l\x00o\x00,\x00 '
@@ -47,14 +56,16 @@ class OpenTests:
         )
 
     def test_open_binary_FileNotFoundError(self):
-        self.assertRaises(
-            FileNotFoundError, resources.open_binary, self.data, 'does-not-exist'
-        )
+        with util.suppress_known_deprecation():
+            self.assertRaises(
+                FileNotFoundError, resources.open_binary, self.data, 'does-not-exist'
+            )
 
     def test_open_text_FileNotFoundError(self):
-        self.assertRaises(
-            FileNotFoundError, resources.open_text, self.data, 'does-not-exist'
-        )
+        with util.suppress_known_deprecation():
+            self.assertRaises(
+                FileNotFoundError, resources.open_text, self.data, 'does-not-exist'
+            )
 
 
 class OpenDiskTests(OpenTests, unittest.TestCase):
diff --git a/Lib/test/test_importlib/test_path.py b/Lib/test/test_importlib/test_path.py
index 4436d7f..3ccbc6f 100644
--- a/Lib/test/test_importlib/test_path.py
+++ b/Lib/test/test_importlib/test_path.py
@@ -8,8 +8,9 @@ from .resources import util
 
 class CommonTests(util.CommonTests, unittest.TestCase):
     def execute(self, package, path):
-        with resources.path(package, path):
-            pass
+        with util.suppress_known_deprecation():
+            with resources.path(package, path):
+                pass
 
 
 class PathTests:
@@ -17,12 +18,13 @@ class PathTests:
         # Path should be readable.
         # Test also implicitly verifies the returned object is a pathlib.Path
         # instance.
-        with resources.path(self.data, 'utf-8.file') as path:
-            self.assertTrue(path.name.endswith("utf-8.file"), repr(path))
-            # pathlib.Path.read_text() was introduced in Python 3.5.
-            with path.open('r', encoding='utf-8') as file:
-                text = file.read()
-            self.assertEqual('Hello, UTF-8 world!\n', text)
+        with util.suppress_known_deprecation():
+            with resources.path(self.data, 'utf-8.file') as path:
+                self.assertTrue(path.name.endswith("utf-8.file"), repr(path))
+                # pathlib.Path.read_text() was introduced in Python 3.5.
+                with path.open('r', encoding='utf-8') as file:
+                    text = file.read()
+                self.assertEqual('Hello, UTF-8 world!\n', text)
 
 
 class PathDiskTests(PathTests, unittest.TestCase):
@@ -32,8 +34,9 @@ class PathDiskTests(PathTests, unittest.TestCase):
         # Guarantee the internal implementation detail that
         # file-system-backed resources do not get the tempdir
         # treatment.
-        with resources.path(self.data, 'utf-8.file') as path:
-            assert 'data' in str(path)
+        with util.suppress_known_deprecation():
+            with resources.path(self.data, 'utf-8.file') as path:
+                assert 'data' in str(path)
 
 
 class PathMemoryTests(PathTests, unittest.TestCase):
@@ -51,8 +54,9 @@ class PathZipTests(PathTests, util.ZipSetup, unittest.TestCase):
     def test_remove_in_context_manager(self):
         # It is not an error if the file that was temporarily stashed on the
         # file system is removed inside the `with` stanza.
-        with resources.path(self.data, 'utf-8.file') as path:
-            path.unlink()
+        with util.suppress_known_deprecation():
+            with resources.path(self.data, 'utf-8.file') as path:
+                path.unlink()
 
 
 if __name__ == '__main__':
diff --git a/Lib/test/test_importlib/test_read.py b/Lib/test/test_importlib/test_read.py
index 3579801..1bab5c9 100644
--- a/Lib/test/test_importlib/test_read.py
+++ b/Lib/test/test_importlib/test_read.py
@@ -7,31 +7,40 @@ from .resources import util
 
 class CommonBinaryTests(util.CommonTests, unittest.TestCase):
     def execute(self, package, path):
-        resources.read_binary(package, path)
+        with util.suppress_known_deprecation():
+            resources.read_binary(package, path)
 
 
 class CommonTextTests(util.CommonTests, unittest.TestCase):
     def execute(self, package, path):
-        resources.read_text(package, path)
+        with util.suppress_known_deprecation():
+            resources.read_text(package, path)
 
 
 class ReadTests:
     def test_read_binary(self):
-        result = resources.read_binary(self.data, 'binary.file')
+        with util.suppress_known_deprecation():
+            result = resources.read_binary(self.data, 'binary.file')
         self.assertEqual(result, b'\0\1\2\3')
 
     def test_read_text_default_encoding(self):
-        result = resources.read_text(self.data, 'utf-8.file')
+        with util.suppress_known_deprecation():
+            result = resources.read_text(self.data, 'utf-8.file')
         self.assertEqual(result, 'Hello, UTF-8 world!\n')
 
     def test_read_text_given_encoding(self):
-        result = resources.read_text(self.data, 'utf-16.file', encoding='utf-16')
+        with util.suppress_known_deprecation():
+            result = resources.read_text(self.data, 'utf-16.file', encoding='utf-16')
         self.assertEqual(result, 'Hello, UTF-16 world!\n')
 
     def test_read_text_with_errors(self):
         # Raises UnicodeError without the 'errors' argument.
-        self.assertRaises(UnicodeError, resources.read_text, self.data, 'utf-16.file')
-        result = resources.read_text(self.data, 'utf-16.file', errors='ignore')
+        with util.suppress_known_deprecation():
+            self.assertRaises(
+                UnicodeError, resources.read_text, self.data, 'utf-16.file'
+            )
+        with util.suppress_known_deprecation():
+            result = resources.read_text(self.data, 'utf-16.file', errors='ignore')
         self.assertEqual(
             result,
             'H\x00e\x00l\x00l\x00o\x00,\x00 '
@@ -47,11 +56,13 @@ class ReadDiskTests(ReadTests, unittest.TestCase):
 class ReadZipTests(ReadTests, util.ZipSetup, unittest.TestCase):
     def test_read_submodule_resource(self):
         submodule = import_module('ziptestdata.subdirectory')
-        result = resources.read_binary(submodule, 'binary.file')
+        with util.suppress_known_deprecation():
+            result = resources.read_binary(submodule, 'binary.file')
         self.assertEqual(result, b'\0\1\2\3')
 
     def test_read_submodule_resource_by_name(self):
-        result = resources.read_binary('ziptestdata.subdirectory', 'binary.file')
+        with util.suppress_known_deprecation():
+            result = resources.read_binary('ziptestdata.subdirectory', 'binary.file')
         self.assertEqual(result, b'\0\1\2\3')
 
 
diff --git a/Lib/test/test_importlib/test_resource.py b/Lib/test/test_importlib/test_resource.py
index 612bada..3990459 100644
--- a/Lib/test/test_importlib/test_resource.py
+++ b/Lib/test/test_importlib/test_resource.py
@@ -15,17 +15,21 @@ class ResourceTests:
     # Subclasses are expected to set the `data` attribute.
 
     def test_is_resource_good_path(self):
-        self.assertTrue(resources.is_resource(self.data, 'binary.file'))
+        with util.suppress_known_deprecation():
+            self.assertTrue(resources.is_resource(self.data, 'binary.file'))
 
     def test_is_resource_missing(self):
-        self.assertFalse(resources.is_resource(self.data, 'not-a-file'))
+        with util.suppress_known_deprecation():
+            self.assertFalse(resources.is_resource(self.data, 'not-a-file'))
 
     def test_is_resource_subresource_directory(self):
         # Directories are not resources.
-        self.assertFalse(resources.is_resource(self.data, 'subdirectory'))
+        with util.suppress_known_deprecation():
+            self.assertFalse(resources.is_resource(self.data, 'subdirectory'))
 
     def test_contents(self):
-        contents = set(resources.contents(self.data))
+        with util.suppress_known_deprecation():
+            contents = set(resources.contents(self.data))
         # There may be cruft in the directory listing of the data directory.
         # It could have a __pycache__ directory,
         # an artifact of the
@@ -58,25 +62,29 @@ class ResourceLoaderTests(unittest.TestCase):
         package = util.create_package(
             file=data01, path=data01.__file__, contents=['A', 'B', 'C']
         )
-        self.assertEqual(set(resources.contents(package)), {'A', 'B', 'C'})
+        with util.suppress_known_deprecation():
+            self.assertEqual(set(resources.contents(package)), {'A', 'B', 'C'})
 
     def test_resource_is_resource(self):
         package = util.create_package(
             file=data01, path=data01.__file__, contents=['A', 'B', 'C', 'D/E', 'D/F']
         )
-        self.assertTrue(resources.is_resource(package, 'B'))
+        with util.suppress_known_deprecation():
+            self.assertTrue(resources.is_resource(package, 'B'))
 
     def test_resource_directory_is_not_resource(self):
         package = util.create_package(
             file=data01, path=data01.__file__, contents=['A', 'B', 'C', 'D/E', 'D/F']
         )
-        self.assertFalse(resources.is_resource(package, 'D'))
+        with util.suppress_known_deprecation():
+            self.assertFalse(resources.is_resource(package, 'D'))
 
     def test_resource_missing_is_not_resource(self):
         package = util.create_package(
             file=data01, path=data01.__file__, contents=['A', 'B', 'C', 'D/E', 'D/F']
         )
-        self.assertFalse(resources.is_resource(package, 'Z'))
+        with util.suppress_known_deprecation():
+            self.assertFalse(resources.is_resource(package, 'Z'))
 
 
 class ResourceCornerCaseTests(unittest.TestCase):
@@ -94,7 +102,8 @@ class ResourceCornerCaseTests(unittest.TestCase):
         module.__file__ = '/path/which/shall/not/be/named'
         module.__spec__.loader = module.__loader__
         module.__spec__.origin = module.__file__
-        self.assertFalse(resources.is_resource(module, 'A'))
+        with util.suppress_known_deprecation():
+            self.assertFalse(resources.is_resource(module, 'A'))
 
 
 class ResourceFromZipsTest01(util.ZipSetupBase, unittest.TestCase):
@@ -102,24 +111,28 @@ class ResourceFromZipsTest01(util.ZipSetupBase, unittest.TestCase):
 
     def test_is_submodule_resource(self):
         submodule = import_module('ziptestdata.subdirectory')
-        self.assertTrue(resources.is_resource(submodule, 'binary.file'))
+        with util.suppress_known_deprecation():
+            self.assertTrue(resources.is_resource(submodule, 'binary.file'))
 
     def test_read_submodule_resource_by_name(self):
-        self.assertTrue(
-            resources.is_resource('ziptestdata.subdirectory', 'binary.file')
-        )
+        with util.suppress_known_deprecation():
+            self.assertTrue(
+                resources.is_resource('ziptestdata.subdirectory', 'binary.file')
+            )
 
     def test_submodule_contents(self):
         submodule = import_module('ziptestdata.subdirectory')
-        self.assertEqual(
-            set(resources.contents(submodule)), {'__init__.py', 'binary.file'}
-        )
+        with util.suppress_known_deprecation():
+            self.assertEqual(
+                set(resources.contents(submodule)), {'__init__.py', 'binary.file'}
+            )
 
     def test_submodule_contents_by_name(self):
-        self.assertEqual(
-            set(resources.contents('ziptestdata.subdirectory')),
-            {'__init__.py', 'binary.file'},
-        )
+        with util.suppress_known_deprecation():
+            self.assertEqual(
+                set(resources.contents('ziptestdata.subdirectory')),
+                {'__init__.py', 'binary.file'},
+            )
 
 
 class ResourceFromZipsTest02(util.ZipSetupBase, unittest.TestCase):
@@ -130,12 +143,16 @@ class ResourceFromZipsTest02(util.ZipSetupBase, unittest.TestCase):
         Test thata zip with two unrelated subpackages return
         distinct resources. Ref python/importlib_resources#44.
         """
-        self.assertEqual(
-            set(resources.contents('ziptestdata.one')), {'__init__.py', 'resource1.txt'}
-        )
-        self.assertEqual(
-            set(resources.contents('ziptestdata.two')), {'__init__.py', 'resource2.txt'}
-        )
+        with util.suppress_known_deprecation():
+            self.assertEqual(
+                set(resources.contents('ziptestdata.one')),
+                {'__init__.py', 'resource1.txt'},
+            )
+        with util.suppress_known_deprecation():
+            self.assertEqual(
+                set(resources.contents('ziptestdata.two')),
+                {'__init__.py', 'resource2.txt'},
+            )
 
 
 class DeletingZipsTest(unittest.TestCase):
@@ -176,17 +193,20 @@ class DeletingZipsTest(unittest.TestCase):
             pass
 
     def test_contents_does_not_keep_open(self):
-        c = resources.contents('ziptestdata')
+        with util.suppress_known_deprecation():
+            c = resources.contents('ziptestdata')
         self.zip_path.unlink()
         del c
 
     def test_is_resource_does_not_keep_open(self):
-        c = resources.is_resource('ziptestdata', 'binary.file')
+        with util.suppress_known_deprecation():
+            c = resources.is_resource('ziptestdata', 'binary.file')
         self.zip_path.unlink()
         del c
 
     def test_is_resource_failure_does_not_keep_open(self):
-        c = resources.is_resource('ziptestdata', 'not-present')
+        with util.suppress_known_deprecation():
+            c = resources.is_resource('ziptestdata', 'not-present')
         self.zip_path.unlink()
         del c
 
@@ -199,17 +219,20 @@ class DeletingZipsTest(unittest.TestCase):
     def test_entered_path_does_not_keep_open(self):
         # This is what certifi does on import to make its bundle
         # available for the process duration.
-        c = resources.path('ziptestdata', 'binary.file').__enter__()
+        with util.suppress_known_deprecation():
+            c = resources.path('ziptestdata', 'binary.file').__enter__()
         self.zip_path.unlink()
         del c
 
     def test_read_binary_does_not_keep_open(self):
-        c = resources.read_binary('ziptestdata', 'binary.file')
+        with util.suppress_known_deprecation():
+            c = resources.read_binary('ziptestdata', 'binary.file')
         self.zip_path.unlink()
         del c
 
     def test_read_text_does_not_keep_open(self):
-        c = resources.read_text('ziptestdata', 'utf-8.file', encoding='utf-8')
+        with util.suppress_known_deprecation():
+            c = resources.read_text('ziptestdata', 'utf-8.file', encoding='utf-8')
         self.zip_path.unlink()
         del c
 
@@ -226,15 +249,18 @@ class ResourceFromNamespaceTest01(unittest.TestCase):
         sys.path.remove(cls.site_dir)
 
     def test_is_submodule_resource(self):
-        self.assertTrue(
-            resources.is_resource(import_module('namespacedata01'), 'binary.file')
-        )
+        with util.suppress_known_deprecation():
+            self.assertTrue(
+                resources.is_resource(import_module('namespacedata01'), 'binary.file')
+            )
 
     def test_read_submodule_resource_by_name(self):
-        self.assertTrue(resources.is_resource('namespacedata01', 'binary.file'))
+        with util.suppress_known_deprecation():
+            self.assertTrue(resources.is_resource('namespacedata01', 'binary.file'))
 
     def test_submodule_contents(self):
-        contents = set(resources.contents(import_module('namespacedata01')))
+        with util.suppress_known_deprecation():
+            contents = set(resources.contents(import_module('namespacedata01')))
         try:
             contents.remove('__pycache__')
         except KeyError:
@@ -242,7 +268,8 @@ class ResourceFromNamespaceTest01(unittest.TestCase):
         self.assertEqual(contents, {'binary.file', 'utf-8.file', 'utf-16.file'})
 
     def test_submodule_contents_by_name(self):
-        contents = set(resources.contents('namespacedata01'))
+        with util.suppress_known_deprecation():
+            contents = set(resources.contents('namespacedata01'))
         try:
             contents.remove('__pycache__')
         except KeyError: