uTools-Manuals/docs/python/pkgutil.html

<div class="body" role="main"><div class="section" id="module-pkgutil"><h1><span class="yiyi-st" id="yiyi-10">31.2. <a class="reference internal" href="#module-pkgutil" title="pkgutil: Utilities for the import system."><code class="xref py py-mod docutils literal"><span class="pre">pkgutil</span></code></a>  - 软件包扩展实用程序</span></h1><p><span class="yiyi-st" id="yiyi-11"><strong>源代码：</strong> <a class="reference external" href="https://hg.python.org/cpython/file/3.5/Lib/pkgutil.py">Lib / pkgutil.py</a></span></p><p><span class="yiyi-st" id="yiyi-12">此模块为导入系统提供实用程序，特别是软件包支持。</span></p><dl class="function"><dt id="pkgutil.extend_path"><span class="yiyi-st" id="yiyi-13"> <code class="descclassname">pkgutil.</code><code class="descname">extend_path</code><span class="sig-paren">(</span><em>path</em>, <em>name</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-14">扩展组成包的模块的搜索路径。</span><span class="yiyi-st" id="yiyi-15">预期用途是将以下代码放在包的<code class="file docutils literal"><span class="pre">__init__.py</span></code>中：</span></p><pre><code class="language-python"><span></span><span class="kn">from</span> <span class="nn">pkgutil</span> <span class="k">import</span> <span class="n">extend_path</span>
<span class="n">__path__</span> <span class="o">=</span> <span class="n">extend_path</span><span class="p">(</span><span class="n">__path__</span><span class="p">,</span> <span class="n">__name__</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-16">这将向包的<code class="docutils literal"><span class="pre">__path__</span></code>添加在包之后命名的<code class="docutils literal"><span class="pre">sys.path</span></code>上的目录的所有子目录。</span><span class="yiyi-st" id="yiyi-17">如果想要将单个逻辑包的不同部分分布为多个目录，这将非常有用。</span></p><p><span class="yiyi-st" id="yiyi-18">它还会查找<code class="docutils literal"><span class="pre">*</span></code>开头的<code class="file docutils literal"><span class="pre">*.pkg</span></code>文件是否与<em>名称</em>参数匹配。</span><span class="yiyi-st" id="yiyi-19">此功能类似于<code class="file docutils literal"><span class="pre">*.pth</span></code>文件（有关详细信息，请参阅<a class="reference internal" href="site.html#module-site" title="site: Module responsible for site-specific configuration."><code class="xref py py-mod docutils literal"><span class="pre">site</span></code></a>模块），但不包含以<code class="docutils literal"><span class="pre">import</span></code></span><span class="yiyi-st" id="yiyi-20">A <code class="file docutils literal"><span class="pre">*.pkg</span></code>文件以面值信任：除了检查重复之外，在<code class="file docutils literal"><span class="pre">*.pkg</span></code>文件中找到的所有条目都添加到路径，存在于文件系统上。</span><span class="yiyi-st" id="yiyi-21">（这是功能。）</span></p><p><span class="yiyi-st" id="yiyi-22">如果输入路径不是列表（如冻结包的情况），则返回不变。</span><span class="yiyi-st" id="yiyi-23">输入路径不修改；将返回扩展副本。</span><span class="yiyi-st" id="yiyi-24">项目仅附加到末尾的副本。</span></p><p><span class="yiyi-st" id="yiyi-25">假设<a class="reference internal" href="sys.html#sys.path" title="sys.path"><code class="xref py py-data docutils literal"><span class="pre">sys.path</span></code></a>是一个序列。</span><span class="yiyi-st" id="yiyi-26">不是指向现有目录的字符的<a class="reference internal" href="sys.html#sys.path" title="sys.path"><code class="xref py py-data docutils literal"><span class="pre">sys.path</span></code></a>项将被忽略。</span><span class="yiyi-st" id="yiyi-27">在<a class="reference internal" href="sys.html#sys.path" title="sys.path"><code class="xref py py-data docutils literal"><span class="pre">sys.path</span></code></a>上导致错误的Unicode项目在用作文件名时可能导致此函数引发异常（与<a class="reference internal" href="os.path.html#os.path.isdir" title="os.path.isdir"><code class="xref py py-func docutils literal"><span class="pre">os.path.isdir()</span></code></a>行为一致）。</span></p></dd></dl><dl class="class"><dt id="pkgutil.ImpImporter"><span class="yiyi-st" id="yiyi-28"> <em class="property">class </em><code class="descclassname">pkgutil.</code><code class="descname">ImpImporter</code><span class="sig-paren">(</span><em>dirname=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-29"><span class="target" id="index-0"></span> <a class="pep reference external" href="https://www.python.org/dev/peps/pep-0302"><strong>PEP 302</strong></a>导入器包装Python的“经典”导入算法。</span></p><p><span class="yiyi-st" id="yiyi-30">如果<em>dirname</em>是字符串，则会创建一个<span class="target" id="index-1"></span> <a class="pep reference external" href="https://www.python.org/dev/peps/pep-0302"><strong>PEP 302</strong></a>导入器，用于搜索该目录。</span><span class="yiyi-st" id="yiyi-31">如果<em>dirname</em>为<code class="docutils literal"><span class="pre">None</span></code>，将创建​​一个<span class="target" id="index-2"></span> <a class="pep reference external" href="https://www.python.org/dev/peps/pep-0302"><strong>PEP 302</strong></a>导入器，搜索当前<a class="reference internal" href="sys.html#sys.path" title="sys.path"><code class="xref py py-data docutils literal"><span class="pre">sys.path</span></code></a></span></p><p><span class="yiyi-st" id="yiyi-32">请注意，<a class="reference internal" href="#pkgutil.ImpImporter" title="pkgutil.ImpImporter"><code class="xref py py-class docutils literal"><span class="pre">ImpImporter</span></code></a>目前不支持由<a class="reference internal" href="sys.html#sys.meta_path" title="sys.meta_path"><code class="xref py py-data docutils literal"><span class="pre">sys.meta_path</span></code></a>上的展示位置使用。</span></p><div class="deprecated"><p><span class="yiyi-st" id="yiyi-33"><span class="versionmodified">自版本3.3后已弃用：</span>此模拟不再需要，因为标准导入机制现在完全符合PEP 302，并且在<a class="reference internal" href="importlib.html#module-importlib" title="importlib: The implementation of the import machinery."><code class="xref py py-mod docutils literal"><span class="pre">importlib</span></code></a>中可用。</span></p></div></dd></dl><dl class="class"><dt id="pkgutil.ImpLoader"><span class="yiyi-st" id="yiyi-34"> <em class="property">class </em><code class="descclassname">pkgutil.</code><code class="descname">ImpLoader</code><span class="sig-paren">(</span><em>fullname</em>, <em>file</em>, <em>filename</em>, <em>etc</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-35"><span class="target" id="index-3"></span> <a class="pep reference external" href="https://www.python.org/dev/peps/pep-0302"><strong>PEP 302</strong></a>加载器，它包装Python的“经典”导入算法。</span></p><div class="deprecated"><p><span class="yiyi-st" id="yiyi-36"><span class="versionmodified">自版本3.3后已弃用：</span>此模拟不再需要，因为标准导入机制现在完全符合PEP 302，并且在<a class="reference internal" href="importlib.html#module-importlib" title="importlib: The implementation of the import machinery."><code class="xref py py-mod docutils literal"><span class="pre">importlib</span></code></a>中可用。</span></p></div></dd></dl><dl class="function"><dt id="pkgutil.find_loader"><span class="yiyi-st" id="yiyi-37"> <code class="descclassname">pkgutil.</code><code class="descname">find_loader</code><span class="sig-paren">(</span><em>fullname</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-38">针对给定的<em>全名</em>，检索<span class="target" id="index-4"></span> <a class="pep reference external" href="https://www.python.org/dev/peps/pep-0302"><strong>PEP 302</strong></a>模块加载程序。</span></p><p><span class="yiyi-st" id="yiyi-39">这是<a class="reference internal" href="importlib.html#importlib.util.find_spec" title="importlib.util.find_spec"><code class="xref py py-func docutils literal"><span class="pre">importlib.util.find_spec()</span></code></a>的向后兼容性封装，将大多数失败转换为<a class="reference internal" href="exceptions.html#ImportError" title="ImportError"><code class="xref py py-exc docutils literal"><span class="pre">ImportError</span></code></a>，只返回加载器而不是完整的<code class="xref py py-class docutils literal"><span class="pre">ModuleSpec</span></code></span></p><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-40"><span class="versionmodified">在版本3.3中更改：</span>更新为直接基于<a class="reference internal" href="importlib.html#module-importlib" title="importlib: The implementation of the import machinery."><code class="xref py py-mod docutils literal"><span class="pre">importlib</span></code></a>，而不是依赖程序包内部PEP 302导入仿真。</span></p></div><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-41"><span class="versionmodified">在版本3.4中已更改：</span>更新为基于<span class="target" id="index-5"></span> <a class="pep reference external" href="https://www.python.org/dev/peps/pep-0451"><strong>PEP 451</strong></a></span></p></div></dd></dl><dl class="function"><dt id="pkgutil.get_importer"><span class="yiyi-st" id="yiyi-42"> <code class="descclassname">pkgutil.</code><code class="descname">get_importer</code><span class="sig-paren">(</span><em>path_item</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-43">针对给定的<em>path_item</em>，检索<span class="target" id="index-6"></span> <a class="pep reference external" href="https://www.python.org/dev/peps/pep-0302"><strong>PEP 302</strong></a>导入器。</span></p><p><span class="yiyi-st" id="yiyi-44">如果返回的导入器是由路径钩子新创建的，则缓存在<a class="reference internal" href="sys.html#sys.path_importer_cache" title="sys.path_importer_cache"><code class="xref py py-data docutils literal"><span class="pre">sys.path_importer_cache</span></code></a>中。</span></p><p><span class="yiyi-st" id="yiyi-45">如果需要重新扫描<a class="reference internal" href="sys.html#sys.path_hooks" title="sys.path_hooks"><code class="xref py py-data docutils literal"><span class="pre">sys.path_hooks</span></code></a>，则可以手动清除高速缓存（或其一部分）。</span></p><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-46"><span class="versionmodified">在版本3.3中更改：</span>更新为直接基于<a class="reference internal" href="importlib.html#module-importlib" title="importlib: The implementation of the import machinery."><code class="xref py py-mod docutils literal"><span class="pre">importlib</span></code></a>，而不是依赖程序包内部PEP 302导入仿真。</span></p></div></dd></dl><dl class="function"><dt id="pkgutil.get_loader"><span class="yiyi-st" id="yiyi-47"> <code class="descclassname">pkgutil.</code><code class="descname">get_loader</code><span class="sig-paren">(</span><em>module_or_name</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-48">为<em>module_or_name</em>获取<span class="target" id="index-7"></span> <a class="pep reference external" href="https://www.python.org/dev/peps/pep-0302"><strong>PEP 302</strong></a>“loader”对象。</span></p><p><span class="yiyi-st" id="yiyi-49">如果模块或包可以通过正常的导入机制访问，则返回该机器的相关部分周围的包装。</span><span class="yiyi-st" id="yiyi-50">如果无法找到或导入模块，则返回<code class="docutils literal"><span class="pre">None</span></code>。</span><span class="yiyi-st" id="yiyi-51">如果指定的模块尚未导入，则将导入其包含的包（如果有），以建立包<code class="docutils literal"><span class="pre">__path__</span></code>。</span></p><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-52"><span class="versionmodified">在版本3.3中更改：</span>更新为直接基于<a class="reference internal" href="importlib.html#module-importlib" title="importlib: The implementation of the import machinery."><code class="xref py py-mod docutils literal"><span class="pre">importlib</span></code></a>，而不是依赖程序包内部PEP 302导入仿真。</span></p></div><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-53"><span class="versionmodified">在版本3.4中已更改：</span>更新为基于<span class="target" id="index-8"></span> <a class="pep reference external" href="https://www.python.org/dev/peps/pep-0451"><strong>PEP 451</strong></a></span></p></div></dd></dl><dl class="function"><dt id="pkgutil.iter_importers"><span class="yiyi-st" id="yiyi-54"> <code class="descclassname">pkgutil.</code><code class="descname">iter_importers</code><span class="sig-paren">(</span><em>fullname=''</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-55">给定模块名称的产出<span class="target" id="index-9"></span> <a class="pep reference external" href="https://www.python.org/dev/peps/pep-0302"><strong>PEP 302</strong></a>导入器。</span></p><p><span class="yiyi-st" id="yiyi-56">如果fullname包含'。'，进口商将是包含fullname的包，否则它们将是所有注册的顶级进口商。</span><span class="yiyi-st" id="yiyi-57">那些在sys.meta_path和sys.path_hooks）。</span></p><p><span class="yiyi-st" id="yiyi-58">如果命名模块在包中，则该包将作为调用此函数的副作用导入。</span></p><p><span class="yiyi-st" id="yiyi-59">如果未指定模块名称，则会生成所有顶级导入器。</span></p><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-60"><span class="versionmodified">在版本3.3中更改：</span>更新为直接基于<a class="reference internal" href="importlib.html#module-importlib" title="importlib: The implementation of the import machinery."><code class="xref py py-mod docutils literal"><span class="pre">importlib</span></code></a>，而不是依赖程序包内部PEP 302导入仿真。</span></p></div></dd></dl><dl class="function"><dt id="pkgutil.iter_modules"><span class="yiyi-st" id="yiyi-61"> <code class="descclassname">pkgutil.</code><code class="descname">iter_modules</code><span class="sig-paren">(</span><em>path=None</em>, <em>prefix=''</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-62">对<em>路径</em>上的所有子模块，产生<code class="docutils literal"><span class="pre">（module_finder，</span> <span class="pre">名称，</span> <span class="pre">ispkg） ，如果<em>路径</em>为<code class="docutils literal"><span class="pre">None</span></code>，则<code class="docutils literal"><span class="pre">sys.path</span></code>上的所有顶级模块。</span></code></span></p><p><span class="yiyi-st" id="yiyi-63"><em>路径</em>应为<code class="docutils literal"><span class="pre">None</span></code>或查找模块的路径列表。</span></p><p><span class="yiyi-st" id="yiyi-64"><em>前缀</em>是在输出上每个模块名称前面输出的字符串。</span></p><div class="admonition note"><p class="first admonition-title"><span class="yiyi-st" id="yiyi-65">注意</span></p><p class="last"><span class="yiyi-st" id="yiyi-66">仅适用于定义<code class="docutils literal"><span class="pre">iter_modules()</span></code>方法的<a class="reference internal" href="../glossary.html#term-finder"><span class="xref std std-term">finder</span></a>。</span><span class="yiyi-st" id="yiyi-67">此界面是非标准的，因此该模块还提供了<a class="reference internal" href="importlib.html#importlib.machinery.FileFinder" title="importlib.machinery.FileFinder"><code class="xref py py-class docutils literal"><span class="pre">importlib.machinery.FileFinder</span></code></a>和<a class="reference internal" href="zipimport.html#zipimport.zipimporter" title="zipimport.zipimporter"><code class="xref py py-class docutils literal"><span class="pre">zipimport.zipimporter</span></code></a>的实现。</span></p></div><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-68"><span class="versionmodified">在版本3.3中更改：</span>更新为直接基于<a class="reference internal" href="importlib.html#module-importlib" title="importlib: The implementation of the import machinery."><code class="xref py py-mod docutils literal"><span class="pre">importlib</span></code></a>，而不是依赖程序包内部PEP 302导入仿真。</span></p></div></dd></dl><dl class="function"><dt id="pkgutil.walk_packages"><span class="yiyi-st" id="yiyi-69"> <code class="descclassname">pkgutil.</code><code class="descname">walk_packages</code><span class="sig-paren">(</span><em>path=None</em>, <em>prefix=''</em>, <em>onerror=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-70">对于所有模块在<em>路径</em>上递归生成<code class="docutils literal"><span class="pre">（module_finder，</span> <span class="pre">名称，</span> <span class="pre">ispkg）或者，如果<em>路径</em>是<code class="docutils literal"><span class="pre">None</span></code>，所有可访问的模块。</span></code></span></p><p><span class="yiyi-st" id="yiyi-71"><em>路径</em>应为<code class="docutils literal"><span class="pre">None</span></code>或查找模块的路径列表。</span></p><p><span class="yiyi-st" id="yiyi-72"><em>前缀</em>是在输出上每个模块名称前面输出的字符串。</span></p><p><span class="yiyi-st" id="yiyi-73">请注意，此函数必须导入所有<em>包</em>（<em>不是</em>所有模块！）</span><span class="yiyi-st" id="yiyi-74">在给定的<em>路径</em>上，以访问<code class="docutils literal"><span class="pre">__path__</span></code>属性以查找子模块。</span></p><p><span class="yiyi-st" id="yiyi-75"><em>onerror</em>是在尝试导入包时发生任何异常时，使用一个参数（正在导入的包的名称）调用的函数。</span><span class="yiyi-st" id="yiyi-76">如果未提供<em>onerror</em>函数，则会捕获并忽略<a class="reference internal" href="exceptions.html#ImportError" title="ImportError"><code class="xref py py-exc docutils literal"><span class="pre">ImportError</span></code></a>，而传播所有其他异常，从而终止搜索。</span></p><p><span class="yiyi-st" id="yiyi-77">例子：</span></p><pre><code class="language-python"><span></span><span class="c1"># list all modules python can access</span>
<span class="n">walk_packages</span><span class="p">()</span>

<span class="c1"># list all submodules of ctypes</span>
<span class="n">walk_packages</span><span class="p">(</span><span class="n">ctypes</span><span class="o">.</span><span class="n">__path__</span><span class="p">,</span> <span class="n">ctypes</span><span class="o">.</span><span class="n">__name__</span> <span class="o">+</span> <span class="s1">'.'</span><span class="p">)</span>
</code></pre><div class="admonition note"><p class="first admonition-title"><span class="yiyi-st" id="yiyi-78">注意</span></p><p class="last"><span class="yiyi-st" id="yiyi-79">仅适用于定义<code class="docutils literal"><span class="pre">iter_modules()</span></code>方法的<a class="reference internal" href="../glossary.html#term-finder"><span class="xref std std-term">finder</span></a>。</span><span class="yiyi-st" id="yiyi-80">此界面是非标准的，因此该模块还提供了<a class="reference internal" href="importlib.html#importlib.machinery.FileFinder" title="importlib.machinery.FileFinder"><code class="xref py py-class docutils literal"><span class="pre">importlib.machinery.FileFinder</span></code></a>和<a class="reference internal" href="zipimport.html#zipimport.zipimporter" title="zipimport.zipimporter"><code class="xref py py-class docutils literal"><span class="pre">zipimport.zipimporter</span></code></a>的实现。</span></p></div><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-81"><span class="versionmodified">在版本3.3中更改：</span>更新为直接基于<a class="reference internal" href="importlib.html#module-importlib" title="importlib: The implementation of the import machinery."><code class="xref py py-mod docutils literal"><span class="pre">importlib</span></code></a>，而不是依赖程序包内部PEP 302导入仿真。</span></p></div></dd></dl><dl class="function"><dt id="pkgutil.get_data"><span class="yiyi-st" id="yiyi-82"> <code class="descclassname">pkgutil.</code><code class="descname">get_data</code><span class="sig-paren">(</span><em>package</em>, <em>resource</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-83">从包中获取资源。</span></p><p><span class="yiyi-st" id="yiyi-84">这是<span class="target" id="index-10"></span> <a class="pep reference external" href="https://www.python.org/dev/peps/pep-0302"><strong>PEP 302</strong></a>加载程序<a class="reference internal" href="#pkgutil.get_data" title="pkgutil.get_data"><code class="xref py py-func docutils literal"><span class="pre">get_data()</span></code></a> API的包装器。</span><span class="yiyi-st" id="yiyi-85"><em>包</em>参数应为标准模块格式（<code class="docutils literal"><span class="pre">foo.bar</span></code>）的包名称。</span><span class="yiyi-st" id="yiyi-86"><em>资源</em>参数应采用相对文件名的形式，使用<code class="docutils literal"><span class="pre">/</span></code>作为路径分隔符。</span><span class="yiyi-st" id="yiyi-87">不允许父目录名称<code class="docutils literal"><span class="pre">..</span></code>，也不是根目录名称（以<code class="docutils literal"><span class="pre">/</span></code>开头）。</span></p><p><span class="yiyi-st" id="yiyi-88">该函数返回一个二进制字符串，它是指定资源的内容。</span></p><p><span class="yiyi-st" id="yiyi-89">对于已经导入的位于文件系统中的包，这是大致相当于：</span></p><pre><code class="language-python"><span></span><span class="n">d</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">dirname</span><span class="p">(</span><span class="n">sys</span><span class="o">.</span><span class="n">modules</span><span class="p">[</span><span class="n">package</span><span class="p">]</span><span class="o">.</span><span class="n">__file__</span><span class="p">)</span>
<span class="n">data</span> <span class="o">=</span> <span class="nb">open</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">d</span><span class="p">,</span> <span class="n">resource</span><span class="p">),</span> <span class="s1">'rb'</span><span class="p">)</span><span class="o">.</span><span class="n">read</span><span class="p">()</span>
</code></pre><p><span class="yiyi-st" id="yiyi-90">如果无法找到或加载包，或者使用不支持<a class="reference internal" href="#pkgutil.get_data" title="pkgutil.get_data"><code class="xref py py-func docutils literal"><span class="pre">get_data()</span></code></a>的<span class="target" id="index-11"></span> <a class="pep reference external" href="https://www.python.org/dev/peps/pep-0302"><strong>PEP 302</strong></a>加载程序，则<code class="docutils literal"><span class="pre">None</span></code>。</span></p></dd></dl></div></div>