diff --git a/lib/importlib_resources/__init__.py b/lib/importlib_resources/__init__.py index 2468f575..15f6b26b 100644 --- a/lib/importlib_resources/__init__.py +++ b/lib/importlib_resources/__init__.py @@ -4,7 +4,6 @@ from ._common import ( as_file, files, Package, - Resource, ) from ._legacy import ( @@ -15,6 +14,7 @@ from ._legacy import ( read_text, is_resource, path, + Resource, ) from importlib_resources.abc import ResourceReader diff --git a/lib/importlib_resources/_adapters.py b/lib/importlib_resources/_adapters.py index 9907b148..ea363d86 100644 --- a/lib/importlib_resources/_adapters.py +++ b/lib/importlib_resources/_adapters.py @@ -41,8 +41,8 @@ def _io_wrapper(file, mode='r', *args, **kwargs): class CompatibilityFiles: """ - Adapter for an existing or non-existant resource reader - to provide a compability .files(). + Adapter for an existing or non-existent resource reader + to provide a compatibility .files(). """ class SpecPath(abc.Traversable): @@ -83,7 +83,7 @@ class CompatibilityFiles: class ChildPath(abc.Traversable): """ Path tied to a resource reader child. - Can be read but doesn't expose any meaningfull children. + Can be read but doesn't expose any meaningful children. """ def __init__(self, reader, name): diff --git a/lib/importlib_resources/_common.py b/lib/importlib_resources/_common.py index 25511672..a12e2c75 100644 --- a/lib/importlib_resources/_common.py +++ b/lib/importlib_resources/_common.py @@ -6,13 +6,12 @@ import contextlib import types import importlib -from typing import Union, Any, Optional +from typing import Union, Optional from .abc import ResourceReader, Traversable from ._compat import wrap_spec Package = Union[types.ModuleType, str] -Resource = Union[str, os.PathLike] def files(package): @@ -23,19 +22,6 @@ def files(package): return from_package(get_package(package)) -def normalize_path(path): - # type: (Any) -> str - """Normalize a path by ensuring it is a string. - - If the resulting string contains path separators, an exception is raised. - """ - str_path = str(path) - parent, file_name = os.path.split(str_path) - if parent: - raise ValueError(f'{path!r} must be only a file name') - return file_name - - def get_resource_reader(package): # type: (types.ModuleType) -> Optional[ResourceReader] """ diff --git a/lib/importlib_resources/_itertools.py b/lib/importlib_resources/_itertools.py index dd45f2f0..cce05582 100644 --- a/lib/importlib_resources/_itertools.py +++ b/lib/importlib_resources/_itertools.py @@ -1,11 +1,27 @@ from itertools import filterfalse +from typing import ( + Callable, + Iterable, + Iterator, + Optional, + Set, + TypeVar, + Union, +) -def unique_everseen(iterable, key=None): +# Type and type variable definitions +_T = TypeVar('_T') +_U = TypeVar('_U') + + +def unique_everseen( + iterable: Iterable[_T], key: Optional[Callable[[_T], _U]] = None +) -> Iterator[_T]: "List unique elements, preserving order. Remember all elements ever seen." # unique_everseen('AAAABBBCCDAABBB') --> A B C D # unique_everseen('ABBCcAD', str.lower) --> A B C D - seen = set() + seen: Set[Union[_T, _U]] = set() seen_add = seen.add if key is None: for element in filterfalse(seen.__contains__, iterable): diff --git a/lib/importlib_resources/_legacy.py b/lib/importlib_resources/_legacy.py index 2ddec5f9..1d5d3f1f 100644 --- a/lib/importlib_resources/_legacy.py +++ b/lib/importlib_resources/_legacy.py @@ -1,25 +1,58 @@ +import functools import os import pathlib import types +import warnings -from typing import Union, Iterable, ContextManager, BinaryIO, TextIO +from typing import Union, Iterable, ContextManager, BinaryIO, TextIO, Any from . import _common Package = Union[types.ModuleType, str] -Resource = Union[str, os.PathLike] +Resource = str +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 + + +def normalize_path(path): + # type: (Any) -> str + """Normalize a path by ensuring it is a string. + + If the resulting string contains path separators, an exception is raised. + """ + str_path = str(path) + parent, file_name = os.path.split(str_path) + if parent: + raise ValueError(f'{path!r} must be only a file name') + return file_name + + +@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') + return (_common.files(package) / 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() + return (_common.files(package) / normalize_path(resource)).read_bytes() +@deprecated def open_text( package: Package, resource: Resource, @@ -27,11 +60,12 @@ def open_text( errors: str = 'strict', ) -> TextIO: """Return a file-like object opened for text reading of the resource.""" - return (_common.files(package) / _common.normalize_path(resource)).open( + return (_common.files(package) / normalize_path(resource)).open( 'r', encoding=encoding, errors=errors ) +@deprecated def read_text( package: Package, resource: Resource, @@ -47,6 +81,7 @@ def read_text( return fp.read() +@deprecated def contents(package: Package) -> Iterable[str]: """Return an iterable of entries in `package`. @@ -57,18 +92,20 @@ 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`. Directories are *not* resources. """ - resource = _common.normalize_path(name) + resource = normalize_path(name) return any( traversable.name == resource and traversable.is_file() for traversable in _common.files(package).iterdir() ) +@deprecated def path( package: Package, resource: Resource, @@ -81,4 +118,4 @@ def path( raised if the file was deleted prior to the context manager exiting). """ - return _common.as_file(_common.files(package) / _common.normalize_path(resource)) + return _common.as_file(_common.files(package) / normalize_path(resource)) diff --git a/lib/importlib_resources/abc.py b/lib/importlib_resources/abc.py index 56dc8127..d39dc1ad 100644 --- a/lib/importlib_resources/abc.py +++ b/lib/importlib_resources/abc.py @@ -76,7 +76,7 @@ class Traversable(Protocol): @abc.abstractmethod def is_dir(self) -> bool: """ - Return True if self is a dir + Return True if self is a directory """ @abc.abstractmethod diff --git a/lib/importlib_resources/tests/test_contents.py b/lib/importlib_resources/tests/test_contents.py index 2af70607..525568e8 100644 --- a/lib/importlib_resources/tests/test_contents.py +++ b/lib/importlib_resources/tests/test_contents.py @@ -15,7 +15,8 @@ class ContentsTests: } def test_contents(self): - assert self.expected <= set(resources.contents(self.data)) + contents = {path.name for path in resources.files(self.data).iterdir()} + assert self.expected <= contents class ContentsDiskTests(ContentsTests, unittest.TestCase): diff --git a/lib/importlib_resources/tests/test_open.py b/lib/importlib_resources/tests/test_open.py index 919fc0db..87b42c3d 100644 --- a/lib/importlib_resources/tests/test_open.py +++ b/lib/importlib_resources/tests/test_open.py @@ -7,37 +7,43 @@ from . import util class CommonBinaryTests(util.CommonTests, unittest.TestCase): def execute(self, package, path): - with resources.open_binary(package, path): + target = resources.files(package).joinpath(path) + with target.open('rb'): pass class CommonTextTests(util.CommonTests, unittest.TestCase): def execute(self, package, path): - with resources.open_text(package, path): + target = resources.files(package).joinpath(path) + with target.open(): pass class OpenTests: def test_open_binary(self): - with resources.open_binary(self.data, 'utf-8.file') as fp: + target = resources.files(self.data) / 'binary.file' + with target.open('rb') as fp: result = fp.read() - self.assertEqual(result, b'Hello, UTF-8 world!\n') + 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: + target = resources.files(self.data) / 'utf-8.file' + with target.open() 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: + target = resources.files(self.data) / 'utf-16.file' + with target.open(encoding='utf-16', errors='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: + target = resources.files(self.data) / 'utf-16.file' + with target.open(encoding='utf-8', errors='strict') as fp: self.assertRaises(UnicodeError, fp.read) - with resources.open_text(self.data, 'utf-16.file', 'utf-8', 'ignore') as fp: + with target.open(encoding='utf-8', errors='ignore') as fp: result = fp.read() self.assertEqual( result, @@ -47,14 +53,12 @@ class OpenTests: ) def test_open_binary_FileNotFoundError(self): - self.assertRaises( - FileNotFoundError, resources.open_binary, self.data, 'does-not-exist' - ) + target = resources.files(self.data) / 'does-not-exist' + self.assertRaises(FileNotFoundError, target.open, 'rb') def test_open_text_FileNotFoundError(self): - self.assertRaises( - FileNotFoundError, resources.open_text, self.data, 'does-not-exist' - ) + target = resources.files(self.data) / 'does-not-exist' + self.assertRaises(FileNotFoundError, target.open) class OpenDiskTests(OpenTests, unittest.TestCase): diff --git a/lib/importlib_resources/tests/test_path.py b/lib/importlib_resources/tests/test_path.py index 9180626f..4f4d3943 100644 --- a/lib/importlib_resources/tests/test_path.py +++ b/lib/importlib_resources/tests/test_path.py @@ -8,7 +8,7 @@ from . import util class CommonTests(util.CommonTests, unittest.TestCase): def execute(self, package, path): - with resources.path(package, path): + with resources.as_file(resources.files(package).joinpath(path)): pass @@ -17,7 +17,8 @@ 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: + target = resources.files(self.data) / 'utf-8.file' + with resources.as_file(target) 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: @@ -34,7 +35,8 @@ class PathDiskTests(PathTests, unittest.TestCase): file-system-backed resources do not get the tempdir treatment. """ - with resources.path(self.data, 'utf-8.file') as path: + target = resources.files(self.data) / 'utf-8.file' + with resources.as_file(target) as path: assert 'data' in str(path) @@ -53,7 +55,8 @@ 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: + target = resources.files(self.data) / 'utf-8.file' + with resources.as_file(target) as path: path.unlink() diff --git a/lib/importlib_resources/tests/test_read.py b/lib/importlib_resources/tests/test_read.py index 2616fbf5..41dd6db5 100644 --- a/lib/importlib_resources/tests/test_read.py +++ b/lib/importlib_resources/tests/test_read.py @@ -8,31 +8,36 @@ from importlib import import_module class CommonBinaryTests(util.CommonTests, unittest.TestCase): def execute(self, package, path): - resources.read_binary(package, path) + resources.files(package).joinpath(path).read_bytes() class CommonTextTests(util.CommonTests, unittest.TestCase): def execute(self, package, path): - resources.read_text(package, path) + resources.files(package).joinpath(path).read_text() class ReadTests: - def test_read_binary(self): - result = resources.read_binary(self.data, 'binary.file') + def test_read_bytes(self): + result = resources.files(self.data).joinpath('binary.file').read_bytes() self.assertEqual(result, b'\0\1\2\3') def test_read_text_default_encoding(self): - result = resources.read_text(self.data, 'utf-8.file') + result = resources.files(self.data).joinpath('utf-8.file').read_text() 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') + result = ( + resources.files(self.data) + .joinpath('utf-16.file') + .read_text(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') + target = resources.files(self.data) / 'utf-16.file' + self.assertRaises(UnicodeError, target.read_text, encoding='utf-8') + result = target.read_text(encoding='utf-8', errors='ignore') self.assertEqual( result, 'H\x00e\x00l\x00l\x00o\x00,\x00 ' @@ -48,11 +53,15 @@ 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') + result = resources.files(submodule).joinpath('binary.file').read_bytes() self.assertEqual(result, b'\0\1\2\3') def test_read_submodule_resource_by_name(self): - result = resources.read_binary('ziptestdata.subdirectory', 'binary.file') + result = ( + resources.files('ziptestdata.subdirectory') + .joinpath('binary.file') + .read_bytes() + ) self.assertEqual(result, b'\0\1\2\3') diff --git a/lib/importlib_resources/tests/test_resource.py b/lib/importlib_resources/tests/test_resource.py index 071cb8d4..5affd8b0 100644 --- a/lib/importlib_resources/tests/test_resource.py +++ b/lib/importlib_resources/tests/test_resource.py @@ -14,34 +14,18 @@ from ._compat import import_helper, unlink 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')) + def test_is_file_exists(self): + target = resources.files(self.data) / 'binary.file' + self.assertTrue(target.is_file()) - def test_is_resource_missing(self): - self.assertFalse(resources.is_resource(self.data, 'not-a-file')) + def test_is_file_missing(self): + target = resources.files(self.data) / 'not-a-file' + self.assertFalse(target.is_file()) - def test_is_resource_subresource_directory(self): - # Directories are not resources. - self.assertFalse(resources.is_resource(self.data, 'subdirectory')) - - def test_contents(self): - 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 - # test suite importing these modules, which - # are not germane to this test, so just filter them out. - contents.discard('__pycache__') - self.assertEqual( - sorted(contents), - [ - '__init__.py', - 'binary.file', - 'subdirectory', - 'utf-16.file', - 'utf-8.file', - ], - ) + def test_is_dir(self): + target = resources.files(self.data) / 'subdirectory' + self.assertFalse(target.is_file()) + self.assertTrue(target.is_dir()) class ResourceDiskTests(ResourceTests, unittest.TestCase): @@ -53,30 +37,34 @@ class ResourceZipTests(ResourceTests, util.ZipSetup, unittest.TestCase): pass +def names(traversable): + return {item.name for item in traversable.iterdir()} + + class ResourceLoaderTests(unittest.TestCase): 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'}) + self.assertEqual(names(resources.files(package)), {'A', 'B', 'C'}) - def test_resource_is_resource(self): + def test_is_file(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')) + self.assertTrue(resources.files(package).joinpath('B').is_file()) - def test_resource_directory_is_not_resource(self): + def test_is_dir(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')) + self.assertTrue(resources.files(package).joinpath('D').is_dir()) - def test_resource_missing_is_not_resource(self): + def test_resource_missing(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')) + self.assertFalse(resources.files(package).joinpath('Z').is_file()) class ResourceCornerCaseTests(unittest.TestCase): @@ -94,7 +82,7 @@ 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')) + self.assertFalse(resources.files(module).joinpath('A').is_file()) class ResourceFromZipsTest01(util.ZipSetupBase, unittest.TestCase): @@ -102,22 +90,24 @@ 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')) + self.assertTrue(resources.files(submodule).joinpath('binary.file').is_file()) def test_read_submodule_resource_by_name(self): self.assertTrue( - resources.is_resource('ziptestdata.subdirectory', 'binary.file') + resources.files('ziptestdata.subdirectory') + .joinpath('binary.file') + .is_file() ) def test_submodule_contents(self): submodule = import_module('ziptestdata.subdirectory') self.assertEqual( - set(resources.contents(submodule)), {'__init__.py', 'binary.file'} + names(resources.files(submodule)), {'__init__.py', 'binary.file'} ) def test_submodule_contents_by_name(self): self.assertEqual( - set(resources.contents('ziptestdata.subdirectory')), + names(resources.files('ziptestdata.subdirectory')), {'__init__.py', 'binary.file'}, ) @@ -131,10 +121,12 @@ class ResourceFromZipsTest02(util.ZipSetupBase, unittest.TestCase): distinct resources. Ref python/importlib_resources#44. """ self.assertEqual( - set(resources.contents('ziptestdata.one')), {'__init__.py', 'resource1.txt'} + names(resources.files('ziptestdata.one')), + {'__init__.py', 'resource1.txt'}, ) self.assertEqual( - set(resources.contents('ziptestdata.two')), {'__init__.py', 'resource2.txt'} + names(resources.files('ziptestdata.two')), + {'__init__.py', 'resource2.txt'}, ) @@ -175,41 +167,43 @@ class DeletingZipsTest(unittest.TestCase): # If the test fails, this will probably fail too pass - def test_contents_does_not_keep_open(self): - c = resources.contents('ziptestdata') + def test_iterdir_does_not_keep_open(self): + c = [item.name for item in resources.files('ziptestdata').iterdir()] self.zip_path.unlink() del c - def test_is_resource_does_not_keep_open(self): - c = resources.is_resource('ziptestdata', 'binary.file') + def test_is_file_does_not_keep_open(self): + c = resources.files('ziptestdata').joinpath('binary.file').is_file() self.zip_path.unlink() del c - def test_is_resource_failure_does_not_keep_open(self): - c = resources.is_resource('ziptestdata', 'not-present') + def test_is_file_failure_does_not_keep_open(self): + c = resources.files('ziptestdata').joinpath('not-present').is_file() self.zip_path.unlink() del c @unittest.skip("Desired but not supported.") - def test_path_does_not_keep_open(self): - c = resources.path('ziptestdata', 'binary.file') + def test_as_file_does_not_keep_open(self): # pragma: no cover + c = resources.as_file(resources.files('ziptestdata') / 'binary.file') self.zip_path.unlink() del c 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__() + c = resources.as_file( + resources.files('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') + c = resources.files('ziptestdata').joinpath('binary.file').read_bytes() 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') + c = resources.files('ziptestdata').joinpath('utf-8.file').read_text() self.zip_path.unlink() del c @@ -227,14 +221,18 @@ class ResourceFromNamespaceTest01(unittest.TestCase): def test_is_submodule_resource(self): self.assertTrue( - resources.is_resource(import_module('namespacedata01'), 'binary.file') + resources.files(import_module('namespacedata01')) + .joinpath('binary.file') + .is_file() ) def test_read_submodule_resource_by_name(self): - self.assertTrue(resources.is_resource('namespacedata01', 'binary.file')) + self.assertTrue( + resources.files('namespacedata01').joinpath('binary.file').is_file() + ) def test_submodule_contents(self): - contents = set(resources.contents(import_module('namespacedata01'))) + contents = names(resources.files(import_module('namespacedata01'))) try: contents.remove('__pycache__') except KeyError: @@ -242,7 +240,7 @@ 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')) + contents = names(resources.files('namespacedata01')) try: contents.remove('__pycache__') except KeyError: diff --git a/lib/importlib_resources/tests/util.py b/lib/importlib_resources/tests/util.py index 6ac4332e..c6d83e4b 100644 --- a/lib/importlib_resources/tests/util.py +++ b/lib/importlib_resources/tests/util.py @@ -97,18 +97,6 @@ class CommonTests(metaclass=abc.ABCMeta): path = PurePath('utf-8.file') self.execute(data01, path) - def test_absolute_path(self): - # An absolute path is a ValueError. - path = Path(__file__) - full_path = path.parent / 'utf-8.file' - with self.assertRaises(ValueError): - self.execute(data01, full_path) - - def test_relative_path(self): - # A reative path is a ValueError. - with self.assertRaises(ValueError): - self.execute(data01, '../data01/utf-8.file') - def test_importing_module_as_side_effect(self): # The anchor package can already be imported. del sys.modules[data01.__name__]