study/uTools-Manuals
1
0
Fork 0
mirror of https://github.com/fofolee/uTools-Manuals.git synced 2025-06-09 15:34:05 +08:00
Code Issues Packages Projects Releases Wiki Activity
uTools-Manuals/docs/python/shutil.html
fofolee 7ca94f1141 0.0.1
2019-04-08 23:22:26 +08:00

68 lines
66 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<div class="body" role="main"><div class="section" id="module-shutil"><h1><span class="yiyi-st" id="yiyi-10">11.10. <a class="reference internal" href="#module-shutil" title="shutil: High-level file operations, including copying."><code class="xref py py-mod docutils literal"><span class="pre">shutil</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/shutil.py">Lib / shutil.py</a></span></p><p><span class="yiyi-st" id="yiyi-12"><a class="reference internal" href="#module-shutil" title="shutil: High-level file operations, including copying."><code class="xref py py-mod docutils literal"><span class="pre">shutil</span></code></a>模块提供了对文件和容器文件的一些高级操作。</span><span class="yiyi-st" id="yiyi-13">特别地，提供了支持文件复制和移除的功能。</span><span class="yiyi-st" id="yiyi-14">有关单个文件的操作，另请参见<a class="reference internal" href="os.html#module-os" title="os: Miscellaneous operating system interfaces."><code class="xref py py-mod docutils literal"><span class="pre">os</span></code></a>模块。</span></p><div class="admonition warning"><p class="first admonition-title"><span class="yiyi-st" id="yiyi-15">警告</span></p><p><span class="yiyi-st" id="yiyi-16">即使较高级别的文件复制功能（<a class="reference internal" href="#shutil.copy" title="shutil.copy"><code class="xref py py-func docutils literal"><span class="pre">shutil.copy()</span></code></a>，<a class="reference internal" href="#shutil.copy2" title="shutil.copy2"><code class="xref py py-func docutils literal"><span class="pre">shutil.copy2()</span></code></a>）也无法复制所有文件元数据。</span></p><p class="last"><span class="yiyi-st" id="yiyi-17">在POSIX平台上，这意味着文件所有者和组会丢失以及ACL。</span><span class="yiyi-st" id="yiyi-18">在Mac OS上，不使用资源分支和其他元数据。</span><span class="yiyi-st" id="yiyi-19">这意味着资源将丢失，文件类型和创建者代码将不正确。</span><span class="yiyi-st" id="yiyi-20">在Windows上，不复制文件所有者，ACL和备用数据流。</span></p></div><div class="section" id="directory-and-files-operations"><h2><span class="yiyi-st" id="yiyi-21">11.10.1.</span><span class="yiyi-st" id="yiyi-22">目录和文件操作</span></h2><dl class="function"><dt id="shutil.copyfileobj"><span class="yiyi-st" id="yiyi-23"> <code class="descclassname">shutil.</code><code class="descname">copyfileobj</code><span class="sig-paren">(</span><em>fsrc</em>, <em>fdst</em><span class="optional">[</span>, <em>length</em><span class="optional">]</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-24">将类似文件的对象<em>fsrc</em>的内容复制到类似文件的对象<em>fdst</em>。</span><span class="yiyi-st" id="yiyi-25">整数<em>length</em>（如果给出）是缓冲区大小。</span><span class="yiyi-st" id="yiyi-26">具体地，负的<em>长度</em>值意味着复制数据而不使块中的源数据循环；默认情况下，以块为单位读取数据，以避免不受控制的内存消耗。</span><span class="yiyi-st" id="yiyi-27">请注意，如果<em>fsrc</em>对象的当前文件位置不为0，则只会复制当前文件位置到文件末尾的内容。</span></p></dd></dl><dl class="function"><dt id="shutil.copyfile"><span class="yiyi-st" id="yiyi-28"> <code class="descclassname">shutil.</code><code class="descname">copyfile</code><span class="sig-paren">(</span><em>src</em>, <em>dst</em>, <em>*</em>, <em>follow_symlinks=True</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-29">将名为<em>src</em>的文件的内容（无元数据）复制到名为<em>dst</em>的文件，然后返回<em>dst</em>。</span><span class="yiyi-st" id="yiyi-30"><em>src</em>和<em>dst</em>是以字符串形式给出的路径名称。</span><span class="yiyi-st" id="yiyi-31"><em>dst</em>必须是完整的目标文件名；请查看<a class="reference internal" href="#shutil.copy" title="shutil.copy"><code class="xref py py-func docutils literal"><span class="pre">shutil.copy()</span></code></a>以获取接受目标目录路径的副本。</span><span class="yiyi-st" id="yiyi-32">如果<em>src</em>和<em>dst</em>指定相同的文件，则会引发<a class="reference internal" href="#shutil.SameFileError" title="shutil.SameFileError"><code class="xref py py-exc docutils literal"><span class="pre">SameFileError</span></code></a>。</span></p><p><span class="yiyi-st" id="yiyi-33">目标位置必须可写；否则，将引发<a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal"><span class="pre">OSError</span></code></a>异常。</span><span class="yiyi-st" id="yiyi-34">如果<em>dst</em>已经存在，它将被替换。</span><span class="yiyi-st" id="yiyi-35">使用此功能无法复制特殊文件，例如字符或块设备和管道。</span></p><p><span class="yiyi-st" id="yiyi-36">如果<em>follow_symlinks</em>为假且<em>src</em>是符号链接，则将创建一个新的符号链接，而不是复制<em>src</em>指向的文件。</span></p><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-37"><span class="versionmodified">在版本3.3中更改：</span> <a class="reference internal" href="exceptions.html#IOError" title="IOError"><code class="xref py py-exc docutils literal"><span class="pre">IOError</span></code></a>已升级，而不是<a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal"><span class="pre">OSError</span></code></a>。</span><span class="yiyi-st" id="yiyi-38">添加了<em>follow_symlinks</em>参数。</span><span class="yiyi-st" id="yiyi-39">现在返回<em>dst</em>。</span></p></div><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-40"><span class="versionmodified">在版本3.4中更改：</span>提高<a class="reference internal" href="#shutil.SameFileError" title="shutil.SameFileError"><code class="xref py py-exc docutils literal"><span class="pre">SameFileError</span></code></a>，而不是<a class="reference internal" href="#shutil.Error" title="shutil.Error"><code class="xref py py-exc docutils literal"><span class="pre">Error</span></code></a>。</span><span class="yiyi-st" id="yiyi-41">因为前者是后者的子类，所以这种变化是向后兼容的。</span></p></div></dd></dl><dl class="exception"><dt id="shutil.SameFileError"><span class="yiyi-st" id="yiyi-42"> <em class="property">exception </em><code class="descclassname">shutil.</code><code class="descname">SameFileError</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-43">如果<a class="reference internal" href="#shutil.copyfile" title="shutil.copyfile"><code class="xref py py-func docutils literal"><span class="pre">copyfile()</span></code></a>中的源和目标是相同的文件，则会引发此异常。</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-44"><span class="versionmodified">版本3.4中的新功能。</span></span></p></div></dd></dl><dl class="function"><dt id="shutil.copymode"><span class="yiyi-st" id="yiyi-45"> <code class="descclassname">shutil.</code><code class="descname">copymode</code><span class="sig-paren">(</span><em>src</em>, <em>dst</em>, <em>*</em>, <em>follow_symlinks=True</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-46">将权限位从<em>src</em>复制到<em>dst</em>。</span><span class="yiyi-st" id="yiyi-47">文件内容，所有者和组不受影响。</span><span class="yiyi-st" id="yiyi-48"><em>src</em>和<em>dst</em>是以字符串形式给出的路径名称。</span><span class="yiyi-st" id="yiyi-49">If <em>follow_symlinks</em> is false, and both <em>src</em> and <em>dst</em> are symbolic links, <a class="reference internal" href="#shutil.copymode" title="shutil.copymode"><code class="xref py py-func docutils literal"><span class="pre">copymode()</span></code></a> will attempt to modify the mode of <em>dst</em> itself (rather than the file it points to). </span><span class="yiyi-st" id="yiyi-50">此功能不适用于每个平台；请参阅<a class="reference internal" href="#shutil.copystat" title="shutil.copystat"><code class="xref py py-func docutils literal"><span class="pre">copystat()</span></code></a>了解更多信息。</span><span class="yiyi-st" id="yiyi-51">如果<a class="reference internal" href="#shutil.copymode" title="shutil.copymode"><code class="xref py py-func docutils literal"><span class="pre">copymode()</span></code></a>无法修改本地平台上的符号链接，并且要求这样做，它将不会执行任何操作并返回。</span></p><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-52"><span class="versionmodified">在版本3.3中已更改：</span>添加了<em>follow_symlinks</em>参数。</span></p></div></dd></dl><dl class="function"><dt id="shutil.copystat"><span class="yiyi-st" id="yiyi-53"> <code class="descclassname">shutil.</code><code class="descname">copystat</code><span class="sig-paren">(</span><em>src</em>, <em>dst</em>, <em>*</em>, <em>follow_symlinks=True</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-54">将权限位，最后访问时间，上次修改时间和标志从<em>src</em>复制到<em>dst</em>。</span><span class="yiyi-st" id="yiyi-55">在Linux上，<a class="reference internal" href="#shutil.copystat" title="shutil.copystat"><code class="xref py py-func docutils literal"><span class="pre">copystat()</span></code></a>也会尽可能复制“扩展属性”。</span><span class="yiyi-st" id="yiyi-56">文件内容，所有者和组不受影响。</span><span class="yiyi-st" id="yiyi-57"><em>src</em>和<em>dst</em>是以字符串形式给出的路径名称。</span></p><p><span class="yiyi-st" id="yiyi-58">If <em>follow_symlinks</em> is false, and <em>src</em> and <em>dst</em> both refer to symbolic links, <a class="reference internal" href="#shutil.copystat" title="shutil.copystat"><code class="xref py py-func docutils literal"><span class="pre">copystat()</span></code></a> will operate on the symbolic links themselves rather than the files the symbolic links refer to–reading the information from the <em>src</em> symbolic link, and writing the information to the <em>dst</em> symbolic link.</span></p><div class="admonition note"><p class="first admonition-title"><span class="yiyi-st" id="yiyi-59">注意</span></p><p><span class="yiyi-st" id="yiyi-60">并非所有平台都提供检查和修改符号链接的能力。</span><span class="yiyi-st" id="yiyi-61">Python本身可以告诉你本地可用的功能。</span></p><ul class="simple"><li><span class="yiyi-st" id="yiyi-62">如果 <span class="pre">os.supports_follow_symlinks</span>中的<code class="docutils literal"><span class="pre">os.chmod</span> <span class="pre">是<code class="docutils literal"><span class="pre">True</span></code>，<a class="reference internal" href="#shutil.copystat" title="shutil.copystat"><code class="xref py py-func docutils literal"><span class="pre">copystat()</span></code></a>可以修改符号链接的权限位。</span></code></span></li><li><span class="yiyi-st" id="yiyi-63">如果 t&gt; <span class="pre">os.supports_follow_symlinks</span>中的<code class="docutils literal"><span class="pre">os.utime</span> <span class="pre">是<code class="docutils literal"><span class="pre">True</span></code>，<a class="reference internal" href="#shutil.copystat" title="shutil.copystat"><code class="xref py py-func docutils literal"><span class="pre">copystat()</span></code></a>可以修改符号链接的最后访问和修改时间。</span></code></span></li><li><span class="yiyi-st" id="yiyi-64">如果 t&gt; <span class="pre">os.supports_follow_symlinks</span>中的<code class="docutils literal"><span class="pre">os.chflags</span> <span class="pre">是<code class="docutils literal"><span class="pre">True</span></code>，<a class="reference internal" href="#shutil.copystat" title="shutil.copystat"><code class="xref py py-func docutils literal"><span class="pre">copystat()</span></code></a>可以修改符号链接的标志。</span></code></span><span class="yiyi-st" id="yiyi-65">（<code class="docutils literal"><span class="pre">os.chflags</span></code>不适用于所有平台。）</span></li></ul><p><span class="yiyi-st" id="yiyi-66">在某些或所有功能不可用的平台上，当要求修改符号链接时，<a class="reference internal" href="#shutil.copystat" title="shutil.copystat"><code class="xref py py-func docutils literal"><span class="pre">copystat()</span></code></a>将复制所有可能的内容。</span><span class="yiyi-st" id="yiyi-67"><a class="reference internal" href="#shutil.copystat" title="shutil.copystat"><code class="xref py py-func docutils literal"><span class="pre">copystat()</span></code></a>从不会返回失败。</span></p><p class="last"><span class="yiyi-st" id="yiyi-68">有关详细信息，请参阅<a class="reference internal" href="os.html#os.supports_follow_symlinks" title="os.supports_follow_symlinks"><code class="xref py py-data docutils literal"><span class="pre">os.supports_follow_symlinks</span></code></a>。</span></p></div><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-69"><span class="versionmodified">在版本3.3中已更改：</span>添加了<em>follow_symlinks</em>参数并支持Linux扩展属性。</span></p></div></dd></dl><dl class="function"><dt id="shutil.copy"><span class="yiyi-st" id="yiyi-70"> <code class="descclassname">shutil.</code><code class="descname">copy</code><span class="sig-paren">(</span><em>src</em>, <em>dst</em>, <em>*</em>, <em>follow_symlinks=True</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-71">将文件<em>src</em>复制到文件或目录<em>dst</em>。</span><span class="yiyi-st" id="yiyi-72"><em>src</em>和<em>dst</em>应为字符串。</span><span class="yiyi-st" id="yiyi-73">如果<em>dst</em>指定目录，则文件将使用<em>src</em>的基本文件名复制到<em>dst</em>中。</span><span class="yiyi-st" id="yiyi-74">返回新创建的文件的路径。</span></p><p><span class="yiyi-st" id="yiyi-75">如果<em>follow_symlinks</em>为false，并且<em>src</em>是符号链接，则<em>dst</em>将创建为符号链接。</span><span class="yiyi-st" id="yiyi-76">如果<em>follow_symlinks</em>为true且<em>src</em>是符号链接，则<em>dst</em>将是文件的副本<em>src</em> 。</span></p><p><span class="yiyi-st" id="yiyi-77"><a class="reference internal" href="copy.html#module-copy" title="copy: Shallow and deep copy operations."><code class="xref py py-func docutils literal"><span class="pre">copy()</span></code></a>复制文件数据和文件的权限模式（请参阅<a class="reference internal" href="os.html#os.chmod" title="os.chmod"><code class="xref py py-func docutils literal"><span class="pre">os.chmod()</span></code></a>）。</span><span class="yiyi-st" id="yiyi-78">其他元数据（如文件的创建和修改时间）不会保留。</span><span class="yiyi-st" id="yiyi-79">要保留原始文件的所有文件元数据，请改用<a class="reference internal" href="#shutil.copy2" title="shutil.copy2"><code class="xref py py-func docutils literal"><span class="pre">copy2()</span></code></a>。</span></p><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-80"><span class="versionmodified">在版本3.3中已更改：</span>添加了<em>follow_symlinks</em>参数。</span><span class="yiyi-st" id="yiyi-81">现在返回新创建的文件的路径。</span></p></div></dd></dl><dl class="function"><dt id="shutil.copy2"><span class="yiyi-st" id="yiyi-82"> <code class="descclassname">shutil.</code><code class="descname">copy2</code><span class="sig-paren">(</span><em>src</em>, <em>dst</em>, <em>*</em>, <em>follow_symlinks=True</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-83">与<a class="reference internal" href="#shutil.copy" title="shutil.copy"><code class="xref py py-func docutils literal"><span class="pre">copy()</span></code></a>相同，但<a class="reference internal" href="#shutil.copy2" title="shutil.copy2"><code class="xref py py-func docutils literal"><span class="pre">copy2()</span></code></a>也尝试保留所有文件元数据。</span></p><p><span class="yiyi-st" id="yiyi-84">当<em>follow_symlinks</em>为false，且<em>src</em>是符号链接时，<a class="reference internal" href="#shutil.copy2" title="shutil.copy2"><code class="xref py py-func docutils literal"><span class="pre">copy2()</span></code></a>尝试从<em>src t5 &gt;符号链接到新创建的<em>dst</em>符号链接。</em></span><span class="yiyi-st" id="yiyi-85">但是，此功能不适用于所有平台。</span><span class="yiyi-st" id="yiyi-86">在某些或所有功能不可用的平台上，<a class="reference internal" href="#shutil.copy2" title="shutil.copy2"><code class="xref py py-func docutils literal"><span class="pre">copy2()</span></code></a>将保留其可用的所有元数据； <a class="reference internal" href="#shutil.copy2" title="shutil.copy2"><code class="xref py py-func docutils literal"><span class="pre">copy2()</span></code></a>从不会返回失败。</span></p><p><span class="yiyi-st" id="yiyi-87"><a class="reference internal" href="#shutil.copy2" title="shutil.copy2"><code class="xref py py-func docutils literal"><span class="pre">copy2()</span></code></a>使用<a class="reference internal" href="#shutil.copystat" title="shutil.copystat"><code class="xref py py-func docutils literal"><span class="pre">copystat()</span></code></a>复制文件元数据。</span><span class="yiyi-st" id="yiyi-88">有关修改符号链接元数据的平台支持的详细信息，请参阅<a class="reference internal" href="#shutil.copystat" title="shutil.copystat"><code class="xref py py-func docutils literal"><span class="pre">copystat()</span></code></a>。</span></p><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-89"><span class="versionmodified">在版本3.3中更改：</span>添加了<em>follow_symlinks</em>参数，尝试复制扩展文件系统属性（当前仅限于Linux）。</span><span class="yiyi-st" id="yiyi-90">现在返回新创建的文件的路径。</span></p></div></dd></dl><dl class="function"><dt id="shutil.ignore_patterns"><span class="yiyi-st" id="yiyi-91"> <code class="descclassname">shutil.</code><code class="descname">ignore_patterns</code><span class="sig-paren">(</span><em>*patterns</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-92">此工厂函数创建一个函数，可用作<a class="reference internal" href="#shutil.copytree" title="shutil.copytree"><code class="xref py py-func docutils literal"><span class="pre">copytree()</span></code></a>的<em>忽略</em>参数的可调用函数，忽略与glob类型<em>模式</em>。</span><span class="yiyi-st" id="yiyi-93">请参见下面的示例。</span></p></dd></dl><dl class="function"><dt id="shutil.copytree"><span class="yiyi-st" id="yiyi-94"> <code class="descclassname">shutil.</code><code class="descname">copytree</code><span class="sig-paren">(</span><em>src</em>, <em>dst</em>, <em>symlinks=False</em>, <em>ignore=None</em>, <em>copy_function=copy2</em>, <em>ignore_dangling_symlinks=False</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-95">递归地复制以<em>src</em>为根的整个目录树，返回目标目录。</span><span class="yiyi-st" id="yiyi-96">由<em>dst</em>命名的目标目录不能已经存在；它将被创建以及缺少父目录。</span><span class="yiyi-st" id="yiyi-97">使用<a class="reference internal" href="#shutil.copystat" title="shutil.copystat"><code class="xref py py-func docutils literal"><span class="pre">copystat()</span></code></a>复制目录的权限和时间，使用<a class="reference internal" href="#shutil.copy2" title="shutil.copy2"><code class="xref py py-func docutils literal"><span class="pre">shutil.copy2()</span></code></a>复制单个文件。</span></p><p><span class="yiyi-st" id="yiyi-98">如果<em>符号链接</em>为真，则源树中的符号链接在新树中表示为符号链接，并且原始链接的元数据将被复制到平台允许的范围内；如果为false或省略，链接文件的内容和元数据将复制到新树。</span></p><p><span class="yiyi-st" id="yiyi-99">当<em>符号链接</em>为false时，如果符号链接指向的文件不存在，则在<a class="reference internal" href="#shutil.Error" title="shutil.Error"><code class="xref py py-exc docutils literal"><span class="pre">Error</span></code></a>异常中引发的错误列表中将添加一个异常复制过程。</span><span class="yiyi-st" id="yiyi-100">如果要冻结此异常，可以将可选的<em>ignore_dangling_symlinks</em>标志设置为true。</span><span class="yiyi-st" id="yiyi-101">请注意，此选项对不支持<a class="reference internal" href="os.html#os.symlink" title="os.symlink"><code class="xref py py-func docutils literal"><span class="pre">os.symlink()</span></code></a>的平台没有影响。</span></p><p><span class="yiyi-st" id="yiyi-102">If <em>ignore</em> is given, it must be a callable that will receive as its arguments the directory being visited by <a class="reference internal" href="#shutil.copytree" title="shutil.copytree"><code class="xref py py-func docutils literal"><span class="pre">copytree()</span></code></a>, and a list of its contents, as returned by <a class="reference internal" href="os.html#os.listdir" title="os.listdir"><code class="xref py py-func docutils literal"><span class="pre">os.listdir()</span></code></a>. </span><span class="yiyi-st" id="yiyi-103">由于递归调用<a class="reference internal" href="#shutil.copytree" title="shutil.copytree"><code class="xref py py-func docutils literal"><span class="pre">copytree()</span></code></a>，因此对于要复制的每个目录，将调用<em>忽略</em>可调用对象。</span><span class="yiyi-st" id="yiyi-104">可调用必须返回相对于当前目录的目录和文件名的序列（即，</span><span class="yiyi-st" id="yiyi-105">在其第二参数中的项目的子集）；这些名称将在复制过程中被忽略。</span><span class="yiyi-st" id="yiyi-106"><a class="reference internal" href="#shutil.ignore_patterns" title="shutil.ignore_patterns"><code class="xref py py-func docutils literal"><span class="pre">ignore_patterns()</span></code></a>可用于创建基于glob样式模式忽略名称的可调用方法。</span></p><p><span class="yiyi-st" id="yiyi-107">如果发生异常，则会出现一个<a class="reference internal" href="#shutil.Error" title="shutil.Error"><code class="xref py py-exc docutils literal"><span class="pre">Error</span></code></a>与一系列原因。</span></p><p><span class="yiyi-st" id="yiyi-108">如果给定<em>copy_function</em>，它必须是一个可调用的，将用于复制每个文件。</span><span class="yiyi-st" id="yiyi-109">它将使用源路径和目标路径作为参数进行调用。</span><span class="yiyi-st" id="yiyi-110">默认情况下，使用<a class="reference internal" href="#shutil.copy2" title="shutil.copy2"><code class="xref py py-func docutils literal"><span class="pre">shutil.copy2()</span></code></a>，但可以使用支持相同声明的任何函数（如<a class="reference internal" href="#shutil.copy" title="shutil.copy"><code class="xref py py-func docutils literal"><span class="pre">shutil.copy()</span></code></a>）。</span></p><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-111"><span class="versionmodified">在版本3.3中更改：</span>在<em>符号链接</em>为false时，复制元数据。</span><span class="yiyi-st" id="yiyi-112">现在返回<em>dst</em>。</span></p></div><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-113"><span class="versionmodified">在版本3.2中已更改：</span>添加了<em>copy_function</em>参数，以便能够提供自定义复制功能。</span><span class="yiyi-st" id="yiyi-114">在<em>符号链接</em>为假时，对静默挂起符号链接错误添加<em>ignore_dangling_symlinks</em>参数。</span></p></div></dd></dl><dl class="function"><dt id="shutil.rmtree"><span class="yiyi-st" id="yiyi-115"> <code class="descclassname">shutil.</code><code class="descname">rmtree</code><span class="sig-paren">(</span><em>path</em>, <em>ignore_errors=False</em>, <em>onerror=None</em><span class="sig-paren">)</span></span></dt><dd><p id="index-1"><span class="yiyi-st" id="yiyi-116">删除整个目录树； <em>路径</em>必须指向目录（而不是指向目录的符号链接）。</span><span class="yiyi-st" id="yiyi-117">如果<em>ignore_errors</em>为true，则删除失败导致的错误将被忽略；如果为false或省略，则通过调用<em>onerror</em>指定的处理程序处理这些错误，如果省略，则引发异常。</span></p><div class="admonition note"><p class="first admonition-title"><span class="yiyi-st" id="yiyi-118">注意</span></p><p class="last"><span class="yiyi-st" id="yiyi-119">在支持必要的基于fd的函数的平台上，默认使用<a class="reference internal" href="#shutil.rmtree" title="shutil.rmtree"><code class="xref py py-func docutils literal"><span class="pre">rmtree()</span></code></a>的符号链接攻击防御版本。</span><span class="yiyi-st" id="yiyi-120">在其他平台上，<a class="reference internal" href="#shutil.rmtree" title="shutil.rmtree"><code class="xref py py-func docutils literal"><span class="pre">rmtree()</span></code></a>实现容易受到符号链接攻击：在适当的时间和情况下，攻击者可以操作文件系统上的符号链接以删除他们无法访问的文件。</span><span class="yiyi-st" id="yiyi-121">应用程序可以使用<a class="reference internal" href="#shutil.rmtree.avoids_symlink_attacks" title="shutil.rmtree.avoids_symlink_attacks"><code class="xref py py-data docutils literal"><span class="pre">rmtree.avoids_symlink_attacks</span></code></a>函数属性来确定适用哪种情况。</span></p></div><p><span class="yiyi-st" id="yiyi-122">如果提供<em>onerror</em>，它必须是可接受三个参数的可调用：<em>函数</em>，<em>路径</em>和<em>excinfo</em>。</span></p><p><span class="yiyi-st" id="yiyi-123">第一个参数<em>function</em>是引发异常的函数；它取决于平台和实现。</span><span class="yiyi-st" id="yiyi-124">第二个参数<em>path</em>将是传递给<em>函数</em>的路径名。</span><span class="yiyi-st" id="yiyi-125">第三个参数<em>excinfo</em>将是<a class="reference internal" href="sys.html#sys.exc_info" title="sys.exc_info"><code class="xref py py-func docutils literal"><span class="pre">sys.exc_info()</span></code></a>返回的异常信息。</span><span class="yiyi-st" id="yiyi-126">将不会捕获<em>onerror</em>引发的异常。</span></p><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-127"><span class="versionmodified">在版本3.3中已更改：</span>添加了一个符合symlink攻击的版本，如果平台支持基于fd的函数，则会自动使用该版本。</span></p></div><dl class="attribute"><dt id="shutil.rmtree.avoids_symlink_attacks"><span class="yiyi-st" id="yiyi-128"> <code class="descclassname">rmtree.</code><code class="descname">avoids_symlink_attacks</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-129">指示当前平台和实现是否提供<a class="reference internal" href="#shutil.rmtree" title="shutil.rmtree"><code class="xref py py-func docutils literal"><span class="pre">rmtree()</span></code></a>的符号链接攻击抵御版本。</span><span class="yiyi-st" id="yiyi-130">目前，这只适用于支持基于fd的目录访问功能的平台。</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-131"><span class="versionmodified">版本3.3中的新功能。</span></span></p></div></dd></dl></dd></dl><dl class="function"><dt id="shutil.move"><span class="yiyi-st" id="yiyi-132"> <code class="descclassname">shutil.</code><code class="descname">move</code><span class="sig-paren">(</span><em>src</em>, <em>dst</em>, <em>copy_function=copy2</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-133">递归地将文件或目录（<em>src</em>）移动到另一个位置（<em>dst</em>），并返回目标。</span></p><p><span class="yiyi-st" id="yiyi-134">如果目标是现有目录，则<em>src</em>在该目录中移动。</span><span class="yiyi-st" id="yiyi-135">如果目标已经存在，但不是目录，根据<a class="reference internal" href="os.html#os.rename" title="os.rename"><code class="xref py py-func docutils literal"><span class="pre">os.rename()</span></code></a>语义，它可能会被覆盖。</span></p><p><span class="yiyi-st" id="yiyi-136">如果目标位于当前文件系统上，则使用<a class="reference internal" href="os.html#os.rename" title="os.rename"><code class="xref py py-func docutils literal"><span class="pre">os.rename()</span></code></a>。</span><span class="yiyi-st" id="yiyi-137">否则，使用<em>copy_function</em>将<em>src</em>复制到<em>dst</em>，然后删除。</span><span class="yiyi-st" id="yiyi-138">在符号链接的情况下，指向<em>src</em>的目标的新符号链接将在<em>dst</em>中创建或创建，<em>src</em>将被删除。</span></p><p><span class="yiyi-st" id="yiyi-139">如果给出<em>copy_function</em>，它必须是一个可调用，它接受两个参数<em>src</em>和<em>dst</em>，并且将用于复制<em>src 到<em>dest</em>如果<a class="reference internal" href="os.html#os.rename" title="os.rename"><code class="xref py py-func docutils literal"><span class="pre">os.rename()</span></code></a>不能使用。</em></span><span class="yiyi-st" id="yiyi-140">如果源是目录，则调用<a class="reference internal" href="#shutil.copytree" title="shutil.copytree"><code class="xref py py-func docutils literal"><span class="pre">copytree()</span></code></a>，将其传递给<code class="xref py py-func docutils literal"><span class="pre">copy_function()</span></code>。</span><span class="yiyi-st" id="yiyi-141">默认的<em>copy_function</em>是<a class="reference internal" href="#shutil.copy2" title="shutil.copy2"><code class="xref py py-func docutils literal"><span class="pre">copy2()</span></code></a>。</span><span class="yiyi-st" id="yiyi-142">使用<a class="reference internal" href="copy.html#module-copy" title="copy: Shallow and deep copy operations."><code class="xref py py-func docutils literal"><span class="pre">copy()</span></code></a>作为<em>copy_function</em>允许移动成功，当不可能也复制元数据，而不复制任何元数据。</span></p><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-143"><span class="versionmodified">在版本3.3中已更改：</span>为外部文件系统添加了显式符号链接处理，从而使其适应GNU的<strong class="program">mv</strong>的行为。</span><span class="yiyi-st" id="yiyi-144">现在返回<em>dst</em>。</span></p></div><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-145"><span class="versionmodified">在版本3.5中已更改：</span>添加了<em>copy_function</em>关键字参数。</span></p></div></dd></dl><dl class="function"><dt id="shutil.disk_usage"><span class="yiyi-st" id="yiyi-146"> <code class="descclassname">shutil.</code><code class="descname">disk_usage</code><span class="sig-paren">(</span><em>path</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-147">将给定路径的磁盘使用情况统计信息作为<a class="reference internal" href="../glossary.html#term-named-tuple"><span class="xref std std-term">named tuple</span></a>返回<em>总计</em>，使用<em>和<em>免费</em>是总的，已用和可用空间的量，以字节为单位。</em></span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-148"><span class="versionmodified">版本3.3中的新功能。</span></span></p></div><p><span class="yiyi-st" id="yiyi-149">可用性：Unix，Windows。</span></p></dd></dl><dl class="function"><dt id="shutil.chown"><span class="yiyi-st" id="yiyi-150"> <code class="descclassname">shutil.</code><code class="descname">chown</code><span class="sig-paren">(</span><em>path</em>, <em>user=None</em>, <em>group=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-151">更改给定<em>路径</em>的所有者<em>用户</em>和/或<em>组</em>。</span></p><p><span class="yiyi-st" id="yiyi-152"><em>用户</em>可以是系统用户名或uid；这同样适用于<em>组</em>。</span><span class="yiyi-st" id="yiyi-153">至少需要一个参数。</span></p><p><span class="yiyi-st" id="yiyi-154">另请参见底层函数<a class="reference internal" href="os.html#os.chown" title="os.chown"><code class="xref py py-func docutils literal"><span class="pre">os.chown()</span></code></a>。</span></p><p><span class="yiyi-st" id="yiyi-155">可用性：Unix。</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-156"><span class="versionmodified">版本3.3中的新功能。</span></span></p></div></dd></dl><dl class="function"><dt id="shutil.which"><span class="yiyi-st" id="yiyi-157"> <code class="descclassname">shutil.</code><code class="descname">which</code><span class="sig-paren">(</span><em>cmd</em>, <em>mode=os.F_OK | os.X_OK</em>, <em>path=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-158">返回可执行文件的路径，如果给定的<em>cmd</em>被调用，它将运行。</span><span class="yiyi-st" id="yiyi-159">如果不调用<em>cmd</em>，则返回<code class="docutils literal"><span class="pre">None</span></code>。</span></p><p><span class="yiyi-st" id="yiyi-160"><em>mode</em>是传递给<a class="reference internal" href="os.html#os.access" title="os.access"><code class="xref py py-func docutils literal"><span class="pre">os.access()</span></code></a>的权限掩码，默认情况下确定文件是否存在和可执行。</span></p><p><span class="yiyi-st" id="yiyi-161">当未指定<em>路径</em>时，将使用<a class="reference internal" href="os.html#os.environ" title="os.environ"><code class="xref py py-func docutils literal"><span class="pre">os.environ()</span></code></a>的结果，返回“PATH”值或返回<a class="reference internal" href="os.html#os.defpath" title="os.defpath"><code class="xref py py-attr docutils literal"><span class="pre">os.defpath</span></code></a></span></p><p><span class="yiyi-st" id="yiyi-162">在Windows上，当前目录始终位于<em>路径</em>之前，无论是使用默认路径还是提供自己的路径，这是命令shell在查找可执行文件时使用的行为。</span><span class="yiyi-st" id="yiyi-163">此外，在<em>路径</em>中找到<em>cmd</em>时，会检查<code class="docutils literal"><span class="pre">PATHEXT</span></code>环境变量。</span><span class="yiyi-st" id="yiyi-164">For example, if you call <code class="docutils literal"><span class="pre">shutil.which("python")</span></code>, <a class="reference internal" href="#shutil.which" title="shutil.which"><code class="xref py py-func docutils literal"><span class="pre">which()</span></code></a> will search <code class="docutils literal"><span class="pre">PATHEXT</span></code> to know that it should look for <code class="docutils literal"><span class="pre">python.exe</span></code> within the <em>path</em> directories. </span><span class="yiyi-st" id="yiyi-165">例如，在Windows上：</span></p><div class="highlight-python3"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">shutil</span><span class="o">.</span><span class="n">which</span><span class="p">(</span><span class="s2">"python"</span><span class="p">)</span>
<span class="go">'C:\\Python33\\python.EXE'</span>
</pre></div></div><div class="versionadded"><p><span class="yiyi-st" id="yiyi-166"><span class="versionmodified">版本3.3中的新功能。</span></span></p></div></dd></dl><dl class="exception"><dt id="shutil.Error"><span class="yiyi-st" id="yiyi-167"> <em class="property">exception </em><code class="descclassname">shutil.</code><code class="descname">Error</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-168">此异常收集在多文件操作期间引发的异常。</span><span class="yiyi-st" id="yiyi-169">对于<a class="reference internal" href="#shutil.copytree" title="shutil.copytree"><code class="xref py py-func docutils literal"><span class="pre">copytree()</span></code></a>，异常参数是3元组的列表（<em>srcname</em>，<em>dstname</em>，<em>异常</em>） 。</span></p></dd></dl><div class="section" id="copytree-example"><h3><span class="yiyi-st" id="yiyi-170">11.10.1.1. copytree示例</span></h3><p><span class="yiyi-st" id="yiyi-171">这个例子是上面描述的<a class="reference internal" href="#shutil.copytree" title="shutil.copytree"><code class="xref py py-func docutils literal"><span class="pre">copytree()</span></code></a>函数的实现，省略了docstring。</span><span class="yiyi-st" id="yiyi-172">它演示了此模块提供的许多其他功能。</span></p><div class="highlight-python3"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">copytree</span><span class="p">(</span><span class="n">src</span><span class="p">,</span> <span class="n">dst</span><span class="p">,</span> <span class="n">symlinks</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>
<span class="n">names</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">listdir</span><span class="p">(</span><span class="n">src</span><span class="p">)</span>
<span class="n">os</span><span class="o">.</span><span class="n">makedirs</span><span class="p">(</span><span class="n">dst</span><span class="p">)</span>
<span class="n">errors</span> <span class="o">=</span> <span class="p">[]</span>
<span class="k">for</span> <span class="n">name</span> <span class="ow">in</span> <span class="n">names</span><span class="p">:</span>
<span class="n">srcname</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">join</span><span class="p">(</span><span class="n">src</span><span class="p">,</span> <span class="n">name</span><span class="p">)</span>
<span class="n">dstname</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">join</span><span class="p">(</span><span class="n">dst</span><span class="p">,</span> <span class="n">name</span><span class="p">)</span>
<span class="k">try</span><span class="p">:</span>
<span class="k">if</span> <span class="n">symlinks</span> <span class="ow">and</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">islink</span><span class="p">(</span><span class="n">srcname</span><span class="p">):</span>
<span class="n">linkto</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">readlink</span><span class="p">(</span><span class="n">srcname</span><span class="p">)</span>
<span class="n">os</span><span class="o">.</span><span class="n">symlink</span><span class="p">(</span><span class="n">linkto</span><span class="p">,</span> <span class="n">dstname</span><span class="p">)</span>
<span class="k">elif</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">isdir</span><span class="p">(</span><span class="n">srcname</span><span class="p">):</span>
<span class="n">copytree</span><span class="p">(</span><span class="n">srcname</span><span class="p">,</span> <span class="n">dstname</span><span class="p">,</span> <span class="n">symlinks</span><span class="p">)</span>
<span class="k">else</span><span class="p">:</span>
<span class="n">copy2</span><span class="p">(</span><span class="n">srcname</span><span class="p">,</span> <span class="n">dstname</span><span class="p">)</span>
<span class="c1"># XXX What about devices, sockets etc.?</span>
<span class="k">except</span> <span class="ne">OSError</span> <span class="k">as</span> <span class="n">why</span><span class="p">:</span>
<span class="n">errors</span><span class="o">.</span><span class="n">append</span><span class="p">((</span><span class="n">srcname</span><span class="p">,</span> <span class="n">dstname</span><span class="p">,</span> <span class="nb">str</span><span class="p">(</span><span class="n">why</span><span class="p">)))</span>
<span class="c1"># catch the Error from the recursive copytree so that we can</span>
<span class="c1"># continue with other files</span>
<span class="k">except</span> <span class="n">Error</span> <span class="k">as</span> <span class="n">err</span><span class="p">:</span>
<span class="n">errors</span><span class="o">.</span><span class="n">extend</span><span class="p">(</span><span class="n">err</span><span class="o">.</span><span class="n">args</span><span class="p">[</span><span class="mi">0</span><span class="p">])</span>
<span class="k">try</span><span class="p">:</span>
<span class="n">copystat</span><span class="p">(</span><span class="n">src</span><span class="p">,</span> <span class="n">dst</span><span class="p">)</span>
<span class="k">except</span> <span class="ne">OSError</span> <span class="k">as</span> <span class="n">why</span><span class="p">:</span>
<span class="c1"># can't copy file access times on Windows</span>
<span class="k">if</span> <span class="n">why</span><span class="o">.</span><span class="n">winerror</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
<span class="n">errors</span><span class="o">.</span><span class="n">extend</span><span class="p">((</span><span class="n">src</span><span class="p">,</span> <span class="n">dst</span><span class="p">,</span> <span class="nb">str</span><span class="p">(</span><span class="n">why</span><span class="p">)))</span>
<span class="k">if</span> <span class="n">errors</span><span class="p">:</span>
<span class="k">raise</span> <span class="n">Error</span><span class="p">(</span><span class="n">errors</span><span class="p">)</span>
</pre></div></div><p><span class="yiyi-st" id="yiyi-173">使用<a class="reference internal" href="#shutil.ignore_patterns" title="shutil.ignore_patterns"><code class="xref py py-func docutils literal"><span class="pre">ignore_patterns()</span></code></a>帮助程序的另一个示例：</span></p><div class="highlight-python3"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">shutil</span> <span class="k">import</span> <span class="n">copytree</span><span class="p">,</span> <span class="n">ignore_patterns</span>
<span class="n">copytree</span><span class="p">(</span><span class="n">source</span><span class="p">,</span> <span class="n">destination</span><span class="p">,</span> <span class="n">ignore</span><span class="o">=</span><span class="n">ignore_patterns</span><span class="p">(</span><span class="s1">'*.pyc'</span><span class="p">,</span> <span class="s1">'tmp*'</span><span class="p">))</span>
</pre></div></div><p><span class="yiyi-st" id="yiyi-174">这将复制除<code class="docutils literal"><span class="pre">.pyc</span></code>文件和名称以<code class="docutils literal"><span class="pre">tmp</span></code>开头的文件或目录之外的所有内容。</span></p><p><span class="yiyi-st" id="yiyi-175">使用<em>ignore</em>参数添加日志调用的另一个示例：</span></p><div class="highlight-python3"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">shutil</span> <span class="k">import</span> <span class="n">copytree</span>
<span class="kn">import</span> <span class="nn">logging</span>
<span class="k">def</span> <span class="nf">_logpath</span><span class="p">(</span><span class="n">path</span><span class="p">,</span> <span class="n">names</span><span class="p">):</span>
<span class="n">logging</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">'Working in </span><span class="si">%s</span><span class="s1">'</span> <span class="o">%</span> <span class="n">path</span><span class="p">)</span>
<span class="k">return</span> <span class="p">[]</span> <span class="c1"># nothing will be ignored</span>
<span class="n">copytree</span><span class="p">(</span><span class="n">source</span><span class="p">,</span> <span class="n">destination</span><span class="p">,</span> <span class="n">ignore</span><span class="o">=</span><span class="n">_logpath</span><span class="p">)</span>
</pre></div></div></div><div class="section" id="rmtree-example"><h3><span class="yiyi-st" id="yiyi-176">11.10.1.2. rmtree示例</span></h3><p><span class="yiyi-st" id="yiyi-177">此示例显示如何在Windows上删除目录树，其中一些文件的只读位集已设置。</span><span class="yiyi-st" id="yiyi-178">它使用onerror回调来清除readonly位并重新尝试删除。</span><span class="yiyi-st" id="yiyi-179">任何后续故障都会传播。</span></p><div class="highlight-python3"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">os</span><span class="o">,</span> <span class="nn">stat</span>
<span class="kn">import</span> <span class="nn">shutil</span>
<span class="k">def</span> <span class="nf">remove_readonly</span><span class="p">(</span><span class="n">func</span><span class="p">,</span> <span class="n">path</span><span class="p">,</span> <span class="n">_</span><span class="p">):</span>
<span class="s2">"Clear the readonly bit and reattempt the removal"</span>
<span class="n">os</span><span class="o">.</span><span class="n">chmod</span><span class="p">(</span><span class="n">path</span><span class="p">,</span> <span class="n">stat</span><span class="o">.</span><span class="n">S_IWRITE</span><span class="p">)</span>
<span class="n">func</span><span class="p">(</span><span class="n">path</span><span class="p">)</span>
<span class="n">shutil</span><span class="o">.</span><span class="n">rmtree</span><span class="p">(</span><span class="n">directory</span><span class="p">,</span> <span class="n">onerror</span><span class="o">=</span><span class="n">remove_readonly</span><span class="p">)</span>
</pre></div></div></div></div><div class="section" id="archiving-operations"><h2><span class="yiyi-st" id="yiyi-180">11.10.2.</span><span class="yiyi-st" id="yiyi-181">归档操作</span></h2><div class="versionadded"><p><span class="yiyi-st" id="yiyi-182"><span class="versionmodified">版本3.2中的新功能。</span></span></p></div><p><span class="yiyi-st" id="yiyi-183">还提供了用于创建和读取压缩和归档文件的高级实用程序。</span><span class="yiyi-st" id="yiyi-184">它们依赖于<a class="reference internal" href="zipfile.html#module-zipfile" title="zipfile: Read and write ZIP-format archive files."><code class="xref py py-mod docutils literal"><span class="pre">zipfile</span></code></a>和<a class="reference internal" href="tarfile.html#module-tarfile" title="tarfile: Read and write tar-format archive files."><code class="xref py py-mod docutils literal"><span class="pre">tarfile</span></code></a>模块。</span></p><dl class="function"><dt id="shutil.make_archive"><span class="yiyi-st" id="yiyi-185"> <code class="descclassname">shutil.</code><code class="descname">make_archive</code><span class="sig-paren">(</span><em>base_name</em>, <em>format</em><span class="optional">[</span>, <em>root_dir</em><span class="optional">[</span>, <em>base_dir</em><span class="optional">[</span>, <em>verbose</em><span class="optional">[</span>, <em>dry_run</em><span class="optional">[</span>, <em>owner</em><span class="optional">[</span>, <em>group</em><span class="optional">[</span>, <em>logger</em><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-186">创建归档文件（例如zip或tar）并返回其名称。</span></p><p><span class="yiyi-st" id="yiyi-187"><em>base_name</em>是要创建的文件的名称，包括路径，减去任何特定于格式的扩展名。</span><span class="yiyi-st" id="yiyi-188"><em>format</em> is the archive format: one of “zip”, “tar”, “bztar” (if the <a class="reference internal" href="bz2.html#module-bz2" title="bz2: Interfaces for bzip2 compression and decompression."><code class="xref py py-mod docutils literal"><span class="pre">bz2</span></code></a> module is available), “xztar” (if the <a class="reference internal" href="lzma.html#module-lzma" title="lzma: A Python wrapper for the liblzma compression library."><code class="xref py py-mod docutils literal"><span class="pre">lzma</span></code></a> module is available) or “gztar”.</span></p><p><span class="yiyi-st" id="yiyi-189"><em>root_dir</em>是将成为归档的根目录的目录；例如，在创建归档之前，我们通常将chdir插入到<em>root_dir</em>中。</span></p><p><span class="yiyi-st" id="yiyi-190"><em>base_dir</em>是我们开始归档的目录；即：</span><span class="yiyi-st" id="yiyi-191"><em>base_dir</em>将是归档中所有文件和目录的公共前缀。</span></p><p><span class="yiyi-st" id="yiyi-192"><em>root_dir</em>和<em>base_dir</em>都默认为当前目录。</span></p><p><span class="yiyi-st" id="yiyi-193">如果<em>dry_run</em>为true，则不创建归档，但将执行的操作记录到<em>logger</em>。</span></p><p><span class="yiyi-st" id="yiyi-194"><em>所有者</em>和<em>组</em>用于创建tar存档。</span><span class="yiyi-st" id="yiyi-195">默认情况下，使用当前所有者和组。</span></p><p><span class="yiyi-st" id="yiyi-196"><em>logger</em>必须是与<span class="target" id="index-2"></span> <a class="pep reference external" href="https://www.python.org/dev/peps/pep-0282"><strong>PEP 282</strong></a>兼容的对象，通常为<a class="reference internal" href="logging.html#logging.Logger" title="logging.Logger"><code class="xref py py-class docutils literal"><span class="pre">logging.Logger</span></code></a>的实例。</span></p><p><span class="yiyi-st" id="yiyi-197"><em>verbose</em>参数未使用且已弃用。</span></p><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-198"><span class="versionmodified">在3.5版本中进行了更改：</span>添加了对<em>xztar</em>格式的支持。</span></p></div></dd></dl><dl class="function"><dt id="shutil.get_archive_formats"><span class="yiyi-st" id="yiyi-199"> <code class="descclassname">shutil.</code><code class="descname">get_archive_formats</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-200">返回支持的归档格式列表。</span><span class="yiyi-st" id="yiyi-201">返回序列的每个元素都是元组<code class="docutils literal"><span class="pre">（名称，</span> <span class="pre">描述）</span></code>。</span></p><p><span class="yiyi-st" id="yiyi-202">默认情况下，<a class="reference internal" href="#module-shutil" title="shutil: High-level file operations, including copying."><code class="xref py py-mod docutils literal"><span class="pre">shutil</span></code></a>提供以下格式：</span></p><ul class="simple"><li><span class="yiyi-st" id="yiyi-203"><em>gztar</em>：gzip的tar文件</span></li><li><span class="yiyi-st" id="yiyi-204"><em>bztar</em>：bzip2'ed tar文件（如果<a class="reference internal" href="bz2.html#module-bz2" title="bz2: Interfaces for bzip2 compression and decompression."><code class="xref py py-mod docutils literal"><span class="pre">bz2</span></code></a>模块可用）。</span></li><li><span class="yiyi-st" id="yiyi-205"><em>xztar</em>：xz'ed tar文件（如果<a class="reference internal" href="lzma.html#module-lzma" title="lzma: A Python wrapper for the liblzma compression library."><code class="xref py py-mod docutils literal"><span class="pre">lzma</span></code></a>模块可用）。</span></li><li><span class="yiyi-st" id="yiyi-206"><em>tar</em>：未压缩的tar文件</span></li><li><span class="yiyi-st" id="yiyi-207"><em>zip</em>：ZIP文件</span></li></ul><p><span class="yiyi-st" id="yiyi-208">您可以使用<a class="reference internal" href="#shutil.register_archive_format" title="shutil.register_archive_format"><code class="xref py py-func docutils literal"><span class="pre">register_archive_format()</span></code></a>注册新格式或为任何现有格式提供自己的存档。</span></p></dd></dl><dl class="function"><dt id="shutil.register_archive_format"><span class="yiyi-st" id="yiyi-209"> <code class="descclassname">shutil.</code><code class="descname">register_archive_format</code><span class="sig-paren">(</span><em>name</em>, <em>function</em><span class="optional">[</span>, <em>extra_args</em><span class="optional">[</span>, <em>description</em><span class="optional">]</span><span class="optional">]</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-210">为格式<em>名称</em>注册档案库。</span></p><p><span class="yiyi-st" id="yiyi-211"><em>函数</em>是将用于分拆归档的可调用项。</span><span class="yiyi-st" id="yiyi-212">可调用程序将接收要创建的文件的<em>base_name</em>，然后是<em>base_dir</em>（默认为<a class="reference internal" href="os.html#os.curdir" title="os.curdir"><code class="xref py py-data docutils literal"><span class="pre">os.curdir</span></code></a>）以开始归档。</span><span class="yiyi-st" id="yiyi-213">Further arguments are passed as keyword arguments: <em>owner</em>, <em>group</em>, <em>dry_run</em> and <em>logger</em> (as passed in <a class="reference internal" href="#shutil.make_archive" title="shutil.make_archive"><code class="xref py py-func docutils literal"><span class="pre">make_archive()</span></code></a>).</span></p><p><span class="yiyi-st" id="yiyi-214">如果给定，<em>extra_args</em>是将被用作额外关键字参数的<code class="docutils literal"><span class="pre">（名称，</span> <span class="pre">值）</span> 当使用archiver callable时。</code></span></p><p><span class="yiyi-st" id="yiyi-215"><em>description</em>由<a class="reference internal" href="#shutil.get_archive_formats" title="shutil.get_archive_formats"><code class="xref py py-func docutils literal"><span class="pre">get_archive_formats()</span></code></a>使用，返回归档列表。</span><span class="yiyi-st" id="yiyi-216">默认为空字符串。</span></p></dd></dl><dl class="function"><dt id="shutil.unregister_archive_format"><span class="yiyi-st" id="yiyi-217"> <code class="descclassname">shutil.</code><code class="descname">unregister_archive_format</code><span class="sig-paren">(</span><em>name</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-218">从支持的格式列表中删除归档格式<em>名称</em>。</span></p></dd></dl><dl class="function"><dt id="shutil.unpack_archive"><span class="yiyi-st" id="yiyi-219"> <code class="descclassname">shutil.</code><code class="descname">unpack_archive</code><span class="sig-paren">(</span><em>filename</em><span class="optional">[</span>, <em>extract_dir</em><span class="optional">[</span>, <em>format</em><span class="optional">]</span><span class="optional">]</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-220">分拆归档。</span><span class="yiyi-st" id="yiyi-221"><em>filename</em>是归档的完整路径。</span></p><p><span class="yiyi-st" id="yiyi-222"><em>extract_dir</em>是解压缩归档的目标目录的名称。</span><span class="yiyi-st" id="yiyi-223">如果未提供，则使用当前工作目录。</span></p><p><span class="yiyi-st" id="yiyi-224"><em>格式</em>是存档格式：“zip”，“tar”或“gztar”之一。</span><span class="yiyi-st" id="yiyi-225">或使用<a class="reference internal" href="#shutil.register_unpack_format" title="shutil.register_unpack_format"><code class="xref py py-func docutils literal"><span class="pre">register_unpack_format()</span></code></a>注册的任何其他格式。</span><span class="yiyi-st" id="yiyi-226">如果未提供，<a class="reference internal" href="#shutil.unpack_archive" title="shutil.unpack_archive"><code class="xref py py-func docutils literal"><span class="pre">unpack_archive()</span></code></a>将使用存档文件扩展名，查看是否为该扩展插件注册了解包程序。</span><span class="yiyi-st" id="yiyi-227">如果没有找到，则会引发<a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal"><span class="pre">ValueError</span></code></a>。</span></p></dd></dl><dl class="function"><dt id="shutil.register_unpack_format"><span class="yiyi-st" id="yiyi-228"> <code class="descclassname">shutil.</code><code class="descname">register_unpack_format</code><span class="sig-paren">(</span><em>name</em>, <em>extensions</em>, <em>function</em><span class="optional">[</span>, <em>extra_args</em><span class="optional">[</span>, <em>description</em><span class="optional">]</span><span class="optional">]</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-229">注册分拆格式。</span><span class="yiyi-st" id="yiyi-230"><em>名称</em>是格式的名称，<em>扩展</em>是对应于格式的扩展名列表，如<code class="docutils literal"><span class="pre">.zip</span></code>用于Zip文件。</span></p><p><span class="yiyi-st" id="yiyi-231"><em>函数</em>是将用于分拆归档的可调用项。</span><span class="yiyi-st" id="yiyi-232">可调用程序将接收归档的路径，然后是归档必须提取到的目录。</span></p><p><span class="yiyi-st" id="yiyi-233">提供时，<em>extra_args</em>是将作为关键字参数传递的元组的<code class="docutils literal"><span class="pre">（名称，</span> <span class="pre">值）</span> 可调。</code></span></p><p><span class="yiyi-st" id="yiyi-234"><em>description</em>可用于描述格式，并由<a class="reference internal" href="#shutil.get_unpack_formats" title="shutil.get_unpack_formats"><code class="xref py py-func docutils literal"><span class="pre">get_unpack_formats()</span></code></a>函数返回。</span></p></dd></dl><dl class="function"><dt id="shutil.unregister_unpack_format"><span class="yiyi-st" id="yiyi-235"> <code class="descclassname">shutil.</code><code class="descname">unregister_unpack_format</code><span class="sig-paren">(</span><em>name</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-236">取消注册分拆格式。</span><span class="yiyi-st" id="yiyi-237"><em>name</em>是格式的名称。</span></p></dd></dl><dl class="function"><dt id="shutil.get_unpack_formats"><span class="yiyi-st" id="yiyi-238"> <code class="descclassname">shutil.</code><code class="descname">get_unpack_formats</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-239">返回分拆的所有注册格式的列表。</span><span class="yiyi-st" id="yiyi-240">返回序列的每个元素都是元组<code class="docutils literal"><span class="pre">（名称，</span> <span class="pre">扩展名，</span> <span class="pre">描述）</span></code>。</span></p><p><span class="yiyi-st" id="yiyi-241">默认情况下，<a class="reference internal" href="#module-shutil" title="shutil: High-level file operations, including copying."><code class="xref py py-mod docutils literal"><span class="pre">shutil</span></code></a>提供以下格式：</span></p><ul class="simple"><li><span class="yiyi-st" id="yiyi-242"><em>gztar</em>：gzip的tar文件</span></li><li><span class="yiyi-st" id="yiyi-243"><em>bztar</em>：bzip2'ed tar文件（如果<a class="reference internal" href="bz2.html#module-bz2" title="bz2: Interfaces for bzip2 compression and decompression."><code class="xref py py-mod docutils literal"><span class="pre">bz2</span></code></a>模块可用）。</span></li><li><span class="yiyi-st" id="yiyi-244"><em>xztar</em>：xz'ed tar文件（如果<a class="reference internal" href="lzma.html#module-lzma" title="lzma: A Python wrapper for the liblzma compression library."><code class="xref py py-mod docutils literal"><span class="pre">lzma</span></code></a>模块可用）。</span></li><li><span class="yiyi-st" id="yiyi-245"><em>tar</em>：未压缩的tar文件</span></li><li><span class="yiyi-st" id="yiyi-246"><em>zip</em>：ZIP文件</span></li></ul><p><span class="yiyi-st" id="yiyi-247">您可以使用<a class="reference internal" href="#shutil.register_unpack_format" title="shutil.register_unpack_format"><code class="xref py py-func docutils literal"><span class="pre">register_unpack_format()</span></code></a>注册新格式或为任何现有格式提供自己的解压缩程序。</span></p></dd></dl><div class="section" id="archiving-example"><h3><span class="yiyi-st" id="yiyi-248">11.10.2.1。</span><span class="yiyi-st" id="yiyi-249">Archiving example</span></h3><p><span class="yiyi-st" id="yiyi-250">在本示例中，我们创建一个gzip的tar文件归档，其中包含用户的<code class="file docutils literal"><span class="pre">.ssh</span></code>目录中找到的所有文件：</span></p><div class="highlight-python3"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">shutil</span> <span class="k">import</span> <span class="n">make_archive</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">os</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">archive_name</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">expanduser</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="s1">'~'</span><span class="p">,</span> <span class="s1">'myarchive'</span><span class="p">))</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">root_dir</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">expanduser</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="s1">'~'</span><span class="p">,</span> <span class="s1">'.ssh'</span><span class="p">))</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">make_archive</span><span class="p">(</span><span class="n">archive_name</span><span class="p">,</span> <span class="s1">'gztar'</span><span class="p">,</span> <span class="n">root_dir</span><span class="p">)</span>
<span class="go">'/Users/tarek/myarchive.tar.gz'</span>
</pre></div></div><p><span class="yiyi-st" id="yiyi-251">生成的归档包含：</span></p><div class="highlight-shell-session"><div class="highlight"><pre><span></span><span class="gp">$</span> tar -tzvf /Users/tarek/myarchive.tar.gz
<span class="go">drwx------ tarek/staff 0 2010-02-01 16:23:40 ./</span>
<span class="go">-rw-r--r-- tarek/staff 609 2008-06-09 13:26:54 ./authorized_keys</span>
<span class="go">-rwxr-xr-x tarek/staff 65 2008-06-09 13:26:54 ./config</span>
<span class="go">-rwx------ tarek/staff 668 2008-06-09 13:26:54 ./id_dsa</span>
<span class="go">-rwxr-xr-x tarek/staff 609 2008-06-09 13:26:54 ./id_dsa.pub</span>
<span class="go">-rw------- tarek/staff 1675 2008-06-09 13:26:54 ./id_rsa</span>
<span class="go">-rw-r--r-- tarek/staff 397 2008-06-09 13:26:54 ./id_rsa.pub</span>
<span class="go">-rw-r--r-- tarek/staff 37192 2010-02-06 18:23:10 ./known_hosts</span>
</pre></div></div></div></div><div class="section" id="querying-the-size-of-the-output-terminal"><h2><span class="yiyi-st" id="yiyi-252">11.10.3。</span><span class="yiyi-st" id="yiyi-253">查询输出终端的大小</span></h2><div class="versionadded"><p><span class="yiyi-st" id="yiyi-254"><span class="versionmodified">版本3.3中的新功能。</span></span></p></div><dl class="function"><dt id="shutil.get_terminal_size"><span class="yiyi-st" id="yiyi-255"> <code class="descclassname">shutil.</code><code class="descname">get_terminal_size</code><span class="sig-paren">(</span><em>fallback=(columns</em>, <em>lines)</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-256">获取终端窗口的大小。</span></p><p><span class="yiyi-st" id="yiyi-257">对于两个维度中的每一个，分别检查环境变量<code class="docutils literal"><span class="pre">COLUMNS</span></code>和<code class="docutils literal"><span class="pre">LINES</span></code>。</span><span class="yiyi-st" id="yiyi-258">如果定义变量并且值为正整数，则使用它。</span></p><p><span class="yiyi-st" id="yiyi-259">When <code class="docutils literal"><span class="pre">COLUMNS</span></code> or <code class="docutils literal"><span class="pre">LINES</span></code> is not defined, which is the common case, the terminal connected to <a class="reference internal" href="sys.html#sys.__stdout__" title="sys.__stdout__"><code class="xref py py-data docutils literal"><span class="pre">sys.__stdout__</span></code></a> is queried by invoking <a class="reference internal" href="os.html#os.get_terminal_size" title="os.get_terminal_size"><code class="xref py py-func docutils literal"><span class="pre">os.get_terminal_size()</span></code></a>.</span></p><p><span class="yiyi-st" id="yiyi-260">如果无法成功查询终端大小，或者因为系统不支持查询，或者因为我们未连接到终端，则使用<code class="docutils literal"><span class="pre">fallback</span></code>参数中给出的值。</span><span class="yiyi-st" id="yiyi-261"><code class="docutils literal"><span class="pre">fallback</span></code>默认为许多终端仿真器使用的默认大小<code class="docutils literal"><span class="pre">（80，</span> <span class="pre">24）</span></code>。</span></p><p><span class="yiyi-st" id="yiyi-262">返回的值是类型为<a class="reference internal" href="os.html#os.terminal_size" title="os.terminal_size"><code class="xref py py-class docutils literal"><span class="pre">os.terminal_size</span></code></a>的命名元组。</span></p><p><span class="yiyi-st" id="yiyi-263">另请参阅：单UNIX规范第2版，<a class="reference external" href="http://pubs.opengroup.org/onlinepubs/7908799/xbd/envvar.html#tag_002_003">其他环境变量</a>。</span></p></dd></dl></div></div></div>
Reference in New Issue View Git Blame Copy Permalink