From 0ad6143b5c50b55396947bb6a9632e7578b93f8d Mon Sep 17 00:00:00 2001 From: "Jason R. Coombs" Date: Sun, 17 Oct 2021 17:41:17 -0400 Subject: [PATCH 1/6] Emit deprecation warning on legacy functions. --- importlib_resources/_legacy.py | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/importlib_resources/_legacy.py b/importlib_resources/_legacy.py index 2ddec5f9..a5d49e53 100644 --- a/importlib_resources/_legacy.py +++ b/importlib_resources/_legacy.py @@ -1,6 +1,8 @@ +import inspect import os import pathlib import types +import warnings from typing import Union, Iterable, ContextManager, BinaryIO, TextIO @@ -10,13 +12,24 @@ Resource = Union[str, os.PathLike] +def _warn(): + func = inspect.stack()[1].function + warnings.warn( + f"{func} is deprecated. Use files() instead.", + DeprecationWarning, + stacklevel=2, + ) + + def open_binary(package: Package, resource: Resource) -> BinaryIO: """Return a file-like object opened for binary reading of the resource.""" + _warn() return (_common.files(package) / _common.normalize_path(resource)).open('rb') def read_binary(package: Package, resource: Resource) -> bytes: """Return the binary contents of the resource.""" + _warn() return (_common.files(package) / _common.normalize_path(resource)).read_bytes() @@ -27,6 +40,7 @@ def open_text( errors: str = 'strict', ) -> TextIO: """Return a file-like object opened for text reading of the resource.""" + _warn() return (_common.files(package) / _common.normalize_path(resource)).open( 'r', encoding=encoding, errors=errors ) @@ -43,6 +57,7 @@ def read_text( The decoding-related arguments have the same semantics as those of bytes.decode(). """ + _warn() with open_text(package, resource, encoding, errors) as fp: return fp.read() @@ -54,6 +69,7 @@ def contents(package: Package) -> Iterable[str]: not considered resources. Use `is_resource()` on each entry returned here to check if it is a resource or not. """ + _warn() return [path.name for path in _common.files(package).iterdir()] @@ -62,6 +78,7 @@ def is_resource(package: Package, name: str) -> bool: Directories are *not* resources. """ + _warn() resource = _common.normalize_path(name) return any( traversable.name == resource and traversable.is_file() @@ -81,4 +98,5 @@ def path( raised if the file was deleted prior to the context manager exiting). """ + _warn() return _common.as_file(_common.files(package) / _common.normalize_path(resource)) From 6065e26c049c8323676bee166bd63f101c4f44c2 Mon Sep 17 00:00:00 2001 From: "Jason R. Coombs" Date: Sun, 17 Oct 2021 17:45:40 -0400 Subject: [PATCH 2/6] Re-implement deprecation as a decorator. --- importlib_resources/_legacy.py | 34 +++++++++++++++++++--------------- 1 file changed, 19 insertions(+), 15 deletions(-) diff --git a/importlib_resources/_legacy.py b/importlib_resources/_legacy.py index a5d49e53..7526d512 100644 --- a/importlib_resources/_legacy.py +++ b/importlib_resources/_legacy.py @@ -1,4 +1,4 @@ -import inspect +import functools import os import pathlib import types @@ -12,27 +12,32 @@ Resource = Union[str, os.PathLike] -def _warn(): - func = inspect.stack()[1].function - warnings.warn( - f"{func} is deprecated. Use files() instead.", - DeprecationWarning, - stacklevel=2, - ) +def deprecated(func): + @functools.wraps(func) + def wrapper(*args, **kwargs): + warnings.warn( + f"{func.__name__} is deprecated. Use files() instead.", + DeprecationWarning, + stacklevel=2, + ) + return func(*args, **kwargs) + + return wrapper +@deprecated def open_binary(package: Package, resource: Resource) -> BinaryIO: """Return a file-like object opened for binary reading of the resource.""" - _warn() return (_common.files(package) / _common.normalize_path(resource)).open('rb') +@deprecated def read_binary(package: Package, resource: Resource) -> bytes: """Return the binary contents of the resource.""" - _warn() return (_common.files(package) / _common.normalize_path(resource)).read_bytes() +@deprecated def open_text( package: Package, resource: Resource, @@ -40,12 +45,12 @@ def open_text( errors: str = 'strict', ) -> TextIO: """Return a file-like object opened for text reading of the resource.""" - _warn() return (_common.files(package) / _common.normalize_path(resource)).open( 'r', encoding=encoding, errors=errors ) +@deprecated def read_text( package: Package, resource: Resource, @@ -57,11 +62,11 @@ def read_text( The decoding-related arguments have the same semantics as those of bytes.decode(). """ - _warn() with open_text(package, resource, encoding, errors) as fp: return fp.read() +@deprecated def contents(package: Package) -> Iterable[str]: """Return an iterable of entries in `package`. @@ -69,16 +74,15 @@ def contents(package: Package) -> Iterable[str]: not considered resources. Use `is_resource()` on each entry returned here to check if it is a resource or not. """ - _warn() return [path.name for path in _common.files(package).iterdir()] +@deprecated def is_resource(package: Package, name: str) -> bool: """True if `name` is a resource inside `package`. Directories are *not* resources. """ - _warn() resource = _common.normalize_path(name) return any( traversable.name == resource and traversable.is_file() @@ -86,6 +90,7 @@ def is_resource(package: Package, name: str) -> bool: ) +@deprecated def path( package: Package, resource: Resource, @@ -98,5 +103,4 @@ def path( raised if the file was deleted prior to the context manager exiting). """ - _warn() return _common.as_file(_common.files(package) / _common.normalize_path(resource)) From 13d42b7ad1376649a45fa86f7baa35dc289aa9e3 Mon Sep 17 00:00:00 2001 From: "Jason R. Coombs" Date: Sun, 17 Oct 2021 17:51:08 -0400 Subject: [PATCH 3/6] Update changelog. --- CHANGES.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/CHANGES.rst b/CHANGES.rst index 859dbf18..bfe4f49f 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -1,3 +1,10 @@ +v5.3.0 +====== + +* #80: Now raise a ``DeprecationWarning`` for all legacy + functions. Instead, users should rely on the ``files()`` + API introduced in importlib_resources 1.3. + v5.2.3 ====== From fda6cb2423e839d0920c2bdafe977eef65309656 Mon Sep 17 00:00:00 2001 From: "Jason R. Coombs" Date: Sun, 17 Oct 2021 18:00:54 -0400 Subject: [PATCH 4/6] Acknowledge and suppress warnings --- importlib_resources/tests/test_contents.py | 3 +- importlib_resources/tests/test_open.py | 51 ++++++---- importlib_resources/tests/test_path.py | 28 +++--- importlib_resources/tests/test_read.py | 29 ++++-- importlib_resources/tests/test_resource.py | 103 +++++++++++++-------- importlib_resources/tests/util.py | 9 ++ 6 files changed, 143 insertions(+), 80 deletions(-) diff --git a/importlib_resources/tests/test_contents.py b/importlib_resources/tests/test_contents.py index 2af70607..c95e1a77 100644 --- a/importlib_resources/tests/test_contents.py +++ b/importlib_resources/tests/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/importlib_resources/tests/test_open.py b/importlib_resources/tests/test_open.py index 919fc0db..1c8a943a 100644 --- a/importlib_resources/tests/test_open.py +++ b/importlib_resources/tests/test_open.py @@ -7,38 +7,47 @@ 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, 'utf-8.file') as fp: - result = fp.read() + with util.suppress_known_deprecation(): + with resources.open_binary(self.data, 'utf-8.file') as fp: + result = fp.read() self.assertEqual(result, b'Hello, UTF-8 world!\n') 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 @@ def test_open_text_with_errors(self): ) 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/importlib_resources/tests/test_path.py b/importlib_resources/tests/test_path.py index 9180626f..af433ce0 100644 --- a/importlib_resources/tests/test_path.py +++ b/importlib_resources/tests/test_path.py @@ -8,8 +8,9 @@ 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 @@ def test_reading(self): # 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): @@ -34,8 +36,9 @@ def test_natural_path(self): 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): @@ -53,8 +56,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/importlib_resources/tests/test_read.py b/importlib_resources/tests/test_read.py index 2616fbf5..da7d2745 100644 --- a/importlib_resources/tests/test_read.py +++ b/importlib_resources/tests/test_read.py @@ -8,31 +8,40 @@ 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 ' @@ -48,11 +57,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/importlib_resources/tests/test_resource.py b/importlib_resources/tests/test_resource.py index 071cb8d4..9fcf6705 100644 --- a/importlib_resources/tests/test_resource.py +++ b/importlib_resources/tests/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 @@ def test_resource_contents(self): 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 @@ def test_package_has_no_reader_fallback(self): 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 @@ def test_unrelated_contents(self): 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 @@ def tearDown(self): 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 @@ def test_path_does_not_keep_open(self): 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 @@ def tearDownClass(cls): 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 @@ def test_submodule_contents(self): 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: diff --git a/importlib_resources/tests/util.py b/importlib_resources/tests/util.py index 6ac4332e..b578de9e 100644 --- a/importlib_resources/tests/util.py +++ b/importlib_resources/tests/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. From ed3b2d30e01121b27a6e0d0a8a478a483e437736 Mon Sep 17 00:00:00 2001 From: "Jason R. Coombs" Date: Sun, 17 Oct 2021 18:30:27 -0400 Subject: [PATCH 5/6] Add section to the docs guiding the user on how to migrate (relying on the _legacy module as a guide because it's so easy to read). --- CHANGES.rst | 4 +++- docs/using.rst | 15 +++++++++++++++ 2 files changed, 18 insertions(+), 1 deletion(-) diff --git a/CHANGES.rst b/CHANGES.rst index bfe4f49f..f58e2f23 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -3,7 +3,9 @@ v5.3.0 * #80: Now raise a ``DeprecationWarning`` for all legacy functions. Instead, users should rely on the ``files()`` - API introduced in importlib_resources 1.3. + API introduced in importlib_resources 1.3. See + `Migrating from Legacy `_ + for guidance on avoiding the deprecated functions. v5.2.3 ====== diff --git a/docs/using.rst b/docs/using.rst index c0a60ad1..ec7f0fad 100644 --- a/docs/using.rst +++ b/docs/using.rst @@ -163,6 +163,21 @@ manager. Both relative and absolute paths work for Python 3.7 and newer. +Migrating from Legacy +===================== + +Starting with Python 3.9 and ``importlib_resources`` 1.4, this package +introduced the ``files()`` API, to be preferred over the legacy API, +i.e. the functions ``open_binary``, ``open_text``, ``path``, +``contents``, ``read_text``, ``read_binary``, and ``is_resource``. + +To port to the ``files()`` API, refer to the +`_legacy module `_ +to see simple wrappers that enable drop-in replacement based on the +preferred API, and either copy those or adapt the usage to utilize the +``files`` and ``Traversable`` interfaces directly. + + Extending ========= From 239ae6d56ae545534cf69dc1c91000c620a5f8f7 Mon Sep 17 00:00:00 2001 From: "Jason R. Coombs" Date: Mon, 18 Oct 2021 13:54:29 -0400 Subject: [PATCH 6/6] Provide references to relevant docs and protocol definition for ease-of-use. --- docs/using.rst | 4 +++- importlib_resources/_legacy.py | 4 +++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/using.rst b/docs/using.rst index ec7f0fad..548fa58e 100644 --- a/docs/using.rst +++ b/docs/using.rst @@ -175,7 +175,9 @@ To port to the ``files()`` API, refer to the `_legacy module `_ to see simple wrappers that enable drop-in replacement based on the preferred API, and either copy those or adapt the usage to utilize the -``files`` and ``Traversable`` interfaces directly. +``files`` and +`Traversable `_ +interfaces directly. Extending diff --git a/importlib_resources/_legacy.py b/importlib_resources/_legacy.py index 7526d512..477f89e4 100644 --- a/importlib_resources/_legacy.py +++ b/importlib_resources/_legacy.py @@ -16,7 +16,9 @@ def deprecated(func): @functools.wraps(func) def wrapper(*args, **kwargs): warnings.warn( - f"{func.__name__} is deprecated. Use files() instead.", + f"{func.__name__} is deprecated. Use files() instead. " + "Refer to https://importlib-resources.readthedocs.io" + "/en/latest/using.html#migrating-from-legacy for migration advice.", DeprecationWarning, stacklevel=2, )