Skip to content

Commit d5cd2ef

Browse files
jaracoFFY00
jaraco
and
FFY00
authored
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 <[email protected]>
1 parent 3245270 commit d5cd2ef

File tree

10 files changed

+204
-84
lines changed

10 files changed

+204
-84
lines changed

‎Doc/library/importlib.rst‎

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -917,7 +917,9 @@ not** have to exist as physical files and directories on the file system.
917917
on `using importlib.resources
918918
<http://importlib-resources.readthedocs.io/en/latest/using.html>`_ and
919919
`migrating from pkg_resources to importlib.resources
920-
<http://importlib-resources.readthedocs.io/en/latest/migration.html>`_.
920+
<http://importlib-resources.readthedocs.io/en/latest/migration.html>`_
921+
and
922+
`migrating legacy usage <https://importlib-resources.readthedocs.io/en/latest/using.html#migrating-from-legacy>`_.
921923

922924
Loaders that wish to support resource reading should implement a
923925
``get_resource_reader(fullname)`` method as specified by
@@ -979,6 +981,8 @@ The following functions are available.
979981
sub-resources (i.e. it cannot be a directory). This function returns a
980982
``typing.BinaryIO`` instance, a binary I/O stream open for reading.
981983

984+
.. deprecated:: 3.11
985+
982986

983987
.. function:: open_text(package, resource, encoding='utf-8', errors='strict')
984988

@@ -994,6 +998,8 @@ The following functions are available.
994998
This function returns a ``typing.TextIO`` instance, a text I/O stream open
995999
for reading.
9961000

1001+
.. deprecated:: 3.11
1002+
9971003

9981004
.. function:: read_binary(package, resource)
9991005

@@ -1006,6 +1012,8 @@ The following functions are available.
10061012
sub-resources (i.e. it cannot be a directory). This function returns the
10071013
contents of the resource as :class:`bytes`.
10081014

1015+
.. deprecated:: 3.11
1016+
10091017

10101018
.. function:: read_text(package, resource, encoding='utf-8', errors='strict')
10111019

@@ -1019,6 +1027,8 @@ The following functions are available.
10191027
have the same meaning as with built-in :func:`open`. This function
10201028
returns the contents of the resource as :class:`str`.
10211029

1030+
.. deprecated:: 3.11
1031+
10221032

10231033
.. function:: path(package, resource)
10241034

@@ -1034,6 +1044,8 @@ The following functions are available.
10341044
within *package*; it may not contain path separators and it may not have
10351045
sub-resources (i.e. it cannot be a directory).
10361046

1047+
.. deprecated:: 3.11
1048+
10371049

10381050
.. function:: is_resource(package, name)
10391051

@@ -1042,6 +1054,8 @@ The following functions are available.
10421054
*package* is either a name or a module object which conforms to the
10431055
``Package`` requirements.
10441056

1057+
.. deprecated:: 3.11
1058+
10451059

10461060
.. function:: contents(package)
10471061

@@ -1052,6 +1066,8 @@ The following functions are available.
10521066
*package* is either a name or a module object which conforms to the
10531067
``Package`` requirements.
10541068

1069+
.. deprecated:: 3.11
1070+
10551071

10561072
:mod:`importlib.machinery` -- Importers and path hooks
10571073
------------------------------------------------------

‎Lib/importlib/_itertools.py‎

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,27 @@
11
from itertools import filterfalse
22

3+
from typing import (
4+
Callable,
5+
Iterable,
6+
Iterator,
7+
Optional,
8+
Set,
9+
TypeVar,
10+
Union,
11+
)
312

4-
def unique_everseen(iterable, key=None):
13+
# Type and type variable definitions
14+
_T = TypeVar('_T')
15+
_U = TypeVar('_U')
16+
17+
18+
def unique_everseen(
19+
iterable: Iterable[_T], key: Optional[Callable[[_T], _U]] = None
20+
) -> Iterator[_T]:
521
"List unique elements, preserving order. Remember all elements ever seen."
622
# unique_everseen('AAAABBBCCDAABBB') --> A B C D
723
# unique_everseen('ABBCcAD', str.lower) --> A B C D
8-
seen = set()
24+
seen: Set[Union[_T, _U]] = set()
925
seen_add = seen.add
1026
if key is None:
1127
for element in filterfalse(seen.__contains__, iterable):

‎Lib/importlib/_legacy.py‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
1+
import functools
12
import os
23
import pathlib
34
import types
5+
import warnings
46

57
from typing import Union, Iterable, ContextManager, BinaryIO, TextIO
68

@@ -10,16 +12,34 @@
1012
Resource = Union[str, os.PathLike]
1113

1214

