parthtamu/rag-code-assistant
0
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 — 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> »</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> »183 </li>184 185 <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>186 <li class="nav-item nav-item-2"><a href="modules.html" accesskey="U">Importing Modules</a> »</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">>=</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">"info.txt"</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">"pics/painting.png"</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">"pics"</span><span class="p">,</span> <span class="s2">"painting.png"</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">"info"</span><span class="p">,</span> <span class="s2">"chapter1.txt"</span><span class="p">,</span>337 <span class="n">encoding</span><span class="o">=</span><span class="s1">'utf-8'</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">'rb'</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">'r'</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">"resource.txt"</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> »</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> »572 </li>573 574 <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>575 <li class="nav-item nav-item-2"><a href="modules.html" >Importing Modules</a> »</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 © <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>