mirror of
https://github.com/fofolee/uTools-Manuals.git
synced 2025-06-09 23:44:06 +08:00
68 lines
66 KiB
HTML
68 lines
66 KiB
HTML
<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> <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> <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 >符号链接到新创建的<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><pre><code class="language-python"><span></span><span class="gp">>>> </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>
|
||
</code></pre><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><pre><code class="language-python"><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>
|
||
</code></pre><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><pre><code class="language-python"><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>
|
||
</code></pre><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><pre><code class="language-python"><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>
|
||
</code></pre></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><pre><code class="language-python"><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>
|
||
</code></pre></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><pre><code class="language-python"><span></span><span class="gp">>>> </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">>>> </span><span class="kn">import</span> <span class="nn">os</span>
|
||
<span class="gp">>>> </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">>>> </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">>>> </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>
|
||
</code></pre><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> |