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