diff --git a/CHANGES.rst b/CHANGES.rst index 859dbf1..f58e2f2 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -1,3 +1,12 @@ +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. 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 c0a60ad..548fa58 100644 --- a/docs/using.rst +++ b/docs/using.rst @@ -163,6 +163,23 @@ 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 ========= diff --git a/importlib_resources/_legacy.py b/importlib_resources/_legacy.py index 2ddec5f..477f89e 100644 --- a/importlib_resources/_legacy.py +++ b/importlib_resources/_legacy.py @@ -1,6 +1,8 @@ +import functools import os import pathlib import types +import warnings from typing import Union, Iterable, ContextManager, BinaryIO, TextIO @@ -10,16 +12,34 @@ Resource = Union[str, os.PathLike] +def deprecated(func): + @functools.wraps(func) + def wrapper(*args, **kwargs): + warnings.warn( + 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, + ) + 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.""" 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.""" return (_common.files(package) / _common.normalize_path(resource)).read_bytes() +@deprecated def open_text( package: Package, resource: Resource, @@ -32,6 +52,7 @@ def open_text( ) +@deprecated def read_text( package: Package, resource: Resource, @@ -47,6 +68,7 @@ def read_text( return fp.read() +@deprecated def contents(package: Package) -> Iterable[str]: """Return an iterable of entries in `package`. @@ -57,6 +79,7 @@ def contents(package: Package) -> Iterable[str]: 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`. @@ -69,6 +92,7 @@ def is_resource(package: Package, name: str) -> bool: ) +@deprecated def path( package: Package, resource: Resource, diff --git a/importlib_resources/tests/test_contents.py b/importlib_resources/tests/test_contents.py index 2af7060..c95e1a7 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 919fc0d..1c8a943 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 9180626..af433ce 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 2616fbf..da7d274 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 071cb8d..9fcf670 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 6ac4332..b578de9 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.