Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

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>
This commit is contained in:
Jason R. Coombs 2021-11-24 02:51:37 -05:00 committed by GitHub
parent 324527012f
commit d5cd2effa6
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
10 changed files with 204 additions and 84 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
Doc/library/importlib.rst
View File

@ -917,7 +917,9 @@ not** have to exist as physical files and directories on the file system.
on `using importlib.resources
<http://importlib-resources.readthedocs.io/en/latest/using.html>`_ and
`migrating from pkg_resources to importlib.resources
<http://importlib-resources.readthedocs.io/en/latest/migration.html>`_.
<http://importlib-resources.readthedocs.io/en/latest/migration.html>`_
and
`migrating legacy usage <https://importlib-resources.readthedocs.io/en/latest/using.html#migrating-from-legacy>`_.
Loaders that wish to support resource reading should implement a
``get_resource_reader(fullname)`` method as specified by
@ -979,6 +981,8 @@ The following functions are available.
sub-resources (i.e. it cannot be a directory). This function returns a
``typing.BinaryIO`` instance, a binary I/O stream open for reading.
.. deprecated:: 3.11
.. function:: open_text(package, resource, encoding='utf-8', errors='strict')
@ -994,6 +998,8 @@ The following functions are available.
This function returns a ``typing.TextIO`` instance, a text I/O stream open
for reading.
.. deprecated:: 3.11
.. function:: read_binary(package, resource)
@ -1006,6 +1012,8 @@ The following functions are available.
sub-resources (i.e. it cannot be a directory). This function returns the
contents of the resource as :class:`bytes`.
.. deprecated:: 3.11
.. function:: read_text(package, resource, encoding='utf-8', errors='strict')
@ -1019,6 +1027,8 @@ The following functions are available.
have the same meaning as with built-in :func:`open`. This function
returns the contents of the resource as :class:`str`.
.. deprecated:: 3.11
.. function:: path(package, resource)
@ -1034,6 +1044,8 @@ The following functions are available.
within *package*; it may not contain path separators and it may not have
sub-resources (i.e. it cannot be a directory).
.. deprecated:: 3.11
.. function:: is_resource(package, name)
@ -1042,6 +1054,8 @@ The following functions are available.
*package* is either a name or a module object which conforms to the
``Package`` requirements.
.. deprecated:: 3.11
.. function:: contents(package)
@ -1052,6 +1066,8 @@ The following functions are available.
*package* is either a name or a module object which conforms to the
``Package`` requirements.
.. deprecated:: 3.11
:mod:`importlib.machinery` -- Importers and path hooks
------------------------------------------------------

20
Lib/importlib/_itertools.py
View File

@ -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):

24
Lib/importlib/_legacy.py
View File

@ -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 @@ Package = Union[types.ModuleType, str]
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,

9
Lib/test/test_importlib/resources/util.py
View File

@ -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.

3
Lib/test/test_importlib/test_contents.py
View File

@ -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):

53
Lib/test/test_importlib/test_open.py
View File

@ -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):

28
Lib/test/test_importlib/test_path.py
View File

@ -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__':

29
Lib/test/test_importlib/test_read.py
View File

@ -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')

103
Lib/test/test_importlib/test_resource.py
View File

@ -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:

1
Misc/NEWS.d/next/Library/2021-10-18-14-25-35.bpo-45514.YmlzIl.rst Normal file
View File

@ -0,0 +1 @@
Deprecated legacy functions in :mod:`importlib.resources`.