15+
def deprecated(func):
16+
@functools.wraps(func)
17+
def wrapper(*args, **kwargs):
18+
warnings.warn(
19+
f"{func.__name__} is deprecated. Use files() instead. "
20+
"Refer to https://importlib-resources.readthedocs.io"
21+
"/en/latest/using.html#migrating-from-legacy for migration advice.",
22+
DeprecationWarning,
23+
stacklevel=2,
24+
)
25+
return func(*args, **kwargs)
26+
27+
return wrapper
28+
29+
30+
@deprecated
1331
def open_binary(package: Package, resource: Resource) -> BinaryIO:
1432
"""Return a file-like object opened for binary reading of the resource."""
1533
return (_common.files(package) / _common.normalize_path(resource)).open('rb')
1634

1735

36+
@deprecated
1837
def read_binary(package: Package, resource: Resource) -> bytes:
1938
"""Return the binary contents of the resource."""
2039
return (_common.files(package) / _common.normalize_path(resource)).read_bytes()
2140

2241

42+
@deprecated
2343
def open_text(
2444
package: Package,
2545
resource: Resource,
@@ -32,6 +52,7 @@ def open_text(
3252
)
3353

3454

55+
@deprecated
3556
def read_text(
3657
package: Package,
3758
resource: Resource,
@@ -47,6 +68,7 @@ def read_text(
4768
return fp.read()
4869

4970

71+
@deprecated
5072
def contents(package: Package) -> Iterable[str]:
5173
"""Return an iterable of entries in `package`.
5274
@@ -57,6 +79,7 @@ def contents(package: Package) -> Iterable[str]:
5779
return [path.name for path in _common.files(package).iterdir()]
5880

5981

82+
@deprecated
6083
def is_resource(package: Package, name: str) -> bool:
6184
"""True if `name` is a resource inside `package`.
6285
@@ -69,6 +92,7 @@ def is_resource(package: Package, name: str) -> bool:
6992
)
7093

7194

95+
@deprecated
7296
def path(
7397
package: Package,
7498
resource: Resource,

‎Lib/test/test_importlib/resources/util.py‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,10 @@
11
import abc
2+
import contextlib
23
import importlib
34
import io
45
import sys
56
import types
7+
import warnings
68
from pathlib import Path, PurePath
79

810
from .. import data01
@@ -67,6 +69,13 @@ def create_package(file=None, path=None, is_package=True, contents=()):
6769
)
6870

6971

72+
@contextlib.contextmanager
73+
def suppress_known_deprecation():
74+
with warnings.catch_warnings(record=True) as ctx:
75+
warnings.simplefilter('default', category=DeprecationWarning)
76+
yield ctx
77+
78+
7079
class CommonTests(metaclass=abc.ABCMeta):
7180
"""
7281
Tests shared by test_open, test_path, and test_read.

‎Lib/test/test_importlib/test_contents.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,8 @@ class ContentsTests:
1515
}
1616

1717
def test_contents(self):
18-
assert self.expected <= set(resources.contents(self.data))
18+
with util.suppress_known_deprecation():
19+
assert self.expected <= set(resources.contents(self.data))
1920

2021

2122
class ContentsDiskTests(ContentsTests, unittest.TestCase):

‎Lib/test/test_importlib/test_open.py‎

Lines changed: 32 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -7,38 +7,47 @@
77

88
class CommonBinaryTests(util.CommonTests, unittest.TestCase):
99
def execute(self, package, path):
10-
with resources.open_binary(package, path):
11-
pass
10+
with util.suppress_known_deprecation():
11+
with resources.open_binary(package, path):
12+
pass
1213

1314

1415
class CommonTextTests(util.CommonTests, unittest.TestCase):
1516
def execute(self, package, path):
16-
with resources.open_text(package, path):
17-
pass
17+
with util.suppress_known_deprecation():
18+
with resources.open_text(package, path):
19+
pass
1820

1921

2022
class OpenTests:
2123
def test_open_binary(self):
22-
with resources.open_binary(self.data, 'binary.file') as fp:
23-
result = fp.read()
24-
self.assertEqual(result, b'\x00\x01\x02\x03')
24+
with util.suppress_known_deprecation():
25+
with resources.open_binary(self.data, 'binary.file') as fp:
26+
result = fp.read()
27+
self.assertEqual(result, b'\x00\x01\x02\x03')
2528

2629
def test_open_text_default_encoding(self):
27-
with resources.open_text(self.data, 'utf-8.file') as fp:
28-
result = fp.read()
30+
with util.suppress_known_deprecation():
31+
with resources.open_text(self.data, 'utf-8.file') as fp:
32+
result = fp.read()
2933
self.assertEqual(result, 'Hello, UTF-8 world!\n')
3034

3135
def test_open_text_given_encoding(self):
32-
with resources.open_text(self.data, 'utf-16.file', 'utf-16', 'strict') as fp:
33-
result = fp.read()
36+
with util.suppress_known_deprecation():
37+
with resources.open_text(
38+
self.data, 'utf-16.file', 'utf-16', 'strict'
39+
) as fp:
40+
result = fp.read()
3441
self.assertEqual(result, 'Hello, UTF-16 world!\n')
3542

3643
def test_open_text_with_errors(self):
3744
# Raises UnicodeError without the 'errors' argument.
38-
with resources.open_text(self.data, 'utf-16.file', 'utf-8', 'strict') as fp:
39-
self.assertRaises(UnicodeError, fp.read)
40-
with resources.open_text(self.data, 'utf-16.file', 'utf-8', 'ignore') as fp:
41-
result = fp.read()
45+
with util.suppress_known_deprecation():
46+
with resources.open_text(self.data, 'utf-16.file', 'utf-8', 'strict') as fp:
47+
self.assertRaises(UnicodeError, fp.read)
48+
with util.suppress_known_deprecation():
49+
with resources.open_text(self.data, 'utf-16.file', 'utf-8', 'ignore') as fp:
50+
result = fp.read()
4251
self.assertEqual(
4352
result,
4453
'H\x00e\x00l\x00l\x00o\x00,\x00 '
@@ -47,14 +56,16 @@ def test_open_text_with_errors(self):
4756
)
4857

4958
def test_open_binary_FileNotFoundError(self):
50-
self.assertRaises(
51-
FileNotFoundError, resources.open_binary, self.data, 'does-not-exist'
52-
)
59+
with util.suppress_known_deprecation():
60+
self.assertRaises(
61+
FileNotFoundError, resources.open_binary, self.data, 'does-not-exist'
62+
)
5363

5464
def test_open_text_FileNotFoundError(self):
55-
self.assertRaises(
56-
FileNotFoundError, resources.open_text, self.data, 'does-not-exist'
57-
)
65+
with util.suppress_known_deprecation():
66+
self.assertRaises(
67+
FileNotFoundError, resources.open_text, self.data, 'does-not-exist'
68+
)
5869

5970

6071
class OpenDiskTests(OpenTests, unittest.TestCase):

‎Lib/test/test_importlib/test_path.py‎

Lines changed: 16 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -8,21 +8,23 @@
88

99
class CommonTests(util.CommonTests, unittest.TestCase):
1010
def execute(self, package, path):
11-
with resources.path(package, path):
12-
pass
11+
with util.suppress_known_deprecation():
12+
with resources.path(package, path):
13+
pass
1314

1415

1516
class PathTests:
1617
def test_reading(self):
1718
# Path should be readable.
1819
# Test also implicitly verifies the returned object is a pathlib.Path
1920
# instance.
20-
with resources.path(self.data, 'utf-8.file') as path:
21-
self.assertTrue(path.name.endswith("utf-8.file"), repr(path))
22-
# pathlib.Path.read_text() was introduced in Python 3.5.
23-
with path.open('r', encoding='utf-8') as file:
24-
text = file.read()
25-
self.assertEqual('Hello, UTF-8 world!\n', text)
21+
with util.suppress_known_deprecation():
22+
with resources.path(self.data, 'utf-8.file') as path:
23+
self.assertTrue(path.name.endswith("utf-8.file"), repr(path))
24+
# pathlib.Path.read_text() was introduced in Python 3.5.
25+
with path.open('r', encoding='utf-8') as file:
26+
text = file.read()
27+
self.assertEqual('Hello, UTF-8 world!\n', text)
2628

2729

2830
class PathDiskTests(PathTests, unittest.TestCase):
@@ -32,8 +34,9 @@ def test_natural_path(self):
3234
# Guarantee the internal implementation detail that
3335
# file-system-backed resources do not get the tempdir
3436
# treatment.
35-
with resources.path(self.data, 'utf-8.file') as path:
36-
assert 'data' in str(path)
37+
with util.suppress_known_deprecation():
38+
with resources.path(self.data, 'utf-8.file') as path:
39+
assert 'data' in str(path)
3740

3841

3942
class PathMemoryTests(PathTests, unittest.TestCase):
@@ -51,8 +54,9 @@ class PathZipTests(PathTests, util.ZipSetup, unittest.TestCase):
5154
def test_remove_in_context_manager(self):
5255
# It is not an error if the file that was temporarily stashed on the
5356
# file system is removed inside the `with` stanza.
54-
with resources.path(self.data, 'utf-8.file') as path:
55-
path.unlink()
57+
with util.suppress_known_deprecation():
58+
with resources.path(self.data, 'utf-8.file') as path:
59+
path.unlink()
5660

5761

5862
if __name__ == '__main__':

0 commit comments

Comments
 (0)