1:mod:`importlib.resources` -- Resources
2---------------------------------------
3
4.. module:: importlib.resources
5    :synopsis: Package resource reading, opening, and access
6
7**Source code:** :source:`Lib/importlib/resources/__init__.py`
8
9--------------
10
11.. versionadded:: 3.7
12
13This module leverages Python's import system to provide access to *resources*
14within *packages*.  If you can import a package, you can access resources
15within that package.  Resources can be opened or read, in either binary or
16text mode.
17
18Resources are roughly akin to files inside directories, though it's important
19to keep in mind that this is just a metaphor.  Resources and packages **do
20not** have to exist as physical files and directories on the file system:
21for example, a package and its resources can be imported from a zip file using
22:py:mod:`zipimport`.
23
24.. note::
25
26   This module provides functionality similar to `pkg_resources
27   <https://setuptools.readthedocs.io/en/latest/pkg_resources.html>`_ `Basic
28   Resource Access
29   <https://setuptools.readthedocs.io/en/latest/pkg_resources.html#basic-resource-access>`_
30   without the performance overhead of that package.  This makes reading
31   resources included in packages easier, with more stable and consistent
32   semantics.
33
34   The standalone backport of this module provides more information
35   on `using importlib.resources
36   <https://importlib-resources.readthedocs.io/en/latest/using.html>`_ and
37   `migrating from pkg_resources to importlib.resources
38   <https://importlib-resources.readthedocs.io/en/latest/migration.html>`_.
39
40:class:`Loaders <importlib.abc.Loader>` that wish to support resource reading should implement a
41``get_resource_reader(fullname)`` method as specified by
42:class:`importlib.resources.abc.ResourceReader`.
43
44.. data:: Package
45
46    Whenever a function accepts a ``Package`` argument, you can pass in
47    either a :class:`module object <types.ModuleType>` or a module name
48    as a string.  You can only pass module objects whose
49    ``__spec__.submodule_search_locations`` is not ``None``.
50
51    The ``Package`` type is defined as ``Union[str, ModuleType]``.
52
53.. function:: files(package)
54
55    Returns a :class:`~importlib.resources.abc.Traversable` object
56    representing the resource container for the package (think directory)
57    and its resources (think files). A Traversable may contain other
58    containers (think subdirectories).
59
60    *package* is either a name or a module object which conforms to the
61    :data:`Package` requirements.
62
63    .. versionadded:: 3.9
64
65.. function:: as_file(traversable)
66
67    Given a :class:`~importlib.resources.abc.Traversable` object representing
68    a file, typically from :func:`importlib.resources.files`, return
69    a context manager for use in a :keyword:`with` statement.
70    The context manager provides a :class:`pathlib.Path` object.
71
72    Exiting the context manager cleans up any temporary file created when the
73    resource was extracted from e.g. a zip file.
74
75    Use ``as_file`` when the Traversable methods
76    (``read_text``, etc) are insufficient and an actual file on
77    the file system is required.
78
79    .. versionadded:: 3.9
80
81Deprecated functions
82--------------------
83
84An older, deprecated set of functions is still available, but is
85scheduled for removal in a future version of Python.
86The main drawback of these functions is that they do not support
87directories: they assume all resources are located directly within a *package*.
88
89.. data:: Resource
90
91    For *resource* arguments of the functions below, you can pass in
92    the name of a resource as a string or
93    a :class:`path-like object <os.PathLike>`.
94
95    The ``Resource`` type is defined as ``Union[str, os.PathLike]``.
96
97.. function:: open_binary(package, resource)
98
99    Open for binary reading the *resource* within *package*.
100
101    *package* is either a name or a module object which conforms to the
102    ``Package`` requirements.  *resource* is the name of the resource to open
103    within *package*; it may not contain path separators and it may not have
104    sub-resources (i.e. it cannot be a directory).  This function returns a
105    ``typing.BinaryIO`` instance, a binary I/O stream open for reading.
106
107    .. deprecated:: 3.11
108
109       Calls to this function can be replaced by::
110
111          files(package).joinpath(resource).open('rb')
112
113
114.. function:: open_text(package, resource, encoding='utf-8', errors='strict')
115
116    Open for text reading the *resource* within *package*.  By default, the
117    resource is opened for reading as UTF-8.
118
119    *package* is either a name or a module object which conforms to the
120    ``Package`` requirements.  *resource* is the name of the resource to open
121    within *package*; it may not contain path separators and it may not have
122    sub-resources (i.e. it cannot be a directory).  *encoding* and *errors*
123    have the same meaning as with built-in :func:`open`.
124
125    This function returns a ``typing.TextIO`` instance, a text I/O stream open
126    for reading.
127
128    .. deprecated:: 3.11
129
130       Calls to this function can be replaced by::
131
132          files(package).joinpath(resource).open('r', encoding=encoding)
133
134
135.. function:: read_binary(package, resource)
136
137    Read and return the contents of the *resource* within *package* as
138    ``bytes``.
139
140    *package* is either a name or a module object which conforms to the
141    ``Package`` requirements.  *resource* is the name of the resource to open
142    within *package*; it may not contain path separators and it may not have
143    sub-resources (i.e. it cannot be a directory).  This function returns the
144    contents of the resource as :class:`bytes`.
145
146    .. deprecated:: 3.11
147
148       Calls to this function can be replaced by::
149
150          files(package).joinpath(resource).read_bytes()
151
152
153.. function:: read_text(package, resource, encoding='utf-8', errors='strict')
154
155    Read and return the contents of *resource* within *package* as a ``str``.
156    By default, the contents are read as strict UTF-8.
157
158    *package* is either a name or a module object which conforms to the
159    ``Package`` requirements.  *resource* is the name of the resource to open
160    within *package*; it may not contain path separators and it may not have
161    sub-resources (i.e. it cannot be a directory).  *encoding* and *errors*
162    have the same meaning as with built-in :func:`open`.  This function
163    returns the contents of the resource as :class:`str`.
164
165    .. deprecated:: 3.11
166
167       Calls to this function can be replaced by::
168
169          files(package).joinpath(resource).read_text(encoding=encoding)
170
171
172.. function:: path(package, resource)
173
174    Return the path to the *resource* as an actual file system path.  This
175    function returns a context manager for use in a :keyword:`with` statement.
176    The context manager provides a :class:`pathlib.Path` object.
177
178    Exiting the context manager cleans up any temporary file created when the
179    resource needs to be extracted from e.g. a zip file.
180
181    *package* is either a name or a module object which conforms to the
182    ``Package`` requirements.  *resource* is the name of the resource to open
183    within *package*; it may not contain path separators and it may not have
184    sub-resources (i.e. it cannot be a directory).
185
186    .. deprecated:: 3.11
187
188       Calls to this function can be replaced using :func:`as_file`::
189
190          as_file(files(package).joinpath(resource))
191
192
193.. function:: is_resource(package, name)
194
195    Return ``True`` if there is a resource named *name* in the package,
196    otherwise ``False``.
197    This function does not consider directories to be resources.
198    *package* is either a name or a module object which conforms to the
199    ``Package`` requirements.
200
201    .. deprecated:: 3.11
202
203       Calls to this function can be replaced by::
204
205          files(package).joinpath(resource).is_file()
206
207
208.. function:: contents(package)
209
210    Return an iterable over the named items within the package.  The iterable
211    returns :class:`str` resources (e.g. files) and non-resources
212    (e.g. directories).  The iterable does not recurse into subdirectories.
213
214    *package* is either a name or a module object which conforms to the
215    ``Package`` requirements.
216
217    .. deprecated:: 3.11
218
219       Calls to this function can be replaced by::
220
221          (resource.name for resource in files(package).iterdir() if resource.is_file())
222