Team Ai
Apppublic

parthtamu/rag-code-assistant

sourceHugging Faceupdated 7mo agoView on Hugging Face
0likes
importlib.resources.html627 linesDownload Raw Back to docs
1<!DOCTYPE html>2 3<html lang="en" data-content_root="../">4  <head>5    <meta charset="utf-8" />6    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />7<meta property="og:title" content="importlib.resources – Package resource reading, opening and access" />8<meta property="og:type" content="website" />9<meta property="og:url" content="https://docs.python.org/3/library/importlib.resources.html" />10<meta property="og:site_name" content="Python documentation" />11<meta property="og:description" content="Source code: Lib/importlib/resources/__init__.py This module leverages Python’s import system to provide access to resources within packages. “Resources” are file-like resources associated with a m..." />12<meta property="og:image:width" content="1146" />13<meta property="og:image:height" content="600" />14<meta property="og:image" content="https://docs.python.org/3.15/_images/social_previews/summary_library_importlib.resources_c7b7c27d.png" />15<meta property="og:image:alt" content="Source code: Lib/importlib/resources/__init__.py This module leverages Python’s import system to provide access to resources within packages. “Resources” are file-like resources associated with a m..." />16<meta name="description" content="Source code: Lib/importlib/resources/__init__.py This module leverages Python’s import system to provide access to resources within packages. “Resources” are file-like resources associated with a m..." />17<meta name="twitter:card" content="summary_large_image" />18<meta name="theme-color" content="#3776ab">19 20    <title>importlib.resources – Package resource reading, opening and access &#8212; Python 3.15.0a6 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">21    22    <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />23    <link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />24    <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=89a2f22a" />25    <link rel="stylesheet" type="text/css" href="../_static/profiling-sampling-visualization.css?v=0c2600ae" />26    <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=5349f25f" />27    28    <script src="../_static/documentation_options.js?v=6b7c9ff5"></script>29    <script src="../_static/doctools.js?v=9bcbadda"></script>30    <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>31    <script src="../_static/profiling-sampling-visualization.js?v=9811ed04"></script>32    33    <script src="../_static/sidebar.js"></script>34    35    <link rel="search" type="application/opensearchdescription+xml"36          title="Search within Python 3.15.0a6 documentation"37          href="../_static/opensearch.xml"/>38    <link rel="author" title="About these documents" href="../about.html" />39    <link rel="index" title="Index" href="../genindex.html" />40    <link rel="search" title="Search" href="../search.html" />41    <link rel="copyright" title="Copyright" href="../copyright.html" />42    <link rel="next" title="importlib.resources.abc – Abstract base classes for resources" href="importlib.resources.abc.html" />43    <link rel="prev" title="importlib — The implementation of import" href="importlib.html" />44    45      46      <script defer file-types="bz2,epub,zip" data-domain="docs.python.org" src="https://analytics.python.org/js/script.file-downloads.outbound-links.js"></script>47      48      <link rel="canonical" href="https://docs.python.org/3/library/importlib.resources.html">49      50    51 52    53    <style>54      @media only screen {55        table.full-width-table {56            width: 100%;57        }58      }59    </style>60<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">61    <link rel="shortcut icon" type="image/png" href="../_static/py.svg">62            <script type="text/javascript" src="../_static/copybutton.js"></script>63            <script type="text/javascript" src="../_static/menu.js"></script>64            <script type="text/javascript" src="../_static/search-focus.js"></script>65            <script type="text/javascript" src="../_static/themetoggle.js"></script> 66            <script type="text/javascript" src="../_static/rtd_switcher.js"></script>67            <meta name="readthedocs-addons-api-version" content="1">68 69  </head>70<body>71<div class="mobile-nav">72    <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"73           aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu">74    <nav class="nav-content" role="navigation">75        <label for="menuToggler" class="toggler__label">76            <span></span>77        </label>78        <span class="nav-items-wrapper">79            <a href="https://www.python.org/" class="nav-logo">80                <img src="../_static/py.svg" alt="Python logo">81            </a>82            <span class="version_switcher_placeholder"></span>83            <form role="search" class="search" action="../search.html" method="get">84                <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">85                    <path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>86                </svg>87                <input placeholder="Quick search" aria-label="Quick search" type="search" name="q">88                <input type="submit" value="Go">89            </form>90        </span>91    </nav>92    <div class="menu-wrapper">93        <nav class="menu" role="navigation" aria-label="main navigation">94            <div class="language_switcher_placeholder"></div>95            96<label class="theme-selector-label">97    Theme98    <select class="theme-selector" oninput="activateTheme(this.value)">99        <option value="auto" selected>Auto</option>100        <option value="light">Light</option>101        <option value="dark">Dark</option>102    </select>103</label>104  <div>105    <h3><a href="../contents.html">Table of Contents</a></h3>106    <ul>107<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">importlib.resources</span></code> – Package resource reading, opening and access</a><ul>108<li><a class="reference internal" href="#functional-api">Functional API</a></li>109</ul>110</li>111</ul>112 113  </div>114  <div>115    <h4>Previous topic</h4>116    <p class="topless"><a href="importlib.html"117                          title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">importlib</span></code> — The implementation of <code class="xref std std-keyword docutils literal notranslate"><span class="pre">import</span></code></a></p>118  </div>119  <div>120    <h4>Next topic</h4>121    <p class="topless"><a href="importlib.resources.abc.html"122                          title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">importlib.resources.abc</span></code> – Abstract base classes for resources</a></p>123  </div>124  <script>125    document.addEventListener('DOMContentLoaded', () => {126        const title = document.querySelector('meta[property="og:title"]').content;127        const elements = document.querySelectorAll('.improvepage');128        const pageurl = window.location.href.split('?')[0];129        elements.forEach(element => {130            const url = new URL(element.href.split('?')[0].replace("-nojs", ""));131            url.searchParams.set('pagetitle', title);132            url.searchParams.set('pageurl', pageurl);133            url.searchParams.set('pagesource', "library/importlib.resources.rst");134            element.href = url.toString();135        });136    });137  </script>138  <div role="note" aria-label="source link">139    <h3>This page</h3>140    <ul class="this-page-menu">141      <li><a href="../bugs.html">Report a bug</a></li>142      <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>143      <li>144        <a href="https://github.com/python/cpython/blob/main/Doc/library/importlib.resources.rst?plain=1"145            rel="nofollow">Show source146        </a>147      </li>148      149    </ul>150  </div>151        </nav>152    </div>153</div>154 155  156    <div class="related" role="navigation" aria-label="Related">157      <h3>Navigation</h3>158      <ul>159        <li class="right" style="margin-right: 10px">160          <a href="../genindex.html" title="General Index"161             accesskey="I">index</a></li>162        <li class="right" >163          <a href="../py-modindex.html" title="Python Module Index"164             >modules</a> |</li>165        <li class="right" >166          <a href="importlib.resources.abc.html" title="importlib.resources.abc – Abstract base classes for resources"167             accesskey="N">next</a> |</li>168        <li class="right" >169          <a href="importlib.html" title="importlib — The implementation of import"170             accesskey="P">previous</a> |</li>171 172          <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>173          <li><a href="https://www.python.org/">Python</a> &#187;</li>174          <li class="switchers">175            <div class="language_switcher_placeholder"></div>176            <div class="version_switcher_placeholder"></div>177          </li>178          <li>179              180          </li>181    <li id="cpython-language-and-version">182      <a href="../index.html">3.15.0a6 Documentation</a> &#187;183    </li>184 185          <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>186          <li class="nav-item nav-item-2"><a href="modules.html" accesskey="U">Importing Modules</a> &#187;</li>187        <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">importlib.resources</span></code> – Package resource reading, opening and access</a></li>188                <li class="right">189                    190 191    <div class="inline-search" role="search">192        <form class="inline-search" action="../search.html" method="get">193          <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">194          <input type="submit" value="Go">195        </form>196    </div>197                     |198                </li>199            <li class="right">200<label class="theme-selector-label">201    Theme202    <select class="theme-selector" oninput="activateTheme(this.value)">203        <option value="auto" selected>Auto</option>204        <option value="light">Light</option>205        <option value="dark">Dark</option>206    </select>207</label> |</li>208            209      </ul>210    </div>    211 212    <div class="document">213      <div class="documentwrapper">214        <div class="bodywrapper">215          <div class="body" role="main">216            217  <section id="module-importlib.resources">218<span id="importlib-resources-package-resource-reading-opening-and-access"></span><h1><code class="xref py py-mod docutils literal notranslate"><span class="pre">importlib.resources</span></code> – Package resource reading, opening and access<a class="headerlink" href="#module-importlib.resources" title="Link to this heading">¶</a></h1>219<p><strong>Source code:</strong> <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/main/Lib/importlib/resources/__init__.py">Lib/importlib/resources/__init__.py</a></p>220<hr class="docutils" />221<div class="versionadded">222<p><span class="versionmodified added">Added in version 3.7.</span></p>223</div>224<p>This module leverages Python’s import system to provide access to <em>resources</em>225within <em>packages</em>.</p>226<p>“Resources” are file-like resources associated with a module or package in227Python. The resources may be contained directly in a package, within a228subdirectory contained in that package, or adjacent to modules outside a229package. Resources may be text or binary. As a result, a package’s Python230module sources (.py), compilation artifacts (pycache), and installation231artifacts (like <a class="reference internal" href="os.path.html#os.path.isreserved" title="os.path.isreserved"><code class="xref py py-func docutils literal notranslate"><span class="pre">reserved</span> <span class="pre">filenames</span></code></a>232in directories) are technically de-facto resources of that package.233In practice, however, resources are primarily those non-Python artifacts234exposed specifically by the package author.</p>235<p>Resources can be opened or read in either binary or text mode.</p>236<p>Resources are roughly akin to files inside directories, though it’s important237to keep in mind that this is just a metaphor.  Resources and packages <strong>do238not</strong> have to exist as physical files and directories on the file system:239for example, a package and its resources can be imported from a zip file using240<a class="reference internal" href="zipimport.html#module-zipimport" title="zipimport: Support for importing Python modules from ZIP archives."><code class="xref py py-mod docutils literal notranslate"><span class="pre">zipimport</span></code></a>.</p>241<div class="admonition note">242<p class="admonition-title">Note</p>243<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">Basic244Resource Access</a>245without the performance overhead of that package.  This makes reading246resources included in packages easier, with more stable and consistent247semantics.</p>248<p>The standalone backport of this module provides more information249on <a class="reference external" href="https://importlib-resources.readthedocs.io/en/latest/using.html">using importlib.resources</a> and250<a class="reference external" href="https://importlib-resources.readthedocs.io/en/latest/migration.html">migrating from pkg_resources to importlib.resources</a>.</p>251</div>252<p><a class="reference internal" href="importlib.html#importlib.abc.Loader" title="importlib.abc.Loader"><code class="xref py py-class docutils literal notranslate"><span class="pre">Loaders</span></code></a> that wish to support resource reading should implement a253<code class="docutils literal notranslate"><span class="pre">get_resource_reader(fullname)</span></code> method as specified by254<a class="reference internal" href="importlib.resources.abc.html#importlib.resources.abc.ResourceReader" title="importlib.resources.abc.ResourceReader"><code class="xref py py-class docutils literal notranslate"><span class="pre">importlib.resources.abc.ResourceReader</span></code></a>.</p>255<dl class="py class">256<dt class="sig sig-object py" id="importlib.resources.Anchor">257<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">importlib.resources.</span></span><span class="sig-name descname"><span class="pre">Anchor</span></span><a class="headerlink" href="#importlib.resources.Anchor" title="Link to this definition">¶</a></dt>258<dd><p>Represents an anchor for resources, either a <a class="reference internal" href="types.html#types.ModuleType" title="types.ModuleType"><code class="xref py py-class docutils literal notranslate"><span class="pre">module</span> <span class="pre">object</span></code></a> or a module name as a string. Defined as259<code class="docutils literal notranslate"><span class="pre">Union[str,</span> <span class="pre">ModuleType]</span></code>.</p>260</dd></dl>261 262<dl class="py function">263<dt class="sig sig-object py" id="importlib.resources.files">264<span class="sig-prename descclassname"><span class="pre">importlib.resources.</span></span><span class="sig-name descname"><span class="pre">files</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">anchor</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="#importlib.resources.Anchor" title="importlib.resources.Anchor"><span class="pre">Anchor</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference internal" href="constants.html#None" title="None"><span class="pre">None</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#importlib.resources.files" title="Link to this definition">¶</a></dt>265<dd><p>Returns a <a class="reference internal" href="importlib.resources.abc.html#importlib.resources.abc.Traversable" title="importlib.resources.abc.Traversable"><code class="xref py py-class docutils literal notranslate"><span class="pre">Traversable</span></code></a> object266representing the resource container (think directory) and its resources267(think files). A Traversable may contain other containers (think268subdirectories).</p>269<p><em>anchor</em> is an optional <a class="reference internal" href="#importlib.resources.Anchor" title="importlib.resources.Anchor"><code class="xref py py-class docutils literal notranslate"><span class="pre">Anchor</span></code></a>. If the anchor is a270package, resources are resolved from that package. If a module,271resources are resolved adjacent to that module (in the same package272or the package root). If the anchor is omitted, the caller’s module273is used.</p>274<div class="versionadded">275<p><span class="versionmodified added">Added in version 3.9.</span></p>276</div>277<div class="versionchanged">278<p><span class="versionmodified changed">Changed in version 3.12: </span><em>package</em> parameter was renamed to <em>anchor</em>.279<em>package</em> was still accepted, but deprecated.</p>280</div>281<div class="versionchanged">282<p><span class="versionmodified changed">Changed in version 3.15: </span><em>package</em> parameter was fully removed. <em>anchor</em> can now be a283non-package module and if omitted will default to the caller’s module.284<em>package</em> is no longer accepted since Python 3.15. Consider passing the285anchor positionally or using <code class="docutils literal notranslate"><span class="pre">importlib_resources</span> <span class="pre">&gt;=</span> <span class="pre">5.10</span></code> for a286compatible interface on older Pythons.</p>287</div>288</dd></dl>289 290<dl class="py function">291<dt class="sig sig-object py" id="importlib.resources.as_file">292<span class="sig-prename descclassname"><span class="pre">importlib.resources.</span></span><span class="sig-name descname"><span class="pre">as_file</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">traversable</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#importlib.resources.as_file" title="Link to this definition">¶</a></dt>293<dd><p>Given a <a class="reference internal" href="importlib.resources.abc.html#importlib.resources.abc.Traversable" title="importlib.resources.abc.Traversable"><code class="xref py py-class docutils literal notranslate"><span class="pre">Traversable</span></code></a> object representing294a file or directory, typically from <a class="reference internal" href="#importlib.resources.files" title="importlib.resources.files"><code class="xref py py-func docutils literal notranslate"><span class="pre">importlib.resources.files()</span></code></a>,295return a context manager for use in a <a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> statement.296The context manager provides a <a class="reference internal" href="pathlib.html#pathlib.Path" title="pathlib.Path"><code class="xref py py-class docutils literal notranslate"><span class="pre">pathlib.Path</span></code></a> object.</p>297<p>Exiting the context manager cleans up any temporary file or directory298created when the resource was extracted from e.g. a zip file.</p>299<p>Use <code class="docutils literal notranslate"><span class="pre">as_file</span></code> when the Traversable methods300(<code class="docutils literal notranslate"><span class="pre">read_text</span></code>, etc) are insufficient and an actual file or directory on301the file system is required.</p>302<div class="versionadded">303<p><span class="versionmodified added">Added in version 3.9.</span></p>304</div>305<div class="versionchanged">306<p><span class="versionmodified changed">Changed in version 3.12: </span>Added support for <em>traversable</em> representing a directory.</p>307</div>308</dd></dl>309 310<section id="functional-api">311<span id="importlib-resources-functional"></span><h2>Functional API<a class="headerlink" href="#functional-api" title="Link to this heading">¶</a></h2>312<p>A set of simplified, backwards-compatible helpers is available.313These allow common operations in a single function call.</p>314<p>For all the following functions:</p>315<ul>316<li><p><em>anchor</em> is an <a class="reference internal" href="#importlib.resources.Anchor" title="importlib.resources.Anchor"><code class="xref py py-class docutils literal notranslate"><span class="pre">Anchor</span></code></a>,317as in <a class="reference internal" href="#importlib.resources.files" title="importlib.resources.files"><code class="xref py py-func docutils literal notranslate"><span class="pre">files()</span></code></a>.318Unlike in <code class="docutils literal notranslate"><span class="pre">files</span></code>, it may not be omitted.</p></li>319<li><p><em>path_names</em> are components of a resource’s path name, relative to320the anchor.321For example, to get the text of resource named <code class="docutils literal notranslate"><span class="pre">info.txt</span></code>, use:</p>322<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">importlib</span><span class="o">.</span><span class="n">resources</span><span class="o">.</span><span class="n">read_text</span><span class="p">(</span><span class="n">my_module</span><span class="p">,</span> <span class="s2">&quot;info.txt&quot;</span><span class="p">)</span>323</pre></div>324</div>325<p>Like <a class="reference internal" href="importlib.resources.abc.html#importlib.resources.abc.Traversable" title="importlib.resources.abc.Traversable"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Traversable.joinpath</span></code></a>,326The individual components should use forward slashes (<code class="docutils literal notranslate"><span class="pre">/</span></code>)327as path separators.328For example, the following are equivalent:</p>329<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">importlib</span><span class="o">.</span><span class="n">resources</span><span class="o">.</span><span class="n">read_binary</span><span class="p">(</span><span class="n">my_module</span><span class="p">,</span> <span class="s2">&quot;pics/painting.png&quot;</span><span class="p">)</span>330<span class="n">importlib</span><span class="o">.</span><span class="n">resources</span><span class="o">.</span><span class="n">read_binary</span><span class="p">(</span><span class="n">my_module</span><span class="p">,</span> <span class="s2">&quot;pics&quot;</span><span class="p">,</span> <span class="s2">&quot;painting.png&quot;</span><span class="p">)</span>331</pre></div>332</div>333<p>For backward compatibility reasons, functions that read text require334an explicit <em>encoding</em> argument if multiple <em>path_names</em> are given.335For example, to get the text of <code class="docutils literal notranslate"><span class="pre">info/chapter1.txt</span></code>, use:</p>336<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">importlib</span><span class="o">.</span><span class="n">resources</span><span class="o">.</span><span class="n">read_text</span><span class="p">(</span><span class="n">my_module</span><span class="p">,</span> <span class="s2">&quot;info&quot;</span><span class="p">,</span> <span class="s2">&quot;chapter1.txt&quot;</span><span class="p">,</span>337                              <span class="n">encoding</span><span class="o">=</span><span class="s1">&#39;utf-8&#39;</span><span class="p">)</span>338</pre></div>339</div>340</li>341</ul>342<dl class="py function">343<dt class="sig sig-object py" id="importlib.resources.open_binary">344<span class="sig-prename descclassname"><span class="pre">importlib.resources.</span></span><span class="sig-name descname"><span class="pre">open_binary</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">anchor</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">path_names</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#importlib.resources.open_binary" title="Link to this definition">¶</a></dt>345<dd><p>Open the named resource for binary reading.</p>346<p>See <a class="reference internal" href="#importlib-resources-functional"><span class="std std-ref">the introduction</span></a> for347details on <em>anchor</em> and <em>path_names</em>.</p>348<p>This function returns a <a class="reference internal" href="typing.html#typing.BinaryIO" title="typing.BinaryIO"><code class="xref py py-class docutils literal notranslate"><span class="pre">BinaryIO</span></code></a> object,349that is, a binary stream open for reading.</p>350<p>This function is roughly equivalent to:</p>351<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">files</span><span class="p">(</span><span class="n">anchor</span><span class="p">)</span><span class="o">.</span><span class="n">joinpath</span><span class="p">(</span><span class="o">*</span><span class="n">path_names</span><span class="p">)</span><span class="o">.</span><span class="n">open</span><span class="p">(</span><span class="s1">&#39;rb&#39;</span><span class="p">)</span>352</pre></div>353</div>354<div class="versionchanged">355<p><span class="versionmodified changed">Changed in version 3.13: </span>Multiple <em>path_names</em> are accepted.</p>356</div>357</dd></dl>358 359<dl class="py function">360<dt class="sig sig-object py" id="importlib.resources.open_text">361<span class="sig-prename descclassname"><span class="pre">importlib.resources.</span></span><span class="sig-name descname"><span class="pre">open_text</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">anchor</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">path_names</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">encoding</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'utf-8'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">errors</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'strict'</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#importlib.resources.open_text" title="Link to this definition">¶</a></dt>362<dd><p>Open the named resource for text reading.363By default, the contents are read as strict UTF-8.</p>364<p>See <a class="reference internal" href="#importlib-resources-functional"><span class="std std-ref">the introduction</span></a> for365details on <em>anchor</em> and <em>path_names</em>.366<em>encoding</em> and <em>errors</em> have the same meaning as in built-in <a class="reference internal" href="functions.html#open" title="open"><code class="xref py py-func docutils literal notranslate"><span class="pre">open()</span></code></a>.</p>367<p>For backward compatibility reasons, the <em>encoding</em> argument must be given368explicitly if there are multiple <em>path_names</em>.369This limitation is scheduled to be removed in Python 3.15.</p>370<p>This function returns a <a class="reference internal" href="typing.html#typing.TextIO" title="typing.TextIO"><code class="xref py py-class docutils literal notranslate"><span class="pre">TextIO</span></code></a> object,371that is, a text stream open for reading.</p>372<p>This function is roughly equivalent to:</p>373<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">files</span><span class="p">(</span><span class="n">anchor</span><span class="p">)</span><span class="o">.</span><span class="n">joinpath</span><span class="p">(</span><span class="o">*</span><span class="n">path_names</span><span class="p">)</span><span class="o">.</span><span class="n">open</span><span class="p">(</span><span class="s1">&#39;r&#39;</span><span class="p">,</span> <span class="n">encoding</span><span class="o">=</span><span class="n">encoding</span><span class="p">)</span>374</pre></div>375</div>376<div class="versionchanged">377<p><span class="versionmodified changed">Changed in version 3.13: </span>Multiple <em>path_names</em> are accepted.378<em>encoding</em> and <em>errors</em> must be given as keyword arguments.</p>379</div>380</dd></dl>381 382<dl class="py function">383<dt class="sig sig-object py" id="importlib.resources.read_binary">384<span class="sig-prename descclassname"><span class="pre">importlib.resources.</span></span><span class="sig-name descname"><span class="pre">read_binary</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">anchor</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">path_names</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#importlib.resources.read_binary" title="Link to this definition">¶</a></dt>385<dd><p>Read and return the contents of the named resource as <a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a>.</p>386<p>See <a class="reference internal" href="#importlib-resources-functional"><span class="std std-ref">the introduction</span></a> for387details on <em>anchor</em> and <em>path_names</em>.</p>388<p>This function is roughly equivalent to:</p>389<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">files</span><span class="p">(</span><span class="n">anchor</span><span class="p">)</span><span class="o">.</span><span class="n">joinpath</span><span class="p">(</span><span class="o">*</span><span class="n">path_names</span><span class="p">)</span><span class="o">.</span><span class="n">read_bytes</span><span class="p">()</span>390</pre></div>391</div>392<div class="versionchanged">393<p><span class="versionmodified changed">Changed in version 3.13: </span>Multiple <em>path_names</em> are accepted.</p>394</div>395</dd></dl>396 397<dl class="py function">398<dt class="sig sig-object py" id="importlib.resources.read_text">399<span class="sig-prename descclassname"><span class="pre">importlib.resources.</span></span><span class="sig-name descname"><span class="pre">read_text</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">anchor</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">path_names</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">encoding</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'utf-8'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">errors</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'strict'</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#importlib.resources.read_text" title="Link to this definition">¶</a></dt>400<dd><p>Read and return the contents of the named resource as <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>.401By default, the contents are read as strict UTF-8.</p>402<p>See <a class="reference internal" href="#importlib-resources-functional"><span class="std std-ref">the introduction</span></a> for403details on <em>anchor</em> and <em>path_names</em>.404<em>encoding</em> and <em>errors</em> have the same meaning as in built-in <a class="reference internal" href="functions.html#open" title="open"><code class="xref py py-func docutils literal notranslate"><span class="pre">open()</span></code></a>.</p>405<p>For backward compatibility reasons, the <em>encoding</em> argument must be given406explicitly if there are multiple <em>path_names</em>.407This limitation is scheduled to be removed in Python 3.15.</p>408<p>This function is roughly equivalent to:</p>409<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">files</span><span class="p">(</span><span class="n">anchor</span><span class="p">)</span><span class="o">.</span><span class="n">joinpath</span><span class="p">(</span><span class="o">*</span><span class="n">path_names</span><span class="p">)</span><span class="o">.</span><span class="n">read_text</span><span class="p">(</span><span class="n">encoding</span><span class="o">=</span><span class="n">encoding</span><span class="p">)</span>410</pre></div>411</div>412<div class="versionchanged">413<p><span class="versionmodified changed">Changed in version 3.13: </span>Multiple <em>path_names</em> are accepted.414<em>encoding</em> and <em>errors</em> must be given as keyword arguments.</p>415</div>416</dd></dl>417 418<dl class="py function">419<dt class="sig sig-object py" id="importlib.resources.path">420<span class="sig-prename descclassname"><span class="pre">importlib.resources.</span></span><span class="sig-name descname"><span class="pre">path</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">anchor</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">path_names</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#importlib.resources.path" title="Link to this definition">¶</a></dt>421<dd><p>Provides the path to the <em>resource</em> as an actual file system path.  This422function returns a context manager for use in a <a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> statement.423The context manager provides a <a class="reference internal" href="pathlib.html#pathlib.Path" title="pathlib.Path"><code class="xref py py-class docutils literal notranslate"><span class="pre">pathlib.Path</span></code></a> object.</p>424<p>Exiting the context manager cleans up any temporary files created, e.g.425when the resource needs to be extracted from a zip file.</p>426<p>For example, the <a class="reference internal" href="pathlib.html#pathlib.Path.stat" title="pathlib.Path.stat"><code class="xref py py-meth docutils literal notranslate"><span class="pre">stat()</span></code></a> method requires427an actual file system path; it can be used like this:</p>428<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="n">importlib</span><span class="o">.</span><span class="n">resources</span><span class="o">.</span><span class="n">path</span><span class="p">(</span><span class="n">anchor</span><span class="p">,</span> <span class="s2">&quot;resource.txt&quot;</span><span class="p">)</span> <span class="k">as</span> <span class="n">fspath</span><span class="p">:</span>429    <span class="n">result</span> <span class="o">=</span> <span class="n">fspath</span><span class="o">.</span><span class="n">stat</span><span class="p">()</span>430</pre></div>431</div>432<p>See <a class="reference internal" href="#importlib-resources-functional"><span class="std std-ref">the introduction</span></a> for433details on <em>anchor</em> and <em>path_names</em>.</p>434<p>This function is roughly equivalent to:</p>435<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">as_file</span><span class="p">(</span><span class="n">files</span><span class="p">(</span><span class="n">anchor</span><span class="p">)</span><span class="o">.</span><span class="n">joinpath</span><span class="p">(</span><span class="o">*</span><span class="n">path_names</span><span class="p">))</span>436</pre></div>437</div>438<div class="versionchanged">439<p><span class="versionmodified changed">Changed in version 3.13: </span>Multiple <em>path_names</em> are accepted.440<em>encoding</em> and <em>errors</em> must be given as keyword arguments.</p>441</div>442</dd></dl>443 444<dl class="py function">445<dt class="sig sig-object py" id="importlib.resources.is_resource">446<span class="sig-prename descclassname"><span class="pre">importlib.resources.</span></span><span class="sig-name descname"><span class="pre">is_resource</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">anchor</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">path_names</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#importlib.resources.is_resource" title="Link to this definition">¶</a></dt>447<dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if the named resource exists, otherwise <code class="docutils literal notranslate"><span class="pre">False</span></code>.448This function does not consider directories to be resources.</p>449<p>See <a class="reference internal" href="#importlib-resources-functional"><span class="std std-ref">the introduction</span></a> for450details on <em>anchor</em> and <em>path_names</em>.</p>451<p>This function is roughly equivalent to:</p>452<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">files</span><span class="p">(</span><span class="n">anchor</span><span class="p">)</span><span class="o">.</span><span class="n">joinpath</span><span class="p">(</span><span class="o">*</span><span class="n">path_names</span><span class="p">)</span><span class="o">.</span><span class="n">is_file</span><span class="p">()</span>453</pre></div>454</div>455<div class="versionchanged">456<p><span class="versionmodified changed">Changed in version 3.13: </span>Multiple <em>path_names</em> are accepted.</p>457</div>458</dd></dl>459 460<dl class="py function">461<dt class="sig sig-object py" id="importlib.resources.contents">462<span class="sig-prename descclassname"><span class="pre">importlib.resources.</span></span><span class="sig-name descname"><span class="pre">contents</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">anchor</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">path_names</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#importlib.resources.contents" title="Link to this definition">¶</a></dt>463<dd><p>Return an iterable over the named items within the package or path.464The iterable returns names of resources (e.g. files) and non-resources465(e.g. directories) as <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>.466The iterable does not recurse into subdirectories.</p>467<p>See <a class="reference internal" href="#importlib-resources-functional"><span class="std std-ref">the introduction</span></a> for468details on <em>anchor</em> and <em>path_names</em>.</p>469<p>This function is roughly equivalent to:</p>470<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">for</span> <span class="n">resource</span> <span class="ow">in</span> <span class="n">files</span><span class="p">(</span><span class="n">anchor</span><span class="p">)</span><span class="o">.</span><span class="n">joinpath</span><span class="p">(</span><span class="o">*</span><span class="n">path_names</span><span class="p">)</span><span class="o">.</span><span class="n">iterdir</span><span class="p">():</span>471    <span class="k">yield</span> <span class="n">resource</span><span class="o">.</span><span class="n">name</span>472</pre></div>473</div>474<div class="deprecated">475<p><span class="versionmodified deprecated">Deprecated since version 3.11: </span>Prefer <code class="docutils literal notranslate"><span class="pre">iterdir()</span></code> as above, which offers more control over the476results and richer functionality.</p>477</div>478</dd></dl>479 480</section>481</section>482 483 484            <div class="clearer"></div>485          </div>486        </div>487      </div>488      <div class="sphinxsidebar" role="navigation" aria-label="Main">489        <div class="sphinxsidebarwrapper">490  <div>491    <h3><a href="../contents.html">Table of Contents</a></h3>492    <ul>493<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">importlib.resources</span></code> – Package resource reading, opening and access</a><ul>494<li><a class="reference internal" href="#functional-api">Functional API</a></li>495</ul>496</li>497</ul>498 499  </div>500  <div>501    <h4>Previous topic</h4>502    <p class="topless"><a href="importlib.html"503                          title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">importlib</span></code> — The implementation of <code class="xref std std-keyword docutils literal notranslate"><span class="pre">import</span></code></a></p>504  </div>505  <div>506    <h4>Next topic</h4>507    <p class="topless"><a href="importlib.resources.abc.html"508                          title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">importlib.resources.abc</span></code> – Abstract base classes for resources</a></p>509  </div>510  <script>511    document.addEventListener('DOMContentLoaded', () => {512        const title = document.querySelector('meta[property="og:title"]').content;513        const elements = document.querySelectorAll('.improvepage');514        const pageurl = window.location.href.split('?')[0];515        elements.forEach(element => {516            const url = new URL(element.href.split('?')[0].replace("-nojs", ""));517            url.searchParams.set('pagetitle', title);518            url.searchParams.set('pageurl', pageurl);519            url.searchParams.set('pagesource', "library/importlib.resources.rst");520            element.href = url.toString();521        });522    });523  </script>524  <div role="note" aria-label="source link">525    <h3>This page</h3>526    <ul class="this-page-menu">527      <li><a href="../bugs.html">Report a bug</a></li>528      <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>529      <li>530        <a href="https://github.com/python/cpython/blob/main/Doc/library/importlib.resources.rst?plain=1"531            rel="nofollow">Show source532        </a>533      </li>534      535    </ul>536  </div>537        </div>538<div id="sidebarbutton" title="Collapse sidebar">539<span>«</span>540</div>541 542      </div>543      <div class="clearer"></div>544    </div>  545    <div class="related" role="navigation" aria-label="Related">546      <h3>Navigation</h3>547      <ul>548        <li class="right" style="margin-right: 10px">549          <a href="../genindex.html" title="General Index"550             >index</a></li>551        <li class="right" >552          <a href="../py-modindex.html" title="Python Module Index"553             >modules</a> |</li>554        <li class="right" >555          <a href="importlib.resources.abc.html" title="importlib.resources.abc – Abstract base classes for resources"556             >next</a> |</li>557        <li class="right" >558          <a href="importlib.html" title="importlib — The implementation of import"559             >previous</a> |</li>560 561          <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>562          <li><a href="https://www.python.org/">Python</a> &#187;</li>563          <li class="switchers">564            <div class="language_switcher_placeholder"></div>565            <div class="version_switcher_placeholder"></div>566          </li>567          <li>568              569          </li>570    <li id="cpython-language-and-version">571      <a href="../index.html">3.15.0a6 Documentation</a> &#187;572    </li>573 574          <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>575          <li class="nav-item nav-item-2"><a href="modules.html" >Importing Modules</a> &#187;</li>576        <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">importlib.resources</span></code> – Package resource reading, opening and access</a></li>577                <li class="right">578                    579 580    <div class="inline-search" role="search">581        <form class="inline-search" action="../search.html" method="get">582          <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">583          <input type="submit" value="Go">584        </form>585    </div>586                     |587                </li>588            <li class="right">589<label class="theme-selector-label">590    Theme591    <select class="theme-selector" oninput="activateTheme(this.value)">592        <option value="auto" selected>Auto</option>593        <option value="light">Light</option>594        <option value="dark">Dark</option>595    </select>596</label> |</li>597            598      </ul>599    </div>  600    <div class="footer">601    &copy; <a href="../copyright.html">Copyright</a> 2001 Python Software Foundation.602    <br>603    This page is licensed under the Python Software Foundation License Version 2.604    <br>605    Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.606    <br>607    608      See <a href="/license.html">History and License</a> for more information.<br>609    610    611    <br>612 613    The Python Software Foundation is a non-profit corporation.614<a href="https://www.python.org/psf/donations/">Please donate.</a>615<br>616    <br>617      Last updated on Mar 10, 2026 (08:58 UTC).618    619      <a href="/bugs.html">Found a bug</a>?620    621    <br>622 623    Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.624    </div>625 626  </body>627</html>