gh-97930: Apply changes from importlib_resources 5.10. (GH-100598) · python/cpython@447d061 (original) (raw)
`@@ -14,12 +14,13 @@ This module leverages Python's import system to provide access to resources
`
14
14
`within packages.
`
15
15
``
16
16
`"Resources" are file-like resources associated with a module or package in
`
17
``
`-
Python. The resources may be contained directly in a package or within a
`
18
``
`-
subdirectory contained in that package. Resources may be text or binary. As a
`
19
``
`-
result, Python module sources (.py) of a package and compilation artifacts
`
20
``
`-
(pycache) are technically de-facto resources of that package. In practice,
`
21
``
`-
however, resources are primarily those non-Python artifacts exposed
`
22
``
`-
specifically by the package author.
`
``
17
`+
Python. The resources may be contained directly in a package, within a
`
``
18
`+
subdirectory contained in that package, or adjacent to modules outside a
`
``
19
`+
package. Resources may be text or binary. As a result, Python module sources
`
``
20
`+
(.py) of a package and compilation artifacts (pycache) are technically
`
``
21
`+
de-facto resources of that package. In practice, however, resources are
`
``
22
`+
primarily those non-Python artifacts exposed specifically by the package
`
``
23
`+
author.
`
23
24
``
24
25
`Resources can be opened or read in either binary or text mode.
`
25
26
``
`@@ -49,27 +50,35 @@ for example, a package and its resources can be imported from a zip file using
`
49
50
``` get_resource_reader(fullname) method as specified by
`50`
`51`
`` :class:`importlib.resources.abc.ResourceReader`.
``
`51`
`52`
``
`52`
``
`-
.. data:: Package
`
``
`53`
`+
.. data:: Anchor
`
`53`
`54`
``
`54`
``
``` -
Whenever a function accepts a ``Package`` argument, you can pass in
55
``
`` -
either a :class:module object <types.ModuleType> or a module name
``
56
``
`-
as a string. You can only pass module objects whose
`
57
``
``__spec__.submodule_search_locations`` is not ``None``.
``
55
`` +
Represents an anchor for resources, either a :class:`module object
``
``
56
`` +
<types.ModuleType>` or a module name as a string. Defined as
``
``
57
``Union[str, ModuleType]``.
58
58
``
59
``
The ``Package`` type is defined as ``Union[str, ModuleType]``.
60
``
-
61
``
`-
.. function:: files(package)
`
``
59
`+
.. function:: files(anchor: Optional[Anchor] = None)
`
62
60
``
63
61
`` Returns a :class:~importlib.resources.abc.Traversable object
``
64
``
`-
representing the resource container for the package (think directory)
`
65
``
`-
and its resources (think files). A Traversable may contain other
`
66
``
`-
containers (think subdirectories).
`
``
62
`+
representing the resource container (think directory) and its resources
`
``
63
`+
(think files). A Traversable may contain other containers (think
`
``
64
`+
subdirectories).
`
67
65
``
68
``
`-
package is either a name or a module object which conforms to the
`
69
``
`` -
:data:Package requirements.
``
``
66
`` +
anchor is an optional :data:Anchor. If the anchor is a
``
``
67
`+
package, resources are resolved from that package. If a module,
`
``
68
`+
resources are resolved adjacent to that module (in the same package
`
``
69
`+
or the package root). If the anchor is omitted, the caller's module
`
``
70
`+
is used.
`
70
71
``
71
72
` .. versionadded:: 3.9
`
72
73
``
``
74
`+
.. versionchanged:: 3.12
`
``
75
`+
"package" parameter was renamed to "anchor". "anchor" can now
`
``
76
`+
be a non-package module and if omitted will default to the caller's
`
``
77
`+
module. "package" is still accepted for compatibility but will raise
`
``
78
`+
a DeprecationWarning. Consider passing the anchor positionally or
`
``
79
using ``importlib_resources >= 5.10`` for a compatible interface
``
80
`+
on older Pythons.
`
``
81
+
73
82
`.. function:: as_file(traversable)
`
74
83
``
75
84
`` Given a :class:~importlib.resources.abc.Traversable object representing
``
`@@ -86,6 +95,7 @@ for example, a package and its resources can be imported from a zip file using
`
86
95
``
87
96
` .. versionadded:: 3.9
`
88
97
``
``
98
+
89
99
`Deprecated functions
`
90
100
`--------------------
`
91
101
``
`@@ -94,6 +104,18 @@ scheduled for removal in a future version of Python.
`
94
104
`The main drawback of these functions is that they do not support
`
95
105
`directories: they assume all resources are located directly within a package.
`
96
106
``
``
107
`+
.. data:: Package
`
``
108
+
``
109
Whenever a function accepts a ``Package`` argument, you can pass in
``
110
`` +
either a :class:module object <types.ModuleType> or a module name
``
``
111
`+
as a string. You can only pass module objects whose
`
``
112
``__spec__.submodule_search_locations`` is not ``None``.
``
113
+
``
114
The ``Package`` type is defined as ``Union[str, ModuleType]``.
``
115
+
``
116
`+
.. deprecated:: 3.12
`
``
117
+
``
118
+
97
119
`.. data:: Resource
`
98
120
``
99
121
` For resource arguments of the functions below, you can pass in
`
`@@ -102,6 +124,7 @@ directories: they assume all resources are located directly within a package.
`
102
124
``
103
125
``` The Resource type is defined as Union[str, os.PathLike].
```
104
126
``
``
127
+
105
128
`.. function:: open_binary(package, resource)
`
106
129
``
107
130
` Open for binary reading the resource within package.
`