path: root/devdocs/python~3.12/library%2Fimportlib.resources.html

 <span id="importlib-resources-package-resource-reading-opening-and-access"></span><h1>importlib.resources – Package resource reading, opening and access</h1> <p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.12/Lib/importlib/resources/__init__.py">Lib/importlib/resources/__init__.py</a></p>  <div class="versionadded"> <p><span class="versionmodified added">New in version 3.7.</span></p> </div> <p>This module leverages Python’s import system to provide access to <em>resources</em> within <em>packages</em>.</p> <p>“Resources” are file-like resources associated with a module or package in Python. The resources may be contained directly in a package, within a subdirectory contained in that package, or adjacent to modules outside a package. Resources may be text or binary. As a result, Python module sources (.py) of a package and compilation artifacts (pycache) are technically de-facto resources of that package. In practice, however, resources are primarily those non-Python artifacts exposed specifically by the package author.</p> <p>Resources can be opened or read in either binary or text mode.</p> <p>Resources are roughly akin to files inside directories, though it’s important to keep in mind that this is just a metaphor. Resources and packages <strong>do not</strong> have to exist as physical files and directories on the file system: for example, a package and its resources can be imported from a zip file using <a class="reference internal" href="zipimport#module-zipimport" title="zipimport: Support for importing Python modules from ZIP archives."><code>zipimport</code></a>.</p> <div class="admonition note"> <p class="admonition-title">Note</p> <p>This module provides functionality similar to <a class="reference external" href="https://setuptools.readthedocs.io/en/latest/pkg_resources.html">pkg_resources</a> <a class="reference external" href="https://setuptools.readthedocs.io/en/latest/pkg_resources.html#basic-resource-access">Basic Resource Access</a> without the performance overhead of that package. This makes reading resources included in packages easier, with more stable and consistent semantics.</p> <p>The standalone backport of this module provides more information on <a class="reference external" href="https://importlib-resources.readthedocs.io/en/latest/using.html">using importlib.resources</a> and <a class="reference external" href="https://importlib-resources.readthedocs.io/en/latest/migration.html">migrating from pkg_resources to importlib.resources</a>.</p> </div> <p><a class="reference internal" href="importlib#importlib.abc.Loader" title="importlib.abc.Loader"><code>Loaders</code></a> that wish to support resource reading should implement a <code>get_resource_reader(fullname)</code> method as specified by <a class="reference internal" href="importlib.resources.abc#importlib.resources.abc.ResourceReader" title="importlib.resources.abc.ResourceReader"><code>importlib.resources.abc.ResourceReader</code></a>.</p> <dl class="py class"> <dt class="sig sig-object py" id="importlib.resources.Anchor">
<code>class importlib.resources.Anchor</code> </dt> <dd>
<p>Represents an anchor for resources, either a <a class="reference internal" href="types#types.ModuleType" title="types.ModuleType"><code>module object</code></a> or a module name as a string. Defined as <code>Union[str, ModuleType]</code>.</p> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="importlib.resources.files">
<code>importlib.resources.files(anchor: Optional[Anchor] = None)</code> </dt> <dd>
<p>Returns a <a class="reference internal" href="importlib.resources.abc#importlib.resources.abc.Traversable" title="importlib.resources.abc.Traversable"><code>Traversable</code></a> object representing the resource container (think directory) and its resources (think files). A Traversable may contain other containers (think subdirectories).</p> <p><em>anchor</em> is an optional <a class="reference internal" href="#importlib.resources.Anchor" title="importlib.resources.Anchor"><code>Anchor</code></a>. If the anchor is a package, resources are resolved from that package. If a module, resources are resolved adjacent to that module (in the same package or the package root). If the anchor is omitted, the caller’s module is used.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.9.</span></p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.12: </span><em>package</em> parameter was renamed to <em>anchor</em>. <em>anchor</em> can now be a non-package module and if omitted will default to the caller’s module. <em>package</em> is still accepted for compatibility but will raise a <a class="reference internal" href="exceptions#DeprecationWarning" title="DeprecationWarning"><code>DeprecationWarning</code></a>. Consider passing the anchor positionally or using <code>importlib_resources &gt;= 5.10</code> for a compatible interface on older Pythons.</p> </div> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="importlib.resources.as_file">
<code>importlib.resources.as_file(traversable)</code> </dt> <dd>
<p>Given a <a class="reference internal" href="importlib.resources.abc#importlib.resources.abc.Traversable" title="importlib.resources.abc.Traversable"><code>Traversable</code></a> object representing a file or directory, typically from <a class="reference internal" href="#importlib.resources.files" title="importlib.resources.files"><code>importlib.resources.files()</code></a>, return a context manager for use in a <a class="reference internal" href="../reference/compound_stmts#with"><code>with</code></a> statement. The context manager provides a <a class="reference internal" href="pathlib#pathlib.Path" title="pathlib.Path"><code>pathlib.Path</code></a> object.</p> <p>Exiting the context manager cleans up any temporary file or directory created when the resource was extracted from e.g. a zip file.</p> <p>Use <code>as_file</code> when the Traversable methods (<code>read_text</code>, etc) are insufficient and an actual file or directory on the file system is required.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.9.</span></p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.12: </span>Added support for <em>traversable</em> representing a directory.</p> </div> </dd>
</dl> <section id="deprecated-functions"> <h2>Deprecated functions</h2> <p>An older, deprecated set of functions is still available, but is scheduled for removal in a future version of Python. The main drawback of these functions is that they do not support directories: they assume all resources are located directly within a <em>package</em>.</p> <dl class="py data"> <dt class="sig sig-object py" id="importlib.resources.Package">
<code>importlib.resources.Package</code> </dt> <dd> <p>Whenever a function accepts a <code>Package</code> argument, you can pass in either a <a class="reference internal" href="types#types.ModuleType" title="types.ModuleType"><code>module object</code></a> or a module name as a string. You can only pass module objects whose <code>__spec__.submodule_search_locations</code> is not <code>None</code>.</p> <p>The <code>Package</code> type is defined as <code>Union[str, ModuleType]</code>.</p>  <div class="deprecated"> <p><span class="versionmodified deprecated">Deprecated since version 3.12.</span></p> </div> </dd>
</dl> <dl class="py data"> <dt class="sig sig-object py" id="importlib.resources.Resource">
<code>importlib.resources.Resource</code> </dt> <dd>
<p>For <em>resource</em> arguments of the functions below, you can pass in the name of a resource as a string or a <a class="reference internal" href="os#os.PathLike" title="os.PathLike"><code>path-like object</code></a>.</p> <p>The <code>Resource</code> type is defined as <code>Union[str, os.PathLike]</code>.</p> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="importlib.resources.open_binary">
<code>importlib.resources.open_binary(package, resource)</code> </dt> <dd>
<p>Open for binary reading the <em>resource</em> within <em>package</em>.</p> <p><em>package</em> is either a name or a module object which conforms to the <code>Package</code> requirements. <em>resource</em> is the name of the resource to open within <em>package</em>; it may not contain path separators and it may not have sub-resources (i.e. it cannot be a directory). This function returns a <code>typing.BinaryIO</code> instance, a binary I/O stream open for reading.</p> <div class="deprecated"> <p><span class="versionmodified deprecated">Deprecated since version 3.11: </span>Calls to this function can be replaced by:</p> <pre data-language="python">files(package).joinpath(resource).open('rb')
</pre> </div> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="importlib.resources.open_text">
<code>importlib.resources.open_text(package, resource, encoding='utf-8', errors='strict')</code> </dt> <dd>
<p>Open for text reading the <em>resource</em> within <em>package</em>. By default, the resource is opened for reading as UTF-8.</p> <p><em>package</em> is either a name or a module object which conforms to the <code>Package</code> requirements. <em>resource</em> is the name of the resource to open within <em>package</em>; it may not contain path separators and it may not have sub-resources (i.e. it cannot be a directory). <em>encoding</em> and <em>errors</em> have the same meaning as with built-in <a class="reference internal" href="functions#open" title="open"><code>open()</code></a>.</p> <p>This function returns a <code>typing.TextIO</code> instance, a text I/O stream open for reading.</p> <div class="deprecated"> <p><span class="versionmodified deprecated">Deprecated since version 3.11: </span>Calls to this function can be replaced by:</p> <pre data-language="python">files(package).joinpath(resource).open('r', encoding=encoding)
</pre> </div> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="importlib.resources.read_binary">
<code>importlib.resources.read_binary(package, resource)</code> </dt> <dd>
<p>Read and return the contents of the <em>resource</em> within <em>package</em> as <code>bytes</code>.</p> <p><em>package</em> is either a name or a module object which conforms to the <code>Package</code> requirements. <em>resource</em> is the name of the resource to open within <em>package</em>; it may not contain path separators and it may not have sub-resources (i.e. it cannot be a directory). This function returns the contents of the resource as <a class="reference internal" href="stdtypes#bytes" title="bytes"><code>bytes</code></a>.</p> <div class="deprecated"> <p><span class="versionmodified deprecated">Deprecated since version 3.11: </span>Calls to this function can be replaced by:</p> <pre data-language="python">files(package).joinpath(resource).read_bytes()
</pre> </div> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="importlib.resources.read_text">
<code>importlib.resources.read_text(package, resource, encoding='utf-8', errors='strict')</code> </dt> <dd>
<p>Read and return the contents of <em>resource</em> within <em>package</em> as a <code>str</code>. By default, the contents are read as strict UTF-8.</p> <p><em>package</em> is either a name or a module object which conforms to the <code>Package</code> requirements. <em>resource</em> is the name of the resource to open within <em>package</em>; it may not contain path separators and it may not have sub-resources (i.e. it cannot be a directory). <em>encoding</em> and <em>errors</em> have the same meaning as with built-in <a class="reference internal" href="functions#open" title="open"><code>open()</code></a>. This function returns the contents of the resource as <a class="reference internal" href="stdtypes#str" title="str"><code>str</code></a>.</p> <div class="deprecated"> <p><span class="versionmodified deprecated">Deprecated since version 3.11: </span>Calls to this function can be replaced by:</p> <pre data-language="python">files(package).joinpath(resource).read_text(encoding=encoding)
</pre> </div> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="importlib.resources.path">
<code>importlib.resources.path(package, resource)</code> </dt> <dd>
<p>Return the path to the <em>resource</em> as an actual file system path. This function returns a context manager for use in a <a class="reference internal" href="../reference/compound_stmts#with"><code>with</code></a> statement. The context manager provides a <a class="reference internal" href="pathlib#pathlib.Path" title="pathlib.Path"><code>pathlib.Path</code></a> object.</p> <p>Exiting the context manager cleans up any temporary file created when the resource needs to be extracted from e.g. a zip file.</p> <p><em>package</em> is either a name or a module object which conforms to the <code>Package</code> requirements. <em>resource</em> is the name of the resource to open within <em>package</em>; it may not contain path separators and it may not have sub-resources (i.e. it cannot be a directory).</p> <div class="deprecated"> <p><span class="versionmodified deprecated">Deprecated since version 3.11: </span>Calls to this function can be replaced using <a class="reference internal" href="#importlib.resources.as_file" title="importlib.resources.as_file"><code>as_file()</code></a>:</p> <pre data-language="python">as_file(files(package).joinpath(resource))
</pre> </div> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="importlib.resources.is_resource">
<code>importlib.resources.is_resource(package, name)</code> </dt> <dd>
<p>Return <code>True</code> if there is a resource named <em>name</em> in the package, otherwise <code>False</code>. This function does not consider directories to be resources. <em>package</em> is either a name or a module object which conforms to the <code>Package</code> requirements.</p> <div class="deprecated"> <p><span class="versionmodified deprecated">Deprecated since version 3.11: </span>Calls to this function can be replaced by:</p> <pre data-language="python">files(package).joinpath(resource).is_file()
</pre> </div> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="importlib.resources.contents">
<code>importlib.resources.contents(package)</code> </dt> <dd>
<p>Return an iterable over the named items within the package. The iterable returns <a class="reference internal" href="stdtypes#str" title="str"><code>str</code></a> resources (e.g. files) and non-resources (e.g. directories). The iterable does not recurse into subdirectories.</p> <p><em>package</em> is either a name or a module object which conforms to the <code>Package</code> requirements.</p> <div class="deprecated"> <p><span class="versionmodified deprecated">Deprecated since version 3.11: </span>Calls to this function can be replaced by:</p> <pre data-language="python">(resource.name for resource in files(package).iterdir() if resource.is_file())
</pre> </div> </dd>
</dl> </section> <div class="_attribution">
  <p class="_attribution-p">
    &copy; 2001&ndash;2023 Python Software Foundation<br>Licensed under the PSF License.<br>
    <a href="https://docs.python.org/3.12/library/importlib.resources.html" class="_attribution-link">https://docs.python.org/3.12/library/importlib.resources.html</a>
  </p>
</div>