1317 lines
144 KiB
HTML
1317 lines
144 KiB
HTML
|
||
<!DOCTYPE html>
|
||
|
||
<html xmlns="http://www.w3.org/1999/xhtml" lang="zh_CN">
|
||
<head>
|
||
<meta charset="utf-8" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
|
||
|
||
<title>tarfile --- 读写tar归档文件 — Python 3.8.20 文档</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
|
||
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
|
||
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
|
||
|
||
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
|
||
<script src="../_static/jquery.js"></script>
|
||
<script src="../_static/underscore.js"></script>
|
||
<script src="../_static/doctools.js"></script>
|
||
<script src="../_static/language_data.js"></script>
|
||
<script src="../_static/translations.js"></script>
|
||
|
||
<script src="../_static/sidebar.js"></script>
|
||
|
||
<link rel="search" type="application/opensearchdescription+xml"
|
||
title="在 Python 3.8.20 文档 中搜索"
|
||
href="../_static/opensearch.xml"/>
|
||
<link rel="author" title="关于这些文档" href="../about.html" />
|
||
<link rel="index" title="索引" href="../genindex.html" />
|
||
<link rel="search" title="搜索" href="../search.html" />
|
||
<link rel="copyright" title="版权所有" href="../copyright.html" />
|
||
<link rel="next" title="文件格式" href="fileformats.html" />
|
||
<link rel="prev" title="zipfile --- 使用ZIP存档" href="zipfile.html" />
|
||
<link rel="canonical" href="https://docs.python.org/3/library/tarfile.html" />
|
||
|
||
|
||
|
||
|
||
|
||
<style>
|
||
@media only screen {
|
||
table.full-width-table {
|
||
width: 100%;
|
||
}
|
||
}
|
||
</style>
|
||
<link rel="shortcut icon" type="image/png" href="../_static/py.svg" />
|
||
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
||
<script type="text/javascript" src="../_static/menu.js"></script>
|
||
|
||
</head>
|
||
<body>
|
||
<div class="mobile-nav">
|
||
<input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"
|
||
aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu" />
|
||
<label for="menuToggler" class="toggler__label">
|
||
<span></span>
|
||
</label>
|
||
<nav class="nav-content" role="navigation">
|
||
<a href="https://www.python.org/" class="nav-logo">
|
||
<img src="../_static/py.svg" alt="Logo"/>
|
||
</a>
|
||
<div class="version_switcher_placeholder"></div>
|
||
<form role="search" class="search" action="../search.html" method="get">
|
||
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">
|
||
<path fill-rule="nonzero"
|
||
d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z" fill="#444"></path>
|
||
</svg>
|
||
<input type="text" name="q" aria-label="快速搜索"/>
|
||
<input type="submit" value="转向"/>
|
||
</form>
|
||
</nav>
|
||
<div class="menu-wrapper">
|
||
<nav class="menu" role="navigation" aria-label="main navigation">
|
||
<div class="language_switcher_placeholder"></div>
|
||
<h3><a href="../contents.html">目录</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">tarfile</span></code> --- 读写tar归档文件</a><ul>
|
||
<li><a class="reference internal" href="#tarfile-objects">TarFile 对象</a></li>
|
||
<li><a class="reference internal" href="#tarinfo-objects">TarInfo 对象</a></li>
|
||
<li><a class="reference internal" href="#extraction-filters">解压缩过滤器</a><ul>
|
||
<li><a class="reference internal" href="#default-named-filters">默认的命名过滤器</a></li>
|
||
<li><a class="reference internal" href="#filter-errors">过滤器错误</a></li>
|
||
<li><a class="reference internal" href="#hints-for-further-verification">进一步核验的提示</a></li>
|
||
<li><a class="reference internal" href="#supporting-older-python-versions">支持较早的 Python 版本</a></li>
|
||
<li><a class="reference internal" href="#stateful-extraction-filter-example">有状态的提取过滤器示例</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#command-line-interface">命令行接口</a><ul>
|
||
<li><a class="reference internal" href="#command-line-options">命令行选项</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#examples">例子</a></li>
|
||
<li><a class="reference internal" href="#supported-tar-formats">受支持的 tar 格式</a></li>
|
||
<li><a class="reference internal" href="#unicode-issues">Unicode 问题</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<h4>上一个主题</h4>
|
||
<p class="topless"><a href="zipfile.html"
|
||
title="上一章"><code class="xref py py-mod docutils literal notranslate"><span class="pre">zipfile</span></code> --- 使用ZIP存档</a></p>
|
||
<h4>下一个主题</h4>
|
||
<p class="topless"><a href="fileformats.html"
|
||
title="下一章">文件格式</a></p>
|
||
<div role="note" aria-label="source link">
|
||
<h3>本页</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="../bugs.html">报告 Bug</a></li>
|
||
<li>
|
||
<a href="https://github.com/python/cpython/blob/3.8/Doc/library/tarfile.rst"
|
||
rel="nofollow">显示源代码
|
||
</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</nav>
|
||
</div>
|
||
</div>
|
||
|
||
<div id="outdated-warning" style="padding: .5em; text-align: center; background-color: #FFBABA; color: #6A0E0E;">
|
||
这个文档所针对的是一个已不再受支持的 Python 旧版本。
|
||
你应当升级版本，并阅读
|
||
<a href="/3/library/tarfile.html"> Python 当前稳定版本的文档</a>.
|
||
</div>
|
||
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>导航</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="总目录"
|
||
accesskey="I">索引</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python 模块索引"
|
||
>模块</a> |</li>
|
||
<li class="right" >
|
||
<a href="fileformats.html" title="文件格式"
|
||
accesskey="N">下一页</a> |</li>
|
||
<li class="right" >
|
||
<a href="zipfile.html" title="zipfile --- 使用ZIP存档"
|
||
accesskey="P">上一页</a> |</li>
|
||
|
||
<li><img src="../_static/py.svg" alt="python logo" style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li class="switchers">
|
||
<div class="language_switcher_placeholder"></div>
|
||
<div class="version_switcher_placeholder"></div>
|
||
</li>
|
||
<li>
|
||
|
||
</li>
|
||
<li id="cpython-language-and-version">
|
||
<a href="../index.html">3.8.20 Documentation</a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >Python 标准库</a> »</li>
|
||
<li class="nav-item nav-item-2"><a href="archiving.html" accesskey="U">数据压缩和存档</a> »</li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="快速搜索" aria-label="快速搜索" type="text" name="q" />
|
||
<input type="submit" value="转向" />
|
||
<input type="hidden" name="check_keywords" value="yes" />
|
||
<input type="hidden" name="area" value="default" />
|
||
</form>
|
||
</div>
|
||
|
|
||
</li>
|
||
|
||
</ul>
|
||
</div>
|
||
|
||
<div class="document">
|
||
<div class="documentwrapper">
|
||
<div class="bodywrapper">
|
||
<div class="body" role="main">
|
||
|
||
<section id="module-tarfile">
|
||
<span id="tarfile-read-and-write-tar-archive-files"></span><h1><a class="reference internal" href="#module-tarfile" title="tarfile: Read and write tar-format archive files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">tarfile</span></code></a> --- 读写tar归档文件<a class="headerlink" href="#module-tarfile" title="永久链接至标题">¶</a></h1>
|
||
<p><strong>源代码:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.8/Lib/tarfile.py">Lib/tarfile.py</a></p>
|
||
<hr class="docutils" />
|
||
<p><a class="reference internal" href="#module-tarfile" title="tarfile: Read and write tar-format archive files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">tarfile</span></code></a> 模块可以用来读写 tar 归档，包括使用 gzip, bz2 和 lzma 压缩的归档。 请使用 <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 notranslate"><span class="pre">zipfile</span></code></a> 模块来读写 <code class="file docutils literal notranslate"><span class="pre">.zip</span></code> 文件，或者使用 <a class="reference internal" href="shutil.html#archiving-operations"><span class="std std-ref">shutil</span></a> 的高层级函数。</p>
|
||
<p>一些事实和数字:</p>
|
||
<ul class="simple">
|
||
<li><p>读写 <a class="reference internal" href="gzip.html#module-gzip" title="gzip: Interfaces for gzip compression and decompression using file objects."><code class="xref py py-mod docutils literal notranslate"><span class="pre">gzip</span></code></a>, <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 notranslate"><span class="pre">bz2</span></code></a> 和 <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 notranslate"><span class="pre">lzma</span></code></a> 解压的归档要求相应的模块可用。</p></li>
|
||
<li><p>支持读取 / 写入 POSIX.1-1988 (ustar) 格式。</p></li>
|
||
<li><p>对 GNU tar 格式的读/写支持，包括 <em>longname</em> 和 <em>longlink</em> 扩展，对所有种类 <em>sparse</em> 扩展的只读支持，包括 sparse 文件的恢复。</p></li>
|
||
<li><p>对 POSIX.1-2001 (pax) 格式的读/写支持。</p></li>
|
||
<li><p>处理目录、正常文件、硬链接、符号链接、fifo 管道、字符设备和块设备，并且能够获取和恢复文件信息例如时间戳、访问权限和所有者等。</p></li>
|
||
</ul>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.3 版更改: </span>添加了对 <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 notranslate"><span class="pre">lzma</span></code></a> 压缩的支持。</p>
|
||
</div>
|
||
<dl class="function">
|
||
<dt id="tarfile.open">
|
||
<code class="sig-prename descclassname">tarfile.</code><code class="sig-name descname">open</code><span class="sig-paren">(</span><em class="sig-param">name=None</em>, <em class="sig-param">mode='r'</em>, <em class="sig-param">fileobj=None</em>, <em class="sig-param">bufsize=10240</em>, <em class="sig-param">**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.open" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>针对路径名 <em>name</em> 返回 <a class="reference internal" href="#tarfile.TarFile" title="tarfile.TarFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarFile</span></code></a> 对象。 有关 <a class="reference internal" href="#tarfile.TarFile" title="tarfile.TarFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarFile</span></code></a> 对象以及所允许的关键字参数的详细信息请参阅 <a class="reference internal" href="#tarfile-objects"><span class="std std-ref">TarFile 对象</span></a>。</p>
|
||
<p><em>mode</em> 必须是 <code class="docutils literal notranslate"><span class="pre">'filemode[:compression]'</span></code> 形式的字符串，其默认值为 <code class="docutils literal notranslate"><span class="pre">'r'</span></code>。 以下是模式组合的完整列表:</p>
|
||
<table class="docutils align-default">
|
||
<colgroup>
|
||
<col style="width: 29%" />
|
||
<col style="width: 71%" />
|
||
</colgroup>
|
||
<thead>
|
||
<tr class="row-odd"><th class="head"><p>mode</p></th>
|
||
<th class="head"><p>action</p></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'r'</span> <span class="pre">or</span> <span class="pre">'r:*'</span></code></p></td>
|
||
<td><p>打开和读取使用透明压缩（推荐）。</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'r:'</span></code></p></td>
|
||
<td><p>打开和读取不使用压缩。</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'r:gz'</span></code></p></td>
|
||
<td><p>打开和读取使用gzip 压缩。</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'r:bz2'</span></code></p></td>
|
||
<td><p>打开和读取使用bzip2 压缩。</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'r:xz'</span></code></p></td>
|
||
<td><p>打开和读取使用lzma 压缩。</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'x'</span></code> 或 <code class="docutils literal notranslate"><span class="pre">'x:'</span></code></p></td>
|
||
<td><p>创建tarfile不进行压缩。如果文件已经存在，则抛出 <a class="reference internal" href="exceptions.html#FileExistsError" title="FileExistsError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">FileExistsError</span></code></a> 异常。</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'x:gz'</span></code></p></td>
|
||
<td><p>使用gzip压缩创建tarfile。如果文件已经存在，则抛出 <a class="reference internal" href="exceptions.html#FileExistsError" title="FileExistsError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">FileExistsError</span></code></a> 异常。</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'x:bz2'</span></code></p></td>
|
||
<td><p>使用bzip2 压缩创建tarfile。如果文件已经存在，则抛出 <a class="reference internal" href="exceptions.html#FileExistsError" title="FileExistsError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">FileExistsError</span></code></a> 异常。</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'x:xz'</span></code></p></td>
|
||
<td><p>使用lzma 压缩创建tarfile。如果文件已经存在，则抛出 <a class="reference internal" href="exceptions.html#FileExistsError" title="FileExistsError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">FileExistsError</span></code></a> 异常。</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'a'</span> <span class="pre">or</span> <span class="pre">'a:'</span></code></p></td>
|
||
<td><p>打开以便在没有压缩的情况下追加。如果文件不存在，则创建该文件。</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'w'</span> <span class="pre">or</span> <span class="pre">'w:'</span></code></p></td>
|
||
<td><p>打开用于未压缩的写入。</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'w:gz'</span></code></p></td>
|
||
<td><p>打开用于 gzip 压缩的写入。</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'w:bz2'</span></code></p></td>
|
||
<td><p>打开用于 bzip2 压缩的写入。</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'w:xz'</span></code></p></td>
|
||
<td><p>打开用于 lzma 压缩的写入。</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p>请注意 <code class="docutils literal notranslate"><span class="pre">'a:gz'</span></code>, <code class="docutils literal notranslate"><span class="pre">'a:bz2'</span></code> 或 <code class="docutils literal notranslate"><span class="pre">'a:xz'</span></code> 是不可能的组合。 如果 <em>mode</em> 不适用于打开特定（压缩的）文件用于读取，则会引发 <a class="reference internal" href="#tarfile.ReadError" title="tarfile.ReadError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ReadError</span></code></a>。 请使用 <em>mode</em> <code class="docutils literal notranslate"><span class="pre">'r'</span></code> 来避免这种情况。 如果某种压缩方法不受支持，则会引发 <a class="reference internal" href="#tarfile.CompressionError" title="tarfile.CompressionError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">CompressionError</span></code></a>。</p>
|
||
<p>如果指定了 <em>fileobj</em>，它会被用作对应于 <em>name</em> 的以二进制模式打开的 <a class="reference internal" href="../glossary.html#term-file-object"><span class="xref std std-term">file object</span></a> 的替代。 它会被设定为处在位置 0。</p>
|
||
<p>对于 <code class="docutils literal notranslate"><span class="pre">'w:gz'</span></code>, <code class="docutils literal notranslate"><span class="pre">'r:gz'</span></code>, <code class="docutils literal notranslate"><span class="pre">'w:bz2'</span></code>, <code class="docutils literal notranslate"><span class="pre">'r:bz2'</span></code>, <code class="docutils literal notranslate"><span class="pre">'x:gz'</span></code>, <code class="docutils literal notranslate"><span class="pre">'x:bz2'</span></code> 等模式，<a class="reference internal" href="#tarfile.open" title="tarfile.open"><code class="xref py py-func docutils literal notranslate"><span class="pre">tarfile.open()</span></code></a> 接受关键字参数 <em>compresslevel</em> (默认值为 <code class="docutils literal notranslate"><span class="pre">9</span></code>) 来指定文件的压缩等级。</p>
|
||
<p>针对特殊的目的，还存在第二种 <em>mode</em> 格式: <code class="docutils literal notranslate"><span class="pre">'filemode|[compression]'</span></code>。 <a class="reference internal" href="#tarfile.open" title="tarfile.open"><code class="xref py py-func docutils literal notranslate"><span class="pre">tarfile.open()</span></code></a> 将返回一个将其数据作为数据块流来处理的 <a class="reference internal" href="#tarfile.TarFile" title="tarfile.TarFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarFile</span></code></a> 对象。 对此文件将不能执行随机查找。 如果给定了 <em>fileobj</em>，它可以是任何具有 <code class="xref py py-meth docutils literal notranslate"><span class="pre">read()</span></code> 或 <code class="xref py py-meth docutils literal notranslate"><span class="pre">write()</span></code> 方法 (由 <em>mode</em> 确定) 的对象。 <em>bufsize</em> 指定块大小，默认值为 <code class="docutils literal notranslate"><span class="pre">20</span> <span class="pre">*</span> <span class="pre">512</span></code> 字节。 可与此格式组合使用的有 <code class="docutils literal notranslate"><span class="pre">sys.stdin</span></code>, 套接字 <a class="reference internal" href="../glossary.html#term-file-object"><span class="xref std std-term">file object</span></a> 或磁带设备等。 但是，对于这样的 <a class="reference internal" href="#tarfile.TarFile" title="tarfile.TarFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarFile</span></code></a> 对象存在不允许随机访问的限制，参见 <a class="reference internal" href="#tar-examples"><span class="std std-ref">例子</span></a>。 目前可用的模式如下:</p>
|
||
<table class="docutils align-default">
|
||
<colgroup>
|
||
<col style="width: 23%" />
|
||
<col style="width: 77%" />
|
||
</colgroup>
|
||
<thead>
|
||
<tr class="row-odd"><th class="head"><p>模式</p></th>
|
||
<th class="head"><p>动作</p></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'r|*'</span></code></p></td>
|
||
<td><p>打开 tar 块的 <em>流</em> 以进行透明压缩读取。</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'r|'</span></code></p></td>
|
||
<td><p>打开一个未压缩的 tar 块的 <em>stream</em> 用于读取。</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'r|gz'</span></code></p></td>
|
||
<td><p>打开一个 gzip 压缩的 <em>stream</em> 用于读取。</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'r|bz2'</span></code></p></td>
|
||
<td><p>打开一个 bzip2 压缩的 <em>stream</em> 用于读取。</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'r|xz'</span></code></p></td>
|
||
<td><p>打开一个 lzma 压缩 <em>stream</em> 用于读取。</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'w|'</span></code></p></td>
|
||
<td><p>打开一个未压缩的 <em>stream</em> 用于写入。</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'w|gz'</span></code></p></td>
|
||
<td><p>打开一个 gzip 压缩的 <em>stream</em> 用于写入。</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'w|bz2'</span></code></p></td>
|
||
<td><p>打开一个 bzip2 压缩的 <em>stream</em> 用于写入。</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'w|xz'</span></code></p></td>
|
||
<td><p>打开一个 lzma 压缩的 <em>stream</em> 用于写入。</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.5 版更改: </span>添加了 <code class="docutils literal notranslate"><span class="pre">'x'</span></code> (单独创建) 模式。</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.6 版更改: </span><em>name</em> 形参接受一个 <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>。</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt>
|
||
<em class="property">class </em><code class="sig-prename descclassname">tarfile.</code><code class="sig-name descname">TarFile</code></dt>
|
||
<dd><p>用于读取和写入 tar 归档的类。 请不要直接使用这个类：而要使用 <a class="reference internal" href="#tarfile.open" title="tarfile.open"><code class="xref py py-func docutils literal notranslate"><span class="pre">tarfile.open()</span></code></a>。 参见 <a class="reference internal" href="#tarfile-objects"><span class="std std-ref">TarFile 对象</span></a>。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="tarfile.is_tarfile">
|
||
<code class="sig-prename descclassname">tarfile.</code><code class="sig-name descname">is_tarfile</code><span class="sig-paren">(</span><em class="sig-param">name</em><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.is_tarfile" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>如果 <em>name</em> 是一个 <a class="reference internal" href="#module-tarfile" title="tarfile: Read and write tar-format archive files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">tarfile</span></code></a> 模块能读取的 tar 归档文件则返回 <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a>。</p>
|
||
</dd></dl>
|
||
|
||
<p><a class="reference internal" href="#module-tarfile" title="tarfile: Read and write tar-format archive files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">tarfile</span></code></a> 模块定义了以下异常:</p>
|
||
<dl class="exception">
|
||
<dt id="tarfile.TarError">
|
||
<em class="property">exception </em><code class="sig-prename descclassname">tarfile.</code><code class="sig-name descname">TarError</code><a class="headerlink" href="#tarfile.TarError" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>所有 <a class="reference internal" href="#module-tarfile" title="tarfile: Read and write tar-format archive files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">tarfile</span></code></a> 异常的基类。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="exception">
|
||
<dt id="tarfile.ReadError">
|
||
<em class="property">exception </em><code class="sig-prename descclassname">tarfile.</code><code class="sig-name descname">ReadError</code><a class="headerlink" href="#tarfile.ReadError" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>当一个不能被 <a class="reference internal" href="#module-tarfile" title="tarfile: Read and write tar-format archive files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">tarfile</span></code></a> 模块处理或者因某种原因而无效的 tar 归档被打开时将被引发。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="exception">
|
||
<dt id="tarfile.CompressionError">
|
||
<em class="property">exception </em><code class="sig-prename descclassname">tarfile.</code><code class="sig-name descname">CompressionError</code><a class="headerlink" href="#tarfile.CompressionError" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>当一个压缩方法不受支持或者当数据无法被正确解码时将被引发。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="exception">
|
||
<dt id="tarfile.StreamError">
|
||
<em class="property">exception </em><code class="sig-prename descclassname">tarfile.</code><code class="sig-name descname">StreamError</code><a class="headerlink" href="#tarfile.StreamError" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>当达到流式 <a class="reference internal" href="#tarfile.TarFile" title="tarfile.TarFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarFile</span></code></a> 对象的典型限制时将被引发。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="exception">
|
||
<dt id="tarfile.ExtractError">
|
||
<em class="property">exception </em><code class="sig-prename descclassname">tarfile.</code><code class="sig-name descname">ExtractError</code><a class="headerlink" href="#tarfile.ExtractError" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>当使用 <a class="reference internal" href="#tarfile.TarFile.extract" title="tarfile.TarFile.extract"><code class="xref py py-meth docutils literal notranslate"><span class="pre">TarFile.extract()</span></code></a> 时针对 <em>non-fatal</em> 所引发的异常，但是仅限 <a class="reference internal" href="#tarfile.TarFile.errorlevel" title="tarfile.TarFile.errorlevel"><code class="xref py py-attr docutils literal notranslate"><span class="pre">TarFile.errorlevel</span></code></a><code class="docutils literal notranslate"><span class="pre">==</span> <span class="pre">2</span></code>。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="exception">
|
||
<dt id="tarfile.HeaderError">
|
||
<em class="property">exception </em><code class="sig-prename descclassname">tarfile.</code><code class="sig-name descname">HeaderError</code><a class="headerlink" href="#tarfile.HeaderError" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>如果获取的缓冲区无效则会由 <a class="reference internal" href="#tarfile.TarInfo.frombuf" title="tarfile.TarInfo.frombuf"><code class="xref py py-meth docutils literal notranslate"><span class="pre">TarInfo.frombuf()</span></code></a> 引发的异常。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="exception">
|
||
<dt id="tarfile.FilterError">
|
||
<em class="property">exception </em><code class="sig-prename descclassname">tarfile.</code><code class="sig-name descname">FilterError</code><a class="headerlink" href="#tarfile.FilterError" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>被过滤器 <a class="reference internal" href="#tarfile-extraction-refuse"><span class="std std-ref">拒绝</span></a> 的成员的基类。</p>
|
||
<dl class="attribute">
|
||
<dt id="tarfile.FilterError.tarinfo">
|
||
<code class="sig-name descname">tarinfo</code><a class="headerlink" href="#tarfile.FilterError.tarinfo" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>关于过滤器拒绝提取的成员的信息，为 <a class="reference internal" href="#tarinfo-objects"><span class="std std-ref">TarInfo</span></a> 类型。</p>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
<dl class="exception">
|
||
<dt id="tarfile.AbsolutePathError">
|
||
<em class="property">exception </em><code class="sig-prename descclassname">tarfile.</code><code class="sig-name descname">AbsolutePathError</code><a class="headerlink" href="#tarfile.AbsolutePathError" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>在拒绝提取具有绝对路径的成员时引发。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="exception">
|
||
<dt id="tarfile.OutsideDestinationError">
|
||
<em class="property">exception </em><code class="sig-prename descclassname">tarfile.</code><code class="sig-name descname">OutsideDestinationError</code><a class="headerlink" href="#tarfile.OutsideDestinationError" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>在拒绝提取目标目录以外的成员时引发。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="exception">
|
||
<dt id="tarfile.SpecialFileError">
|
||
<em class="property">exception </em><code class="sig-prename descclassname">tarfile.</code><code class="sig-name descname">SpecialFileError</code><a class="headerlink" href="#tarfile.SpecialFileError" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>在拒绝提取特殊文件（例如设备或管道）时引发。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="exception">
|
||
<dt id="tarfile.AbsoluteLinkError">
|
||
<em class="property">exception </em><code class="sig-prename descclassname">tarfile.</code><code class="sig-name descname">AbsoluteLinkError</code><a class="headerlink" href="#tarfile.AbsoluteLinkError" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>在拒绝提取具有绝对路径的符号链接时引发。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="exception">
|
||
<dt id="tarfile.LinkOutsideDestinationError">
|
||
<em class="property">exception </em><code class="sig-prename descclassname">tarfile.</code><code class="sig-name descname">LinkOutsideDestinationError</code><a class="headerlink" href="#tarfile.LinkOutsideDestinationError" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>在拒绝提取指向目标目录以外的符号链接时引发。</p>
|
||
</dd></dl>
|
||
|
||
<p>以下常量在模块层级上可用:</p>
|
||
<dl class="data">
|
||
<dt id="tarfile.ENCODING">
|
||
<code class="sig-prename descclassname">tarfile.</code><code class="sig-name descname">ENCODING</code><a class="headerlink" href="#tarfile.ENCODING" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>默认的字符编码格式：在 Windows 上为 <code class="docutils literal notranslate"><span class="pre">'utf-8'</span></code>，其他系统上则为 <a class="reference internal" href="sys.html#sys.getfilesystemencoding" title="sys.getfilesystemencoding"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.getfilesystemencoding()</span></code></a> 所返回的值。</p>
|
||
</dd></dl>
|
||
|
||
<p>以下常量各自定义了一个 <a class="reference internal" href="#module-tarfile" title="tarfile: Read and write tar-format archive files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">tarfile</span></code></a> 模块能够创建的 tar 归档格式。 相关细节请参阅 <a class="reference internal" href="#tar-formats"><span class="std std-ref">受支持的 tar 格式</span></a> 小节。</p>
|
||
<dl class="data">
|
||
<dt id="tarfile.USTAR_FORMAT">
|
||
<code class="sig-prename descclassname">tarfile.</code><code class="sig-name descname">USTAR_FORMAT</code><a class="headerlink" href="#tarfile.USTAR_FORMAT" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>POSIX.1-1988 (ustar) 格式。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="tarfile.GNU_FORMAT">
|
||
<code class="sig-prename descclassname">tarfile.</code><code class="sig-name descname">GNU_FORMAT</code><a class="headerlink" href="#tarfile.GNU_FORMAT" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>GNU tar 格式。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="tarfile.PAX_FORMAT">
|
||
<code class="sig-prename descclassname">tarfile.</code><code class="sig-name descname">PAX_FORMAT</code><a class="headerlink" href="#tarfile.PAX_FORMAT" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>POSIX.1-2001 (pax) 格式。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="tarfile.DEFAULT_FORMAT">
|
||
<code class="sig-prename descclassname">tarfile.</code><code class="sig-name descname">DEFAULT_FORMAT</code><a class="headerlink" href="#tarfile.DEFAULT_FORMAT" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>用于创建归档的默认格式。 目前为 <a class="reference internal" href="#tarfile.PAX_FORMAT" title="tarfile.PAX_FORMAT"><code class="xref py py-const docutils literal notranslate"><span class="pre">PAX_FORMAT</span></code></a>。</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.8 版更改: </span>新归档的默认格式已更改为 <a class="reference internal" href="#tarfile.PAX_FORMAT" title="tarfile.PAX_FORMAT"><code class="xref py py-const docutils literal notranslate"><span class="pre">PAX_FORMAT</span></code></a> 而不再是 <a class="reference internal" href="#tarfile.GNU_FORMAT" title="tarfile.GNU_FORMAT"><code class="xref py py-const docutils literal notranslate"><span class="pre">GNU_FORMAT</span></code></a>。</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<div class="admonition seealso">
|
||
<p class="admonition-title">参见</p>
|
||
<dl class="simple">
|
||
<dt>模块 <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 notranslate"><span class="pre">zipfile</span></code></a></dt><dd><p><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 notranslate"><span class="pre">zipfile</span></code></a> 标准模块的文档。</p>
|
||
</dd>
|
||
<dt><a class="reference internal" href="shutil.html#archiving-operations"><span class="std std-ref">归档操作</span></a></dt><dd><p>标准 <a class="reference internal" href="shutil.html#module-shutil" title="shutil: High-level file operations, including copying."><code class="xref py py-mod docutils literal notranslate"><span class="pre">shutil</span></code></a> 模块所提供的高层级归档工具的文档。</p>
|
||
</dd>
|
||
<dt><a class="reference external" href="https://www.gnu.org/software/tar/manual/html_node/Standard.html">GNU tar manual, Basic Tar Format</a></dt><dd><p>针对 tar 归档文件的文档，包含 GNU tar 扩展。</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
<section id="tarfile-objects">
|
||
<span id="id1"></span><h2>TarFile 对象<a class="headerlink" href="#tarfile-objects" title="永久链接至标题">¶</a></h2>
|
||
<p><a class="reference internal" href="#tarfile.TarFile" title="tarfile.TarFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarFile</span></code></a> 对象提供了一个 tar 归档的接口。 一个 tar 归档就是数据块的序列。 一个归档成员（被保存文件）是由一个标头块加多个数据块组成的。 一个文件可以在一个 tar 归档中多次被保存。 每个归档成员都由一个 <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> 对象来代表，详情参见 <a class="reference internal" href="#tarinfo-objects"><span class="std std-ref">TarInfo 对象</span></a>。</p>
|
||
<p><a class="reference internal" href="#tarfile.TarFile" title="tarfile.TarFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarFile</span></code></a> 对象可在 <a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> 语句中作为上下文管理器使用。 当语句块结束时它将自动被关闭。 请注意在发生异常事件时被打开用于写入的归档将不会被终结；只有内部使用的文件对象将被关闭。 相关用例请参见 <a class="reference internal" href="#tar-examples"><span class="std std-ref">例子</span></a>。</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">3.2 新版功能: </span>添加了对上下文管理器协议的支持。</p>
|
||
</div>
|
||
<dl class="class">
|
||
<dt id="tarfile.TarFile">
|
||
<em class="property">class </em><code class="sig-prename descclassname">tarfile.</code><code class="sig-name descname">TarFile</code><span class="sig-paren">(</span><em class="sig-param">name=None</em>, <em class="sig-param">mode='r'</em>, <em class="sig-param">fileobj=None</em>, <em class="sig-param">format=DEFAULT_FORMAT</em>, <em class="sig-param">tarinfo=TarInfo</em>, <em class="sig-param">dereference=False</em>, <em class="sig-param">ignore_zeros=False</em>, <em class="sig-param">encoding=ENCODING</em>, <em class="sig-param">errors='surrogateescape'</em>, <em class="sig-param">pax_headers=None</em>, <em class="sig-param">debug=0</em>, <em class="sig-param">errorlevel=1</em><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarFile" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>下列所有参数都是可选项并且也可作为实例属性来访问。</p>
|
||
<p><em>name</em> 是归档的路径名称。 <em>name</em> 可以是一个 <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>。 如果给定了 <em>fileobj</em> 则它可以被省略。 在此情况下，如果对象的 <code class="xref py py-attr docutils literal notranslate"><span class="pre">name</span></code> 属性存在则它会被使用。</p>
|
||
<p><em>mode</em> 可以为 <code class="docutils literal notranslate"><span class="pre">'r'</span></code> 表示从现有归档读取，<code class="docutils literal notranslate"><span class="pre">'a'</span></code> 表示将数据追加到现有文件，<code class="docutils literal notranslate"><span class="pre">'w'</span></code> 表示创建新文件覆盖现有文件，或者 <code class="docutils literal notranslate"><span class="pre">'x'</span></code> 表示仅在文件不存在时创建新文件。</p>
|
||
<p>如果给定了 <em>fileobj</em>，它会被用于读取或写入数据。 如果可以被确定，则 <em>mode</em> 会被 <em>fileobj</em> 的模式所覆盖。 <em>fileobj</em> 的使用将从位置 0 开始。</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">注解</p>
|
||
<p>当 <a class="reference internal" href="#tarfile.TarFile" title="tarfile.TarFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarFile</span></code></a> 被关闭时，<em>fileobj</em> 不会被关闭。</p>
|
||
</div>
|
||
<p><em>format</em> 控制用于写入的归档格式。 它必须为在模块层级定义的常量 <a class="reference internal" href="#tarfile.USTAR_FORMAT" title="tarfile.USTAR_FORMAT"><code class="xref py py-const docutils literal notranslate"><span class="pre">USTAR_FORMAT</span></code></a>, <a class="reference internal" href="#tarfile.GNU_FORMAT" title="tarfile.GNU_FORMAT"><code class="xref py py-const docutils literal notranslate"><span class="pre">GNU_FORMAT</span></code></a> 或 <a class="reference internal" href="#tarfile.PAX_FORMAT" title="tarfile.PAX_FORMAT"><code class="xref py py-const docutils literal notranslate"><span class="pre">PAX_FORMAT</span></code></a> 中的一个。 当读取时，格式将被自动检测，即使单个归档中存在不同的格式。</p>
|
||
<p><em>tarinfo</em> 参数可以被用来将默认的 <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> 类替换为另一个。</p>
|
||
<p>如果 <em>dereference</em> 为 <a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a>，则会将符号链接和硬链接添加到归档中。 如果为 <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a>，则会将目标文件的内容添加到归档中。 在不支持符号链接的系统上参数将不起作用。</p>
|
||
<p>如果 <em>ignore_zeros</em> 为 <a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a>，则会将空的数据块当作归档的末尾来处理。 如果为 <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a>，则会跳过空的（和无效的）数据块并尝试获取尽可能多的成员。 此参数仅适用于读取拼接的或损坏的归档。</p>
|
||
<p><em>debug</em> 可设为从 <code class="docutils literal notranslate"><span class="pre">0</span></code> (无调试消息) 到 <code class="docutils literal notranslate"><span class="pre">3</span></code> (全部调试消息)。 消息会被写入到 <code class="docutils literal notranslate"><span class="pre">sys.stderr</span></code>。</p>
|
||
<p><em>errorlevel</em> 控制如何处理提取错误，参见 <code class="xref py py-attr docutils literal notranslate"><span class="pre">相应的属性</span></code>。</p>
|
||
<p><em>encoding</em> 和 <em>errors</em> 参数定义了读取或写入归档所使用的字符编码格式以及要如何处理转换错误。 默认设置将适用于大多数用户。 要深入了解详情可参阅 <a class="reference internal" href="#tar-unicode"><span class="std std-ref">Unicode 问题</span></a> 小节。</p>
|
||
<p>可选的 <em>pax_headers</em> 参数是字符串的字典，如果 <em>format</em> 为 <a class="reference internal" href="#tarfile.PAX_FORMAT" title="tarfile.PAX_FORMAT"><code class="xref py py-const docutils literal notranslate"><span class="pre">PAX_FORMAT</span></code></a> 它将被作为 pax 全局标头被添加。</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.2 版更改: </span>使用 <code class="docutils literal notranslate"><span class="pre">'surrogateescape'</span></code> 作为 <em>errors</em> 参数的默认值。</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.5 版更改: </span>添加了 <code class="docutils literal notranslate"><span class="pre">'x'</span></code> (单独创建) 模式。</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.6 版更改: </span><em>name</em> 形参接受一个 <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>。</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="tarfile.TarFile.open">
|
||
<em class="property">classmethod </em><code class="sig-prename descclassname">TarFile.</code><code class="sig-name descname">open</code><span class="sig-paren">(</span><em class="sig-param">...</em><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarFile.open" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>作为替代的构造器。 <a class="reference internal" href="#tarfile.open" title="tarfile.open"><code class="xref py py-func docutils literal notranslate"><span class="pre">tarfile.open()</span></code></a> 函数实际上是这个类方法的快捷方式。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="tarfile.TarFile.getmember">
|
||
<code class="sig-prename descclassname">TarFile.</code><code class="sig-name descname">getmember</code><span class="sig-paren">(</span><em class="sig-param">name</em><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarFile.getmember" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>返回成员 <em>name</em> 的 <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> 对象。 如果 <em>name</em> 在归档中找不到，则会引发 <a class="reference internal" href="exceptions.html#KeyError" title="KeyError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">KeyError</span></code></a>。</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">注解</p>
|
||
<p>如果一个成员在归档中出现超过一次，它的最后一次出现会被视为是最新的版本。</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="tarfile.TarFile.getmembers">
|
||
<code class="sig-prename descclassname">TarFile.</code><code class="sig-name descname">getmembers</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarFile.getmembers" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>以 <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> 对象列表的形式返回归档的成员。 列表的顺序与归档中成员的顺序一致。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="tarfile.TarFile.getnames">
|
||
<code class="sig-prename descclassname">TarFile.</code><code class="sig-name descname">getnames</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarFile.getnames" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>以名称列表的形式返回成员。 它的顺序与 <a class="reference internal" href="#tarfile.TarFile.getmembers" title="tarfile.TarFile.getmembers"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getmembers()</span></code></a> 所返回列表的顺序一致。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="tarfile.TarFile.list">
|
||
<code class="sig-prename descclassname">TarFile.</code><code class="sig-name descname">list</code><span class="sig-paren">(</span><em class="sig-param">verbose=True</em>, <em class="sig-param">*</em>, <em class="sig-param">members=None</em><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarFile.list" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>将内容清单打印到 <code class="docutils literal notranslate"><span class="pre">sys.stdout</span></code>。 如果 <em>verbose</em> 为 <a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a>，则将只打印成员名称。 如果为 <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a>，则输出将类似于 <strong class="program">ls -l</strong> 的输出效果。 如果给定了可选的 <em>members</em>，它必须为 <a class="reference internal" href="#tarfile.TarFile.getmembers" title="tarfile.TarFile.getmembers"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getmembers()</span></code></a> 所返回的列表的一个子集。</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.5 版更改: </span>添加了 <em>members</em> 形参。</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="tarfile.TarFile.next">
|
||
<code class="sig-prename descclassname">TarFile.</code><code class="sig-name descname">next</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarFile.next" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>当 <a class="reference internal" href="#tarfile.TarFile" title="tarfile.TarFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarFile</span></code></a> 被打开用于读取时，以 <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> 对象的形式返回归档的下一个成员。 如果不再有可用对象则返回 <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a>。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="tarfile.TarFile.extractall">
|
||
<code class="sig-prename descclassname">TarFile.</code><code class="sig-name descname">extractall</code><span class="sig-paren">(</span><em class="sig-param">path="."</em>, <em class="sig-param">members=None</em>, <em class="sig-param">*</em>, <em class="sig-param">numeric_owner=False</em>, <em class="sig-param">filter=None</em><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarFile.extractall" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>将归档中的所有成员提取到当前工作目录或 <em>path</em> 目录。 如果给定了可选的 <em>members</em>，则它必须为 <a class="reference internal" href="#tarfile.TarFile.getmembers" title="tarfile.TarFile.getmembers"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getmembers()</span></code></a> 所返回的列表的一个子集。 字典信息例如所有者、修改时间和权限会在所有成员提取完毕后被设置。 这样做是为了避免两个问题：目录的修改时间会在每当在其中创建文件时被重置。 并且如果目录的权限不允许写入，提取文件到目录的操作将失败。</p>
|
||
<p>如果 <em>numeric_owner</em> 为 <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a>，则将使用来自 tarfile 的 uid 和 gid 数值来设置被提取文件的所有者/用户组。 在其他情况下，则会使用来自 tarfile 的名称值。</p>
|
||
<p>The <em>filter</em> argument, which was added in Python 3.8.17, specifies how
|
||
<code class="docutils literal notranslate"><span class="pre">members</span></code> are modified or rejected before extraction.
|
||
See <a class="reference internal" href="#tarfile-extraction-filter"><span class="std std-ref">解压缩过滤器</span></a> for details.
|
||
It is recommended to set this explicitly depending on which <em>tar</em> features
|
||
you need to support.</p>
|
||
<div class="admonition warning">
|
||
<p class="admonition-title">警告</p>
|
||
<p>绝不要未经预先检验就从不可靠的源中提取归档文件。 这样有可能在 <em>path</em> 之外创建文件，例如某些成员具有以 <code class="docutils literal notranslate"><span class="pre">"/"</span></code> 开始的绝对路径文件名或带有两个点号 <code class="docutils literal notranslate"><span class="pre">".."</span></code> 的文件名。</p>
|
||
<p>设置 <code class="docutils literal notranslate"><span class="pre">filter='data'</span></code> 来防止最危险的安全问题，并请参阅 <a class="reference internal" href="#tarfile-extraction-filter"><span class="std std-ref">解压缩过滤器</span></a> 一节了解详情。section for details.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.5 版更改: </span>添加了 <em>numeric_owner</em> 形参。</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.6 版更改: </span><em>path</em> 形参接受一个 <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>。</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.8.17 版更改: </span>添加了 <em>filter</em> 形参。</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="tarfile.TarFile.extract">
|
||
<code class="sig-prename descclassname">TarFile.</code><code class="sig-name descname">extract</code><span class="sig-paren">(</span><em class="sig-param">member</em>, <em class="sig-param">path=""</em>, <em class="sig-param">set_attrs=True</em>, <em class="sig-param">*</em>, <em class="sig-param">numeric_owner=False</em>, <em class="sig-param">filter=None</em><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarFile.extract" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>从归档中提取出一个成员放入当前工作目录，将使用其完整名称。 成员的文件信息会尽可能精确地被提取。 <em>member</em> 可以是一个文件名或 <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> 对象。 你可以使用 <em>path</em> 指定一个不同的目录。 <em>path</em> 可以是一个 <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>。 将会设置文件属性 (owner, mtime, mode) 除非 <em>set_attrs</em> 为假值。</p>
|
||
<p><em>numeric_owner</em> 和 <em>filter</em> 参数与 <a class="reference internal" href="#tarfile.TarFile.extractall" title="tarfile.TarFile.extractall"><code class="xref py py-meth docutils literal notranslate"><span class="pre">extractall()</span></code></a> 中的相同。</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">注解</p>
|
||
<p><a class="reference internal" href="#tarfile.TarFile.extract" title="tarfile.TarFile.extract"><code class="xref py py-meth docutils literal notranslate"><span class="pre">extract()</span></code></a> 方法不会处理某些提取问题。 在大多数情况下你应当考虑使用 <a class="reference internal" href="#tarfile.TarFile.extractall" title="tarfile.TarFile.extractall"><code class="xref py py-meth docutils literal notranslate"><span class="pre">extractall()</span></code></a> 方法。</p>
|
||
</div>
|
||
<div class="admonition warning">
|
||
<p class="admonition-title">警告</p>
|
||
<p>查看 <a class="reference internal" href="#tarfile.TarFile.extractall" title="tarfile.TarFile.extractall"><code class="xref py py-meth docutils literal notranslate"><span class="pre">extractall()</span></code></a> 的警告信息。</p>
|
||
<p>设置 <code class="docutils literal notranslate"><span class="pre">filter='data'</span></code> 来防止最危险的安全问题，并请参阅 <a class="reference internal" href="#tarfile-extraction-filter"><span class="std std-ref">解压缩过滤器</span></a> 一节了解详情。section for details.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.2 版更改: </span>添加了 <em>set_attrs</em> 形参。</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.5 版更改: </span>添加了 <em>numeric_owner</em> 形参。</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.6 版更改: </span><em>path</em> 形参接受一个 <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>。</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.8.17 版更改: </span>添加了 <em>filter</em> 形参。</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="tarfile.TarFile.extractfile">
|
||
<code class="sig-prename descclassname">TarFile.</code><code class="sig-name descname">extractfile</code><span class="sig-paren">(</span><em class="sig-param">member</em><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarFile.extractfile" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>将归档中的一个成员提取为文件对象。 <em>member</em> 可以是一个文件名或 <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> 对象。 如果 <em>member</em> 是一个常规文件或链接，则会返回一个 <a class="reference internal" href="io.html#io.BufferedReader" title="io.BufferedReader"><code class="xref py py-class docutils literal notranslate"><span class="pre">io.BufferedReader</span></code></a> 对象。 在其他情况下将返回 <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a>。</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.3 版更改: </span>返回一个 <a class="reference internal" href="io.html#io.BufferedReader" title="io.BufferedReader"><code class="xref py py-class docutils literal notranslate"><span class="pre">io.BufferedReader</span></code></a> 对象。</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="tarfile.TarFile.errorlevel">
|
||
<code class="sig-prename descclassname">TarFile.</code><code class="sig-name descname">errorlevel</code><em class="property">: int</em><a class="headerlink" href="#tarfile.TarFile.errorlevel" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>如果 <em>errorlevel</em> 为 <code class="docutils literal notranslate"><span class="pre">0</span></code>，则在使用 <a class="reference internal" href="#tarfile.TarFile.extract" title="tarfile.TarFile.extract"><code class="xref py py-meth docutils literal notranslate"><span class="pre">TarFile.extract()</span></code></a> 和 <a class="reference internal" href="#tarfile.TarFile.extractall" title="tarfile.TarFile.extractall"><code class="xref py py-meth docutils literal notranslate"><span class="pre">TarFile.extractall()</span></code></a> 时错误会被忽略。 不过，当 <em>debug</em> 大于 0 时它们将会作为错误消息在调试输出中出现。 如果 <em>errorlevel*为 ``1`` (默认值)，则所有 *fatal</em> 错误都会作为 <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a> 或 <a class="reference internal" href="#tarfile.FilterError" title="tarfile.FilterError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">FilterError</span></code></a> 异常被引发。 如果为 <code class="docutils literal notranslate"><span class="pre">2</span></code>，则所有 <em>non-fatal</em> 错误也会作为 <a class="reference internal" href="#tarfile.TarError" title="tarfile.TarError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TarError</span></code></a> 异常被引发。</p>
|
||
<p>某些异常，如参数类型错误或数据损坏导致的异常，总是会被触发。</p>
|
||
<p>自定义 <a class="reference internal" href="#tarfile-extraction-filter"><span class="std std-ref">提取过滤器</span></a> 应针对 <em>fatal</em> 错误引发 <a class="reference internal" href="#tarfile.FilterError" title="tarfile.FilterError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">FilterError</span></code></a>，针对 <em>non-fatal</em> 错误引发 <a class="reference internal" href="#tarfile.ExtractError" title="tarfile.ExtractError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ExtractError</span></code></a>。</p>
|
||
<p>请注意，当出现异常时，存档可能会被部分提取。用需要户负责进行清理。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="tarfile.TarFile.extraction_filter">
|
||
<code class="sig-prename descclassname">TarFile.</code><code class="sig-name descname">extraction_filter</code><a class="headerlink" href="#tarfile.TarFile.extraction_filter" title="永久链接至目标">¶</a></dt>
|
||
<dd><div class="versionadded">
|
||
<p><span class="versionmodified added">3.8.17 新版功能.</span></p>
|
||
</div>
|
||
<p>被用作 <a class="reference internal" href="#tarfile.TarFile.extract" title="tarfile.TarFile.extract"><code class="xref py py-meth docutils literal notranslate"><span class="pre">extract()</span></code></a> 和 <a class="reference internal" href="#tarfile.TarFile.extractall" title="tarfile.TarFile.extractall"><code class="xref py py-meth docutils literal notranslate"><span class="pre">extractall()</span></code></a> 的 <em>filter</em> 参数的默认值的 <a class="reference internal" href="#tarfile-extraction-filter"><span class="std std-ref">提取过滤器</span></a>。</p>
|
||
<p>该属性可以为 <code class="docutils literal notranslate"><span class="pre">None</span></code> 或是一个可调用对象。 与 <a class="reference internal" href="#tarfile.TarFile.extract" title="tarfile.TarFile.extract"><code class="xref py py-meth docutils literal notranslate"><span class="pre">extract()</span></code></a> 的 <em>filter</em> 参数不同，该属性不允许使用字符串名称。</p>
|
||
<p>If <code class="docutils literal notranslate"><span class="pre">extraction_filter</span></code> is <code class="docutils literal notranslate"><span class="pre">None</span></code> (the default),
|
||
calling an extraction method without a <em>filter</em> argument will
|
||
use the <a class="reference internal" href="#tarfile.fully_trusted_filter" title="tarfile.fully_trusted_filter"><code class="xref py py-func docutils literal notranslate"><span class="pre">fully_trusted</span></code></a> filter for
|
||
compatibility with previous Python versions.</p>
|
||
<p>在 Python 3.12+ 中，保留 <code class="docutils literal notranslate"><span class="pre">extraction_filter=None</span></code> 会发出一个 <code class="docutils literal notranslate"><span class="pre">DeprecationWarning</span></code> 。</p>
|
||
<p>在 Python 3.14+ 中，保持 <code class="docutils literal notranslate"><span class="pre">extraction_filter=None</span></code> 将导致提取方法默认使用 <a class="reference internal" href="#tarfile.data_filter" title="tarfile.data_filter"><code class="xref py py-func docutils literal notranslate"><span class="pre">data</span></code></a> 过滤器。</p>
|
||
<p>该属性可在实例上设置或在子类中重载。 也可以在 <code class="docutils literal notranslate"><span class="pre">TarFile</span></code> 类本身上设置它以设置一个全局默认值，不过，由于它会影响 <em>tarfile</em> 的所有使用，因此最好只在最高层级应用程序或 <a class="reference internal" href="site.html#module-site" title="site: Module responsible for site-specific configuration."><code class="xref py py-mod docutils literal notranslate"><span class="pre">站点配置</span></code></a> 中这样做。 要以这种方式设置全局默认值，需要用 <a class="reference internal" href="functions.html#staticmethod" title="staticmethod"><code class="xref py py-func docutils literal notranslate"><span class="pre">staticmethod()</span></code></a> 包装过滤器函数以防止 <code class="docutils literal notranslate"><span class="pre">self</span></code> 参数的注入。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="tarfile.TarFile.add">
|
||
<code class="sig-prename descclassname">TarFile.</code><code class="sig-name descname">add</code><span class="sig-paren">(</span><em class="sig-param">name</em>, <em class="sig-param">arcname=None</em>, <em class="sig-param">recursive=True</em>, <em class="sig-param">*</em>, <em class="sig-param">filter=None</em><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarFile.add" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>将文件 <em>name</em> 添加到归档。 <em>name</em> 可以为任意类型的文件（目录、fifo、符号链接等等）。 如果给出 <em>arcname</em> 则它将为归档中的文件指定一个替代名称。 默认情况下会递归地添加目录。 这可以通过将 <em>recursive</em> 设为 <a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a> 来避免。 递归操作会按排序顺序添加条目。 如果给定了 <em>filter</em>，它应当为一个接受 <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> 对象并返回已修改 <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> 对象的函数。 如果它返回 <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a> 则 <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> 对象将从归档中被排除。 具体示例参见 <a class="reference internal" href="#tar-examples"><span class="std std-ref">例子</span></a>。</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.2 版更改: </span>添加了 <em>filter</em> 形参。</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.7 版更改: </span>递归操作按排序顺序添加条目。</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="tarfile.TarFile.addfile">
|
||
<code class="sig-prename descclassname">TarFile.</code><code class="sig-name descname">addfile</code><span class="sig-paren">(</span><em class="sig-param">tarinfo</em>, <em class="sig-param">fileobj=None</em><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarFile.addfile" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>将 <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> 对象 <em>tarinfo</em> 添加到归档。 如果给定了 <em>fileobj</em>，它应当是一个 <a class="reference internal" href="../glossary.html#term-binary-file"><span class="xref std std-term">binary file</span></a>，并会从中读取 <code class="docutils literal notranslate"><span class="pre">tarinfo.size</span></code> 个字节添加到归档。 你可以直接创建 <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> 对象，或是使用 <a class="reference internal" href="#tarfile.TarFile.gettarinfo" title="tarfile.TarFile.gettarinfo"><code class="xref py py-meth docutils literal notranslate"><span class="pre">gettarinfo()</span></code></a> 来创建。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="tarfile.TarFile.gettarinfo">
|
||
<code class="sig-prename descclassname">TarFile.</code><code class="sig-name descname">gettarinfo</code><span class="sig-paren">(</span><em class="sig-param">name=None</em>, <em class="sig-param">arcname=None</em>, <em class="sig-param">fileobj=None</em><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarFile.gettarinfo" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>基于 <a class="reference internal" href="os.html#os.stat" title="os.stat"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.stat()</span></code></a> 的结果或者现有文件的相同数据创建一个 <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a>。 文件或者是命名为 <em>name</em>，或者是使用文件描述符指定为一个 <a class="reference internal" href="../glossary.html#term-file-object"><span class="xref std std-term">file object</span></a> <em>fileobj</em>。 <em>name</em> 可以是一个 <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>。 如果给定了 <em>arcname</em>，则它将为归档中的文件指定一个替代名称，在其他情况下，名称将从 <em>fileobj</em> 的 <a class="reference internal" href="io.html#io.FileIO.name" title="io.FileIO.name"><code class="xref py py-attr docutils literal notranslate"><span class="pre">name</span></code></a> 属性或 <em>name</em> 参数获取。 名称应当是一个文本字符串。</p>
|
||
<p>你可以在使用 <a class="reference internal" href="#tarfile.TarFile.addfile" title="tarfile.TarFile.addfile"><code class="xref py py-meth docutils literal notranslate"><span class="pre">addfile()</span></code></a> 添加 <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> 的某些属性之前修改它们。 如果文件对象不是从文件开头进行定位的普通文件对象，<a class="reference internal" href="#tarfile.TarInfo.size" title="tarfile.TarInfo.size"><code class="xref py py-attr docutils literal notranslate"><span class="pre">size</span></code></a> 之类的属性就可能需要修改。 例如 <a class="reference internal" href="gzip.html#gzip.GzipFile" title="gzip.GzipFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">GzipFile</span></code></a> 之类的文件就属于这种情况。 <a class="reference internal" href="#tarfile.TarInfo.name" title="tarfile.TarInfo.name"><code class="xref py py-attr docutils literal notranslate"><span class="pre">name</span></code></a> 也可以被修改，在这种情况下 <em>arcname</em> 可以是一个占位字符串。</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.6 版更改: </span><em>name</em> 形参接受一个 <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>。</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="tarfile.TarFile.close">
|
||
<code class="sig-prename descclassname">TarFile.</code><code class="sig-name descname">close</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarFile.close" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>关闭 <a class="reference internal" href="#tarfile.TarFile" title="tarfile.TarFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarFile</span></code></a>。 在写入模式下，会向归档添加两个表示结束的零数据块。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="tarfile.TarFile.pax_headers">
|
||
<code class="sig-prename descclassname">TarFile.</code><code class="sig-name descname">pax_headers</code><a class="headerlink" href="#tarfile.TarFile.pax_headers" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>一个包含 pax 全局标头的键值对的字典。</p>
|
||
</dd></dl>
|
||
|
||
</section>
|
||
<section id="tarinfo-objects">
|
||
<span id="id2"></span><h2>TarInfo 对象<a class="headerlink" href="#tarinfo-objects" title="永久链接至标题">¶</a></h2>
|
||
<p><a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> 对象代表 <a class="reference internal" href="#tarfile.TarFile" title="tarfile.TarFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarFile</span></code></a> 中的一个文件。 除了会存储所有必要的文件属性（例如文件类型、大小、时间、权限、所有者等），它还提供了一些确定文件类型的有用方法。 此对象 <em>并不</em> 包含文件数据本身。</p>
|
||
<p><a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> 对象可通过 <a class="reference internal" href="#tarfile.TarFile" title="tarfile.TarFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarFile</span></code></a> 的方法 <a class="reference internal" href="#tarfile.TarFile.getmember" title="tarfile.TarFile.getmember"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getmember()</span></code></a>, <a class="reference internal" href="#tarfile.TarFile.getmembers" title="tarfile.TarFile.getmembers"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getmembers()</span></code></a> 和 <a class="reference internal" href="#tarfile.TarFile.gettarinfo" title="tarfile.TarFile.gettarinfo"><code class="xref py py-meth docutils literal notranslate"><span class="pre">gettarinfo()</span></code></a> 返回。</p>
|
||
<p>修改 <code class="xref py py-meth docutils literal notranslate"><span class="pre">getmember()</span></code> 或 <code class="xref py py-meth docutils literal notranslate"><span class="pre">getmembers()</span></code> 返回的对象将会影响在归档上的所有后续操作。 对于不希望如此的情况，你可以使用 <a class="reference internal" href="copy.html#module-copy" title="copy: Shallow and deep copy operations."><code class="xref py py-mod docutils literal notranslate"><span class="pre">copy.copy()</span></code></a> 或调用 <code class="xref py py-meth docutils literal notranslate"><span class="pre">replace()</span></code> 方法通过一个步骤创建经修改的副本。</p>
|
||
<p>部分属性可以设为 <code class="docutils literal notranslate"><span class="pre">None</span></code> 以表示一些元数据未被使用或未知。 不同的 <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> 方法会以不同的方式处理 <code class="docutils literal notranslate"><span class="pre">None</span></code>:</p>
|
||
<ul class="simple">
|
||
<li><p><a class="reference internal" href="#tarfile.TarFile.extract" title="tarfile.TarFile.extract"><code class="xref py py-meth docutils literal notranslate"><span class="pre">extract()</span></code></a> 或 <a class="reference internal" href="#tarfile.TarFile.extractall" title="tarfile.TarFile.extractall"><code class="xref py py-meth docutils literal notranslate"><span class="pre">extractall()</span></code></a> 方法会忽略相应的元数据，让其保持默认设置。</p></li>
|
||
<li><p><a class="reference internal" href="#tarfile.TarFile.addfile" title="tarfile.TarFile.addfile"><code class="xref py py-meth docutils literal notranslate"><span class="pre">addfile()</span></code></a> 将会失败。</p></li>
|
||
<li><p><a class="reference internal" href="#tarfile.TarFile.list" title="tarfile.TarFile.list"><code class="xref py py-meth docutils literal notranslate"><span class="pre">list()</span></code></a> 将打印一个占位字符串。</p></li>
|
||
</ul>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.8.17 版更改: </span>Added <code class="xref py py-meth docutils literal notranslate"><span class="pre">replace()</span></code> and handling of <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
|
||
</div>
|
||
<dl class="class">
|
||
<dt id="tarfile.TarInfo">
|
||
<em class="property">class </em><code class="sig-prename descclassname">tarfile.</code><code class="sig-name descname">TarInfo</code><span class="sig-paren">(</span><em class="sig-param">name=""</em><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarInfo" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>创建一个 <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> 对象。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="tarfile.TarInfo.frombuf">
|
||
<em class="property">classmethod </em><code class="sig-prename descclassname">TarInfo.</code><code class="sig-name descname">frombuf</code><span class="sig-paren">(</span><em class="sig-param">buf</em>, <em class="sig-param">encoding</em>, <em class="sig-param">errors</em><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarInfo.frombuf" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>基于字符串缓冲区 <em>buf</em> 创建并返回一个 <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> 对象。</p>
|
||
<p>如果缓冲区无效则会引发 <a class="reference internal" href="#tarfile.HeaderError" title="tarfile.HeaderError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">HeaderError</span></code></a>。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="tarfile.TarInfo.fromtarfile">
|
||
<em class="property">classmethod </em><code class="sig-prename descclassname">TarInfo.</code><code class="sig-name descname">fromtarfile</code><span class="sig-paren">(</span><em class="sig-param">tarfile</em><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarInfo.fromtarfile" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>从 <a class="reference internal" href="#tarfile.TarFile" title="tarfile.TarFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarFile</span></code></a> 对象 <em>tarfile</em> 读取下一个成员并将其作为 <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> 对象返回。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="tarfile.TarInfo.tobuf">
|
||
<code class="sig-prename descclassname">TarInfo.</code><code class="sig-name descname">tobuf</code><span class="sig-paren">(</span><em class="sig-param">format=DEFAULT_FORMAT</em>, <em class="sig-param">encoding=ENCODING</em>, <em class="sig-param">errors='surrogateescape'</em><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarInfo.tobuf" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>基于 <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> 对象创建一个字符串缓冲区。 有关参数的信息请参见 <a class="reference internal" href="#tarfile.TarFile" title="tarfile.TarFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarFile</span></code></a> 类的构造器。</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.2 版更改: </span>使用 <code class="docutils literal notranslate"><span class="pre">'surrogateescape'</span></code> 作为 <em>errors</em> 参数的默认值。</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<p><code class="docutils literal notranslate"><span class="pre">TarInfo</span></code> 对象具有以下公有数据属性:</p>
|
||
<dl class="attribute">
|
||
<dt id="tarfile.TarInfo.name">
|
||
<code class="sig-prename descclassname">TarInfo.</code><code class="sig-name descname">name</code><em class="property">: str</em><a class="headerlink" href="#tarfile.TarInfo.name" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>归档成员的名称。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="tarfile.TarInfo.size">
|
||
<code class="sig-prename descclassname">TarInfo.</code><code class="sig-name descname">size</code><em class="property">: int</em><a class="headerlink" href="#tarfile.TarInfo.size" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>以字节表示的大小。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="tarfile.TarInfo.mtime">
|
||
<code class="sig-prename descclassname">TarInfo.</code><code class="sig-name descname">mtime</code><em class="property">: int | float</em><a class="headerlink" href="#tarfile.TarInfo.mtime" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>以 <a class="reference internal" href="time.html#epoch"><span class="std std-ref">Unix 纪元</span></a> 秒数表示的最近修改时间，与 <a class="reference internal" href="os.html#os.stat_result.st_mtime" title="os.stat_result.st_mtime"><code class="xref py py-attr docutils literal notranslate"><span class="pre">os.stat_result.st_mtime</span></code></a> 相同。</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.8.17 版更改: </span>对于 <a class="reference internal" href="#tarfile.TarFile.extract" title="tarfile.TarFile.extract"><code class="xref py py-meth docutils literal notranslate"><span class="pre">extract()</span></code></a> 和 <a class="reference internal" href="#tarfile.TarFile.extractall" title="tarfile.TarFile.extractall"><code class="xref py py-meth docutils literal notranslate"><span class="pre">extractall()</span></code></a> 可设为 <code class="docutils literal notranslate"><span class="pre">None</span></code>，以使解压缩操作跳过应用此属性。</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="tarfile.TarInfo.mode">
|
||
<code class="sig-prename descclassname">TarInfo.</code><code class="sig-name descname">mode</code><em class="property">: int</em><a class="headerlink" href="#tarfile.TarInfo.mode" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>权限比特位，与 <a class="reference internal" href="os.html#os.chmod" title="os.chmod"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.chmod()</span></code></a> 相同。</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.8.17 版更改: </span>对于 <a class="reference internal" href="#tarfile.TarFile.extract" title="tarfile.TarFile.extract"><code class="xref py py-meth docutils literal notranslate"><span class="pre">extract()</span></code></a> 和 <a class="reference internal" href="#tarfile.TarFile.extractall" title="tarfile.TarFile.extractall"><code class="xref py py-meth docutils literal notranslate"><span class="pre">extractall()</span></code></a> 可设为 <code class="docutils literal notranslate"><span class="pre">None</span></code>，以使解压缩操作跳过应用此属性。</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="tarfile.TarInfo.type">
|
||
<code class="sig-prename descclassname">TarInfo.</code><code class="sig-name descname">type</code><a class="headerlink" href="#tarfile.TarInfo.type" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>文件类型。 <em>type</em> 通常为以下常量之一: <code class="xref py py-const docutils literal notranslate"><span class="pre">REGTYPE</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">AREGTYPE</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">LNKTYPE</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">SYMTYPE</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">DIRTYPE</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">FIFOTYPE</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">CONTTYPE</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">CHRTYPE</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">BLKTYPE</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">GNUTYPE_SPARSE</span></code>。 要更方便地确定一个 <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> 对象的类型，请使用下述的 <code class="docutils literal notranslate"><span class="pre">is*()</span></code> 方法。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="tarfile.TarInfo.linkname">
|
||
<code class="sig-prename descclassname">TarInfo.</code><code class="sig-name descname">linkname</code><em class="property">: str</em><a class="headerlink" href="#tarfile.TarInfo.linkname" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>目标文件名的名称，该属性仅在类型为 <code class="xref py py-const docutils literal notranslate"><span class="pre">LNKTYPE</span></code> 和 <code class="xref py py-const docutils literal notranslate"><span class="pre">SYMTYPE</span></code> 的 <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> 对象中存在。</p>
|
||
<p>对于符号链接 (<code class="docutils literal notranslate"><span class="pre">SYMTYPE</span></code>)，<em>linkname</em> 是相对于包含链接的目录的。 对于硬链接 (<code class="docutils literal notranslate"><span class="pre">LNKTYPE</span></code>)，<em>linkname</em> 则是相对于存档根目录的。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="tarfile.TarInfo.uid">
|
||
<code class="sig-prename descclassname">TarInfo.</code><code class="sig-name descname">uid</code><em class="property">: int</em><a class="headerlink" href="#tarfile.TarInfo.uid" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>最初保存该成员的用户的用户 ID。</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.8.17 版更改: </span>对于 <a class="reference internal" href="#tarfile.TarFile.extract" title="tarfile.TarFile.extract"><code class="xref py py-meth docutils literal notranslate"><span class="pre">extract()</span></code></a> 和 <a class="reference internal" href="#tarfile.TarFile.extractall" title="tarfile.TarFile.extractall"><code class="xref py py-meth docutils literal notranslate"><span class="pre">extractall()</span></code></a> 可设为 <code class="docutils literal notranslate"><span class="pre">None</span></code>，以使解压缩操作跳过应用此属性。</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="tarfile.TarInfo.gid">
|
||
<code class="sig-prename descclassname">TarInfo.</code><code class="sig-name descname">gid</code><em class="property">: int</em><a class="headerlink" href="#tarfile.TarInfo.gid" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>最初保存该成员的用户的分组 ID。</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.8.17 版更改: </span>对于 <a class="reference internal" href="#tarfile.TarFile.extract" title="tarfile.TarFile.extract"><code class="xref py py-meth docutils literal notranslate"><span class="pre">extract()</span></code></a> 和 <a class="reference internal" href="#tarfile.TarFile.extractall" title="tarfile.TarFile.extractall"><code class="xref py py-meth docutils literal notranslate"><span class="pre">extractall()</span></code></a> 可设为 <code class="docutils literal notranslate"><span class="pre">None</span></code>，以使解压缩操作跳过应用此属性。</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="tarfile.TarInfo.uname">
|
||
<code class="sig-prename descclassname">TarInfo.</code><code class="sig-name descname">uname</code><em class="property">: str</em><a class="headerlink" href="#tarfile.TarInfo.uname" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>用户名。</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.8.17 版更改: </span>对于 <a class="reference internal" href="#tarfile.TarFile.extract" title="tarfile.TarFile.extract"><code class="xref py py-meth docutils literal notranslate"><span class="pre">extract()</span></code></a> 和 <a class="reference internal" href="#tarfile.TarFile.extractall" title="tarfile.TarFile.extractall"><code class="xref py py-meth docutils literal notranslate"><span class="pre">extractall()</span></code></a> 可设为 <code class="docutils literal notranslate"><span class="pre">None</span></code>，以使解压缩操作跳过应用此属性。</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="tarfile.TarInfo.gname">
|
||
<code class="sig-prename descclassname">TarInfo.</code><code class="sig-name descname">gname</code><em class="property">: str</em><a class="headerlink" href="#tarfile.TarInfo.gname" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>分组名。</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.8.17 版更改: </span>对于 <a class="reference internal" href="#tarfile.TarFile.extract" title="tarfile.TarFile.extract"><code class="xref py py-meth docutils literal notranslate"><span class="pre">extract()</span></code></a> 和 <a class="reference internal" href="#tarfile.TarFile.extractall" title="tarfile.TarFile.extractall"><code class="xref py py-meth docutils literal notranslate"><span class="pre">extractall()</span></code></a> 可设为 <code class="docutils literal notranslate"><span class="pre">None</span></code>，以使解压缩操作跳过应用此属性。</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="tarfile.TarInfo.pax_headers">
|
||
<code class="sig-prename descclassname">TarInfo.</code><code class="sig-name descname">pax_headers</code><em class="property">: dict</em><a class="headerlink" href="#tarfile.TarInfo.pax_headers" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>一个包含所关联的 pax 扩展标头的键值对的字典。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt>
|
||
<code class="sig-name descname">TarInfo.replace(name=..., mtime=..., mode=..., linkname=...,</code></dt>
|
||
<dt>
|
||
<code class="sig-name descname">uid=..., gid=..., uname=..., gname=...,</code></dt>
|
||
<dt>
|
||
<code class="sig-name descname">deep=True)</code></dt>
|
||
<dd><div class="versionadded">
|
||
<p><span class="versionmodified added">3.8.17 新版功能.</span></p>
|
||
</div>
|
||
<p>返回修改了给定属性的 <code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code> 对象的 <em>新</em> 副本。 例如，要返回组名设为 <code class="docutils literal notranslate"><span class="pre">'staff'</span></code> 的 <code class="docutils literal notranslate"><span class="pre">TarInfo</span></code>，请使用:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">new_tarinfo</span> <span class="o">=</span> <span class="n">old_tarinfo</span><span class="o">.</span><span class="n">replace</span><span class="p">(</span><span class="n">gname</span><span class="o">=</span><span class="s1">'staff'</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>在默认情况下，将执行深拷贝。 如果 <em>deep</em> 为假值，则执行浅拷贝，即 <code class="docutils literal notranslate"><span class="pre">pax_headers</span></code> 及任何自定义属性都与原始 <code class="docutils literal notranslate"><span class="pre">TarInfo</span></code> 对象共享。</p>
|
||
</dd></dl>
|
||
|
||
<p><a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> 对象还提供了一些便捷查询方法:</p>
|
||
<dl class="method">
|
||
<dt id="tarfile.TarInfo.isfile">
|
||
<code class="sig-prename descclassname">TarInfo.</code><code class="sig-name descname">isfile</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarInfo.isfile" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>如果 <code class="xref py py-class docutils literal notranslate"><span class="pre">Tarinfo</span></code> 对象为普通文件则返回 <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a>。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="tarfile.TarInfo.isreg">
|
||
<code class="sig-prename descclassname">TarInfo.</code><code class="sig-name descname">isreg</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarInfo.isreg" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>与 <a class="reference internal" href="#tarfile.TarInfo.isfile" title="tarfile.TarInfo.isfile"><code class="xref py py-meth docutils literal notranslate"><span class="pre">isfile()</span></code></a> 相同。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="tarfile.TarInfo.isdir">
|
||
<code class="sig-prename descclassname">TarInfo.</code><code class="sig-name descname">isdir</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarInfo.isdir" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>如果为目录则返回 <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a>。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="tarfile.TarInfo.issym">
|
||
<code class="sig-prename descclassname">TarInfo.</code><code class="sig-name descname">issym</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarInfo.issym" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>如果为符号链接则返回 <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a>。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="tarfile.TarInfo.islnk">
|
||
<code class="sig-prename descclassname">TarInfo.</code><code class="sig-name descname">islnk</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarInfo.islnk" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>如果为硬链接则返回 <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a>。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="tarfile.TarInfo.ischr">
|
||
<code class="sig-prename descclassname">TarInfo.</code><code class="sig-name descname">ischr</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarInfo.ischr" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>如果为字符设备则返回 <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a>。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="tarfile.TarInfo.isblk">
|
||
<code class="sig-prename descclassname">TarInfo.</code><code class="sig-name descname">isblk</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarInfo.isblk" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>如果为块设备则返回 <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a>。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="tarfile.TarInfo.isfifo">
|
||
<code class="sig-prename descclassname">TarInfo.</code><code class="sig-name descname">isfifo</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarInfo.isfifo" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>如果为 FIFO 则返回 <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a>。.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="tarfile.TarInfo.isdev">
|
||
<code class="sig-prename descclassname">TarInfo.</code><code class="sig-name descname">isdev</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarInfo.isdev" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>如果为字符设备、块设备或 FIFO 之一则返回 <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a>。</p>
|
||
</dd></dl>
|
||
|
||
</section>
|
||
<section id="extraction-filters">
|
||
<span id="tarfile-extraction-filter"></span><h2>解压缩过滤器<a class="headerlink" href="#extraction-filters" title="永久链接至标题">¶</a></h2>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">3.8.17 新版功能.</span></p>
|
||
</div>
|
||
<p><em>tar</em> 格式的设计旨在捕捉类 UNIX 文件系统的所有细节，这使其功能非常强大。 不幸的是，这些特性也使得很容易创建在解压缩时产生意想不到的 -- 甚至可能是恶意的 -- 影响的 tar 文件。 举例来说，解压缩 tar 文件时可以通过各种方式覆盖任意文件（例如通过使用绝对路径、<code class="docutils literal notranslate"><span class="pre">..</span></code> 路径组件或影响后续成员的符号链接等）。</p>
|
||
<p>在大多数情况下，并不需要全部的功能。 因此，<em>tarfile</em> 支持提取过滤器：一种限制功能的机制，从而避免一些安全问题。</p>
|
||
<div class="admonition seealso">
|
||
<p class="admonition-title">参见</p>
|
||
<dl class="simple">
|
||
<dt><span class="target" id="index-0"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0706"><strong>PEP 706</strong></a></dt><dd><p>包含设计背后进一步的动机和理由。</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
<p><a class="reference internal" href="#tarfile.TarFile.extract" title="tarfile.TarFile.extract"><code class="xref py py-meth docutils literal notranslate"><span class="pre">TarFile.extract()</span></code></a> 或 <a class="reference internal" href="#tarfile.TarFile.extractall" title="tarfile.TarFile.extractall"><code class="xref py py-meth docutils literal notranslate"><span class="pre">extractall()</span></code></a> 的 <em>filter</em> 参数可以是：</p>
|
||
<ul>
|
||
<li><p>字符串 <code class="docutils literal notranslate"><span class="pre">'fully_trusted'</span></code>：尊重归档文件中指定的所有元数据。 如果用户完全信任该归档，或实现了自己的复杂验证则应使用此过滤器。</p></li>
|
||
<li><p>字符串 <code class="docutils literal notranslate"><span class="pre">'tar'</span></code>: 尊重大多数 <em>tar</em> 专属的特性（即类 UNIX 文件系统的功能），但阻止极有可能令人惊讶的或恶意的功能。 详情参见 <a class="reference internal" href="#tarfile.tar_filter" title="tarfile.tar_filter"><code class="xref py py-func docutils literal notranslate"><span class="pre">tar_filter()</span></code></a>。</p></li>
|
||
<li><p>字符串 <code class="docutils literal notranslate"><span class="pre">'data'</span></code>：忽略或阻止大多数类 UNIX 文件系统专属的特性。 用于提取跨平台数据归档文件。 详情参见 <a class="reference internal" href="#tarfile.data_filter" title="tarfile.data_filter"><code class="xref py py-func docutils literal notranslate"><span class="pre">data_filter()</span></code></a>。</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">None</span></code> (默认): 使用 <a class="reference internal" href="#tarfile.TarFile.extraction_filter" title="tarfile.TarFile.extraction_filter"><code class="xref py py-attr docutils literal notranslate"><span class="pre">TarFile.extraction_filter</span></code></a>。</p>
|
||
<p>如果也是 <code class="docutils literal notranslate"><span class="pre">None</span></code> （默认值），则将使用 <code class="docutils literal notranslate"><span class="pre">'fully_trusted'</span></code> 过滤器（为了与 Python 早期版本兼容）。</p>
|
||
<p>在 Python 3.12 中，默认情况下会发出 <code class="docutils literal notranslate"><span class="pre">DeprecationWarning</span></code> 。</p>
|
||
<p>在 Python 3.14 中，<code class="docutils literal notranslate"><span class="pre">'data'</span></code> 过滤器将变成默认选项。 也可以提前切换，参见 <a class="reference internal" href="#tarfile.TarFile.extraction_filter" title="tarfile.TarFile.extraction_filter"><code class="xref py py-attr docutils literal notranslate"><span class="pre">TarFile.extraction_filter</span></code></a>。</p>
|
||
</li>
|
||
<li><p>该可调用对象将针每个被提取的成员执行调用并附带一个 <a class="reference internal" href="#tarinfo-objects"><span class="std std-ref">TarInfo</span></a> 来描述该成员以及被提取归档文件的目标路径（即供所有成员使用的相同路径）:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nb">filter</span><span class="p">(</span><span class="o">/</span><span class="p">,</span> <span class="n">member</span><span class="p">:</span> <span class="n">TarInfo</span><span class="p">,</span> <span class="n">path</span><span class="p">:</span> <span class="nb">str</span><span class="p">)</span> <span class="o">-></span> <span class="n">TarInfo</span> <span class="o">|</span> <span class="kc">None</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>该可调用对象会在提取每个成员之前被调用，因此它能够将磁盘的当前状态考虑在内。 它可以：</p>
|
||
<ul class="simple">
|
||
<li><p>返回一个 <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> 对象，该对象将被用来代替归档文件中的元数据，或者</p></li>
|
||
<li><p>返回 <code class="docutils literal notranslate"><span class="pre">None</span></code>，在这种情况下该成员将被跳过，或者</p></li>
|
||
<li><p>根据 <a class="reference internal" href="#tarfile.TarFile.errorlevel" title="tarfile.TarFile.errorlevel"><code class="xref py py-attr docutils literal notranslate"><span class="pre">errorlevel</span></code></a> 的值引发一个异常以中止操作或跳过成员。 请注意当提取操作中止时，<a class="reference internal" href="#tarfile.TarFile.extractall" title="tarfile.TarFile.extractall"><code class="xref py py-meth docutils literal notranslate"><span class="pre">extractall()</span></code></a> 可能会保留部分已提取的归档文件。 它不会尝试执行清理。</p></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<section id="default-named-filters">
|
||
<h3>默认的命名过滤器<a class="headerlink" href="#default-named-filters" title="永久链接至标题">¶</a></h3>
|
||
<p>预定义的命名过滤器可作为函数使用，因此它们可在自定义过滤器中被重用：</p>
|
||
<dl class="function">
|
||
<dt id="tarfile.fully_trusted_filter">
|
||
<code class="sig-prename descclassname">tarfile.</code><code class="sig-name descname">fully_trusted_filter</code><span class="sig-paren">(</span><em class="sig-param">/</em>, <em class="sig-param">member</em>, <em class="sig-param">path</em><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.fully_trusted_filter" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>不加修改地返回 <em>member</em>。</p>
|
||
<p>实现 <code class="docutils literal notranslate"><span class="pre">'fully_trusted'</span></code> 过滤器。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="tarfile.tar_filter">
|
||
<code class="sig-prename descclassname">tarfile.</code><code class="sig-name descname">tar_filter</code><span class="sig-paren">(</span><em class="sig-param">/</em>, <em class="sig-param">member</em>, <em class="sig-param">path</em><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.tar_filter" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>实现 <code class="docutils literal notranslate"><span class="pre">'tar'</span></code> 过滤器。</p>
|
||
<ul class="simple">
|
||
<li><p>Strip leading slashes (<code class="docutils literal notranslate"><span class="pre">/</span></code> and <a class="reference internal" href="os.html#os.sep" title="os.sep"><code class="xref py py-attr docutils literal notranslate"><span class="pre">os.sep</span></code></a>) from filenames.</p></li>
|
||
<li><p><a class="reference internal" href="#tarfile-extraction-refuse"><span class="std std-ref">拒绝</span></a> 提取具有绝对路径的文件（针对名称在去除斜杠后仍为绝对路径的情况，例如 Windows 上 <code class="docutils literal notranslate"><span class="pre">C:/foo</span></code> 这样的路径）。 这会引发 <a class="reference internal" href="#tarfile.AbsolutePathError" title="tarfile.AbsolutePathError"><code class="xref py py-class docutils literal notranslate"><span class="pre">AbsolutePathError</span></code></a>。</p></li>
|
||
<li><p><a class="reference internal" href="#tarfile-extraction-refuse"><span class="std std-ref">拒绝</span></a> 提取具有位于目标以外的绝对路径（跟随符号链接之后）的文件。这会引发 <a class="reference internal" href="#tarfile.OutsideDestinationError" title="tarfile.OutsideDestinationError"><code class="xref py py-class docutils literal notranslate"><span class="pre">OutsideDestinationError</span></code></a>。</p></li>
|
||
<li><p>Clear high mode bits (setuid, setgid, sticky) and group/other write bits
|
||
(<code class="xref py py-attr docutils literal notranslate"><span class="pre">S_IWOTH</span></code>).</p></li>
|
||
</ul>
|
||
<p>返回修改后的 <code class="docutils literal notranslate"><span class="pre">TarInfo</span></code> 成员。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="tarfile.data_filter">
|
||
<code class="sig-prename descclassname">tarfile.</code><code class="sig-name descname">data_filter</code><span class="sig-paren">(</span><em class="sig-param">/</em>, <em class="sig-param">member</em>, <em class="sig-param">path</em><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.data_filter" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>实现 <code class="docutils literal notranslate"><span class="pre">'data'</span></code> 过滤器。 在 <code class="docutils literal notranslate"><span class="pre">tar_filter</span></code> 的所具有的功能之外：</p>
|
||
<ul>
|
||
<li><p><a class="reference internal" href="#tarfile-extraction-refuse"><span class="std std-ref">拒绝</span></a> 提取链接到绝对路径的链接（不论是硬链接还是软链接），或链接到目标之外的链接。</p>
|
||
<p>这会引发 <a class="reference internal" href="#tarfile.AbsoluteLinkError" title="tarfile.AbsoluteLinkError"><code class="xref py py-class docutils literal notranslate"><span class="pre">AbsoluteLinkError</span></code></a> 或 <a class="reference internal" href="#tarfile.LinkOutsideDestinationError" title="tarfile.LinkOutsideDestinationError"><code class="xref py py-class docutils literal notranslate"><span class="pre">LinkOutsideDestinationError</span></code></a>。</p>
|
||
<p>请注意即使在不支持符号链接的平台上此类文件也会被拒绝。</p>
|
||
</li>
|
||
<li><p><a class="reference internal" href="#tarfile-extraction-refuse"><span class="std std-ref">拒绝</span></a> 提取设备文件（包括管道）。 这会引发 <a class="reference internal" href="#tarfile.SpecialFileError" title="tarfile.SpecialFileError"><code class="xref py py-class docutils literal notranslate"><span class="pre">SpecialFileError</span></code></a>。</p></li>
|
||
<li><p>用于常规文件，包括硬链接：</p>
|
||
<ul class="simple">
|
||
<li><p>Set the owner read and write permissions
|
||
(<code class="xref py py-attr docutils literal notranslate"><span class="pre">S_IWUSR</span></code>).</p></li>
|
||
<li><p>Remove the group & other executable permission
|
||
(<code class="xref py py-attr docutils literal notranslate"><span class="pre">S_IXOTH</span></code>)
|
||
if the owner doesn’t have it (<a class="reference internal" href="stat.html#stat.S_IXUSR" title="stat.S_IXUSR"><code class="xref py py-attr docutils literal notranslate"><span class="pre">S_IXUSR</span></code></a>).</p></li>
|
||
</ul>
|
||
</li>
|
||
<li><p>对于其他文件（目录），将 <code class="docutils literal notranslate"><span class="pre">mode</span></code> 设为 <code class="docutils literal notranslate"><span class="pre">None</span></code>，以便提取方法跳过应用权限位。</p></li>
|
||
<li><p>将用户和组信息 (<code class="docutils literal notranslate"><span class="pre">uid</span></code>, <code class="docutils literal notranslate"><span class="pre">gid</span></code>, <code class="docutils literal notranslate"><span class="pre">uname</span></code>, <code class="docutils literal notranslate"><span class="pre">gname</span></code>) 设为 <code class="docutils literal notranslate"><span class="pre">None</span></code>，以使得提取方法跳过对它的设置。</p></li>
|
||
</ul>
|
||
<p>返回修改后的 <code class="docutils literal notranslate"><span class="pre">TarInfo</span></code> 成员。</p>
|
||
</dd></dl>
|
||
|
||
</section>
|
||
<section id="filter-errors">
|
||
<span id="tarfile-extraction-refuse"></span><h3>过滤器错误<a class="headerlink" href="#filter-errors" title="永久链接至标题">¶</a></h3>
|
||
<p>当过滤器拒绝提取文件时，它将引发一个适当的异常，即 <a class="reference internal" href="#tarfile.FilterError" title="tarfile.FilterError"><code class="xref py py-class docutils literal notranslate"><span class="pre">FilterError</span></code></a> 的子类。 如果 <a class="reference internal" href="#tarfile.TarFile.errorlevel" title="tarfile.TarFile.errorlevel"><code class="xref py py-attr docutils literal notranslate"><span class="pre">TarFile.errorlevel</span></code></a> 为 1 或更大的值则提取将中止。 如果 <code class="docutils literal notranslate"><span class="pre">errorlevel=0</span></code> 则会记录错误并跳过该成员，但提取仍会继续。</p>
|
||
</section>
|
||
<section id="hints-for-further-verification">
|
||
<h3>进一步核验的提示<a class="headerlink" href="#hints-for-further-verification" title="永久链接至标题">¶</a></h3>
|
||
<p>即使 <code class="docutils literal notranslate"><span class="pre">filter='data'</span></code>，<em>tarfile</em> 也不适合在没有事先检查的情况下提取不受信任的文件。 除其他问题外，预定义的过滤器不能防止拒绝服务攻击。 用户应当进行额外的检查。</p>
|
||
<p>以下是一份不完整的考虑事项列表：</p>
|
||
<ul class="simple">
|
||
<li><p>提取到 <a class="reference internal" href="tempfile.html#tempfile.mkdtemp" title="tempfile.mkdtemp"><code class="xref py py-func docutils literal notranslate"><span class="pre">新的临时目录</span></code></a> 以避免滥用已存在的链接等问题，并使得提取失败后更容易清理。</p></li>
|
||
<li><p>在处理不受信任的数据时，使用外部（例如操作系统层级）的磁盘、内存和 CPU 使用限制。</p></li>
|
||
<li><p>根据允许字符列表检查文件名（来过滤控制字符、易混淆字符、外来路径分隔符等）。</p></li>
|
||
<li><p>检查文件名是否有预期的扩展名（不鼓励使用在“点击”时会被执行的文件，或像 Windows 特殊设备名称这样没有扩展名的文件）。</p></li>
|
||
<li><p>限制提取文件的数量、提取数据的总大小、文件名长度（包括符号链接长度）以及单个文件的大小。</p></li>
|
||
<li><p>检查在不区分大小写的文件系统上会被屏蔽的文件。</p></li>
|
||
</ul>
|
||
<p>还需要注意：</p>
|
||
<ul class="simple">
|
||
<li><p>Tar 文件可能包含同一文件的多个版本。 较晚的版本会覆盖任何较早的版本。 这一功能对于更新磁带归档来说至关重要，但也可能被恶意滥用。</p></li>
|
||
<li><p><em>tarfile</em> 无法为“实时”数据的问题提供保护，例如在提取（或归档）过程中攻击者对目标（或源）目录进行了改动。</p></li>
|
||
</ul>
|
||
</section>
|
||
<section id="supporting-older-python-versions">
|
||
<h3>支持较早的 Python 版本<a class="headerlink" href="#supporting-older-python-versions" title="永久链接至标题">¶</a></h3>
|
||
<p>Extraction filters were added to Python 3.12, and are backported to older
|
||
versions as security updates.
|
||
To check whether the feature is available, use e.g.
|
||
<code class="docutils literal notranslate"><span class="pre">hasattr(tarfile,</span> <span class="pre">'data_filter')</span></code> rather than checking the Python version.</p>
|
||
<p>下面的例子演示了如何支持带有和没有有该功能的 Python 版本。 请注意设置 <code class="docutils literal notranslate"><span class="pre">extraction_filter</span></code> 会影响任何后续的操作。</p>
|
||
<ul>
|
||
<li><p>完全受信任的归档:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">my_tarfile</span><span class="o">.</span><span class="n">extraction_filter</span> <span class="o">=</span> <span class="p">(</span><span class="k">lambda</span> <span class="n">member</span><span class="p">,</span> <span class="n">path</span><span class="p">:</span> <span class="n">member</span><span class="p">)</span>
|
||
<span class="n">my_tarfile</span><span class="o">.</span><span class="n">extractall</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p>如果可用则使用 <code class="docutils literal notranslate"><span class="pre">'data'</span></code> 过滤器；如果此特性不可用，则恢复为 Python 3.11 的行为 (<code class="docutils literal notranslate"><span class="pre">'fully_trusted'</span></code>):</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">my_tarfile</span><span class="o">.</span><span class="n">extraction_filter</span> <span class="o">=</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">tarfile</span><span class="p">,</span> <span class="s1">'data_filter'</span><span class="p">,</span>
|
||
<span class="p">(</span><span class="k">lambda</span> <span class="n">member</span><span class="p">,</span> <span class="n">path</span><span class="p">:</span> <span class="n">member</span><span class="p">))</span>
|
||
<span class="n">my_tarfile</span><span class="o">.</span><span class="n">extractall</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p>使用 <code class="docutils literal notranslate"><span class="pre">'data'</span></code> 过滤器；如果不可用则 <em>fail</em>:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">my_tarfile</span><span class="o">.</span><span class="n">extractall</span><span class="p">(</span><span class="nb">filter</span><span class="o">=</span><span class="n">tarfile</span><span class="o">.</span><span class="n">data_filter</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>或者：</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">my_tarfile</span><span class="o">.</span><span class="n">extraction_filter</span> <span class="o">=</span> <span class="n">tarfile</span><span class="o">.</span><span class="n">data_filter</span>
|
||
<span class="n">my_tarfile</span><span class="o">.</span><span class="n">extractall</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p>使用 <code class="docutils literal notranslate"><span class="pre">'data'</span></code> 过滤器；如果不可用则 <em>warn</em>:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="nb">hasattr</span><span class="p">(</span><span class="n">tarfile</span><span class="p">,</span> <span class="s1">'data_filter'</span><span class="p">):</span>
|
||
<span class="n">my_tarfile</span><span class="o">.</span><span class="n">extractall</span><span class="p">(</span><span class="nb">filter</span><span class="o">=</span><span class="s1">'data'</span><span class="p">)</span>
|
||
<span class="k">else</span><span class="p">:</span>
|
||
<span class="c1"># remove this when no longer needed</span>
|
||
<span class="n">warn_the_user</span><span class="p">(</span><span class="s1">'Extracting may be unsafe; consider updating Python'</span><span class="p">)</span>
|
||
<span class="n">my_tarfile</span><span class="o">.</span><span class="n">extractall</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
</ul>
|
||
</section>
|
||
<section id="stateful-extraction-filter-example">
|
||
<h3>有状态的提取过滤器示例<a class="headerlink" href="#stateful-extraction-filter-example" title="永久链接至标题">¶</a></h3>
|
||
<p><em>tarfile</em> 的提取方法接受一个简单的 <em>filter</em> 可调用对象，而自定义过滤器则可以是具有内部状态的更复杂对象。 将其写成为下文管理器可能会很有用处，即以这样的方式使用:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="n">StatefulFilter</span><span class="p">()</span> <span class="k">as</span> <span class="n">filter_func</span><span class="p">:</span>
|
||
<span class="n">tar</span><span class="o">.</span><span class="n">extractall</span><span class="p">(</span><span class="n">path</span><span class="p">,</span> <span class="nb">filter</span><span class="o">=</span><span class="n">filter_func</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>例如，这种过滤器可以写成:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">StatefulFilter</span><span class="p">:</span>
|
||
<span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">file_count</span> <span class="o">=</span> <span class="mi">0</span>
|
||
|
||
<span class="k">def</span> <span class="fm">__enter__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
|
||
<span class="k">return</span> <span class="bp">self</span>
|
||
|
||
<span class="k">def</span> <span class="fm">__call__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">member</span><span class="p">,</span> <span class="n">path</span><span class="p">):</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">file_count</span> <span class="o">+=</span> <span class="mi">1</span>
|
||
<span class="k">return</span> <span class="n">member</span>
|
||
|
||
<span class="k">def</span> <span class="fm">__exit__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="o">*</span><span class="n">exc_info</span><span class="p">):</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s1">'</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">file_count</span><span class="si">}</span><span class="s1"> files extracted'</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
</section>
|
||
<section id="command-line-interface">
|
||
<span id="tarfile-commandline"></span><h2>命令行接口<a class="headerlink" href="#command-line-interface" title="永久链接至标题">¶</a></h2>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">3.4 新版功能.</span></p>
|
||
</div>
|
||
<p><a class="reference internal" href="#module-tarfile" title="tarfile: Read and write tar-format archive files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">tarfile</span></code></a> 模块提供了简单的命令行接口以便与 tar 归档进行交互。</p>
|
||
<p>如果你想要创建一个新的 tar 归档，请在 <a class="reference internal" href="#cmdoption-tarfile-c"><code class="xref std std-option docutils literal notranslate"><span class="pre">-c</span></code></a> 选项后指定其名称然后列出应当被包含的文件名:</p>
|
||
<div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>python<span class="w"> </span>-m<span class="w"> </span>tarfile<span class="w"> </span>-c<span class="w"> </span>monty.tar<span class="w"> </span>spam.txt<span class="w"> </span>eggs.txt
|
||
</pre></div>
|
||
</div>
|
||
<p>传入一个目录也是可接受的:</p>
|
||
<div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>python<span class="w"> </span>-m<span class="w"> </span>tarfile<span class="w"> </span>-c<span class="w"> </span>monty.tar<span class="w"> </span>life-of-brian_1979/
|
||
</pre></div>
|
||
</div>
|
||
<p>如果你想要将一个 tar 归档提取到指定的目录，请使用 <a class="reference internal" href="#cmdoption-tarfile-e"><code class="xref std std-option docutils literal notranslate"><span class="pre">-e</span></code></a> 选项:</p>
|
||
<div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>python<span class="w"> </span>-m<span class="w"> </span>tarfile<span class="w"> </span>-e<span class="w"> </span>monty.tar
|
||
</pre></div>
|
||
</div>
|
||
<p>你也可以通过传入目录名称将一个 tar 归档提取到不同的目录:</p>
|
||
<div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>python<span class="w"> </span>-m<span class="w"> </span>tarfile<span class="w"> </span>-e<span class="w"> </span>monty.tar<span class="w"> </span>other-dir/
|
||
</pre></div>
|
||
</div>
|
||
<p>要获取一个 tar 归档中文件的列表，请使用 <a class="reference internal" href="#cmdoption-tarfile-l"><code class="xref std std-option docutils literal notranslate"><span class="pre">-l</span></code></a> 选项:</p>
|
||
<div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>python<span class="w"> </span>-m<span class="w"> </span>tarfile<span class="w"> </span>-l<span class="w"> </span>monty.tar
|
||
</pre></div>
|
||
</div>
|
||
<section id="command-line-options">
|
||
<h3>命令行选项<a class="headerlink" href="#command-line-options" title="永久链接至标题">¶</a></h3>
|
||
<dl class="cmdoption">
|
||
<dt id="cmdoption-tarfile-l">
|
||
<code class="sig-name descname">-l</code><code class="sig-prename descclassname"> <tarfile></code><a class="headerlink" href="#cmdoption-tarfile-l" title="永久链接至目标">¶</a></dt>
|
||
<dt id="cmdoption-tarfile-list">
|
||
<code class="sig-name descname">--list</code><code class="sig-prename descclassname"> <tarfile></code><a class="headerlink" href="#cmdoption-tarfile-list" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>列出一个 tarfile 中的文件名。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="cmdoption">
|
||
<dt id="cmdoption-tarfile-c">
|
||
<code class="sig-name descname">-c</code><code class="sig-prename descclassname"> <tarfile> <source1> ... <sourceN></code><a class="headerlink" href="#cmdoption-tarfile-c" title="永久链接至目标">¶</a></dt>
|
||
<dt id="cmdoption-tarfile-create">
|
||
<code class="sig-name descname">--create</code><code class="sig-prename descclassname"> <tarfile> <source1> ... <sourceN></code><a class="headerlink" href="#cmdoption-tarfile-create" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>基于源文件创建 tarfile。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="cmdoption">
|
||
<dt id="cmdoption-tarfile-e">
|
||
<code class="sig-name descname">-e</code><code class="sig-prename descclassname"> <tarfile> [<output_dir>]</code><a class="headerlink" href="#cmdoption-tarfile-e" title="永久链接至目标">¶</a></dt>
|
||
<dt id="cmdoption-tarfile-extract">
|
||
<code class="sig-name descname">--extract</code><code class="sig-prename descclassname"> <tarfile> [<output_dir>]</code><a class="headerlink" href="#cmdoption-tarfile-extract" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>如果未指定 <em>output_dir</em> 则会将 tarfile 提取到当前目录。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="cmdoption">
|
||
<dt id="cmdoption-tarfile-t">
|
||
<code class="sig-name descname">-t</code><code class="sig-prename descclassname"> <tarfile></code><a class="headerlink" href="#cmdoption-tarfile-t" title="永久链接至目标">¶</a></dt>
|
||
<dt id="cmdoption-tarfile-test">
|
||
<code class="sig-name descname">--test</code><code class="sig-prename descclassname"> <tarfile></code><a class="headerlink" href="#cmdoption-tarfile-test" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>检测 tarfile 是否有效。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="cmdoption">
|
||
<dt id="cmdoption-tarfile-v">
|
||
<code class="sig-name descname">-v</code><code class="sig-prename descclassname"></code><code class="sig-prename descclassname">, </code><code class="sig-name descname">--verbose</code><code class="sig-prename descclassname"></code><a class="headerlink" href="#cmdoption-tarfile-v" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>更详细地输出结果。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="cmdoption">
|
||
<dt id="cmdoption-tarfile-filter">
|
||
<code class="sig-name descname">--filter</code><code class="sig-prename descclassname"> <filtername></code><a class="headerlink" href="#cmdoption-tarfile-filter" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>为 <code class="docutils literal notranslate"><span class="pre">--extract</span></code> 指定 <em>filter</em>。 详情参见 <a class="reference internal" href="#tarfile-extraction-filter"><span class="std std-ref">解压缩过滤器</span></a>。 只接受字符串名称 (包括 <code class="docutils literal notranslate"><span class="pre">fully_trusted</span></code>, <code class="docutils literal notranslate"><span class="pre">tar</span></code> 和 <code class="docutils literal notranslate"><span class="pre">data</span></code>)。</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">3.8.17 新版功能.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
</section>
|
||
</section>
|
||
<section id="examples">
|
||
<span id="tar-examples"></span><h2>例子<a class="headerlink" href="#examples" title="永久链接至标题">¶</a></h2>
|
||
<p>如何将整个 tar 归档提取到当前工作目录:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">tarfile</span>
|
||
<span class="n">tar</span> <span class="o">=</span> <span class="n">tarfile</span><span class="o">.</span><span class="n">open</span><span class="p">(</span><span class="s2">"sample.tar.gz"</span><span class="p">)</span>
|
||
<span class="n">tar</span><span class="o">.</span><span class="n">extractall</span><span class="p">()</span>
|
||
<span class="n">tar</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>如何通过 <a class="reference internal" href="#tarfile.TarFile.extractall" title="tarfile.TarFile.extractall"><code class="xref py py-meth docutils literal notranslate"><span class="pre">TarFile.extractall()</span></code></a> 使用生成器函数而非列表来提取一个 tar 归档的子集:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">os</span>
|
||
<span class="kn">import</span> <span class="nn">tarfile</span>
|
||
|
||
<span class="k">def</span> <span class="nf">py_files</span><span class="p">(</span><span class="n">members</span><span class="p">):</span>
|
||
<span class="k">for</span> <span class="n">tarinfo</span> <span class="ow">in</span> <span class="n">members</span><span class="p">:</span>
|
||
<span class="k">if</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">splitext</span><span class="p">(</span><span class="n">tarinfo</span><span class="o">.</span><span class="n">name</span><span class="p">)[</span><span class="mi">1</span><span class="p">]</span> <span class="o">==</span> <span class="s2">".py"</span><span class="p">:</span>
|
||
<span class="k">yield</span> <span class="n">tarinfo</span>
|
||
|
||
<span class="n">tar</span> <span class="o">=</span> <span class="n">tarfile</span><span class="o">.</span><span class="n">open</span><span class="p">(</span><span class="s2">"sample.tar.gz"</span><span class="p">)</span>
|
||
<span class="n">tar</span><span class="o">.</span><span class="n">extractall</span><span class="p">(</span><span class="n">members</span><span class="o">=</span><span class="n">py_files</span><span class="p">(</span><span class="n">tar</span><span class="p">))</span>
|
||
<span class="n">tar</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>如何基于一个文件名列表创建未压缩的 tar 归档:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">tarfile</span>
|
||
<span class="n">tar</span> <span class="o">=</span> <span class="n">tarfile</span><span class="o">.</span><span class="n">open</span><span class="p">(</span><span class="s2">"sample.tar"</span><span class="p">,</span> <span class="s2">"w"</span><span class="p">)</span>
|
||
<span class="k">for</span> <span class="n">name</span> <span class="ow">in</span> <span class="p">[</span><span class="s2">"foo"</span><span class="p">,</span> <span class="s2">"bar"</span><span class="p">,</span> <span class="s2">"quux"</span><span class="p">]:</span>
|
||
<span class="n">tar</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="n">name</span><span class="p">)</span>
|
||
<span class="n">tar</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>使用 <a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> 语句的同一个示例:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">tarfile</span>
|
||
<span class="k">with</span> <span class="n">tarfile</span><span class="o">.</span><span class="n">open</span><span class="p">(</span><span class="s2">"sample.tar"</span><span class="p">,</span> <span class="s2">"w"</span><span class="p">)</span> <span class="k">as</span> <span class="n">tar</span><span class="p">:</span>
|
||
<span class="k">for</span> <span class="n">name</span> <span class="ow">in</span> <span class="p">[</span><span class="s2">"foo"</span><span class="p">,</span> <span class="s2">"bar"</span><span class="p">,</span> <span class="s2">"quux"</span><span class="p">]:</span>
|
||
<span class="n">tar</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="n">name</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>如何读取一个 gzip 压缩的 tar 归档并显示一些成员信息:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">tarfile</span>
|
||
<span class="n">tar</span> <span class="o">=</span> <span class="n">tarfile</span><span class="o">.</span><span class="n">open</span><span class="p">(</span><span class="s2">"sample.tar.gz"</span><span class="p">,</span> <span class="s2">"r:gz"</span><span class="p">)</span>
|
||
<span class="k">for</span> <span class="n">tarinfo</span> <span class="ow">in</span> <span class="n">tar</span><span class="p">:</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="n">tarinfo</span><span class="o">.</span><span class="n">name</span><span class="p">,</span> <span class="s2">"is"</span><span class="p">,</span> <span class="n">tarinfo</span><span class="o">.</span><span class="n">size</span><span class="p">,</span> <span class="s2">"bytes in size and is "</span><span class="p">,</span> <span class="n">end</span><span class="o">=</span><span class="s2">""</span><span class="p">)</span>
|
||
<span class="k">if</span> <span class="n">tarinfo</span><span class="o">.</span><span class="n">isreg</span><span class="p">():</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="s2">"a regular file."</span><span class="p">)</span>
|
||
<span class="k">elif</span> <span class="n">tarinfo</span><span class="o">.</span><span class="n">isdir</span><span class="p">():</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="s2">"a directory."</span><span class="p">)</span>
|
||
<span class="k">else</span><span class="p">:</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="s2">"something else."</span><span class="p">)</span>
|
||
<span class="n">tar</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>如何创建一个归档并使用 <a class="reference internal" href="#tarfile.TarFile.add" title="tarfile.TarFile.add"><code class="xref py py-meth docutils literal notranslate"><span class="pre">TarFile.add()</span></code></a> 中的 <em>filter</em> 形参来重置用户信息:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">tarfile</span>
|
||
<span class="k">def</span> <span class="nf">reset</span><span class="p">(</span><span class="n">tarinfo</span><span class="p">):</span>
|
||
<span class="n">tarinfo</span><span class="o">.</span><span class="n">uid</span> <span class="o">=</span> <span class="n">tarinfo</span><span class="o">.</span><span class="n">gid</span> <span class="o">=</span> <span class="mi">0</span>
|
||
<span class="n">tarinfo</span><span class="o">.</span><span class="n">uname</span> <span class="o">=</span> <span class="n">tarinfo</span><span class="o">.</span><span class="n">gname</span> <span class="o">=</span> <span class="s2">"root"</span>
|
||
<span class="k">return</span> <span class="n">tarinfo</span>
|
||
<span class="n">tar</span> <span class="o">=</span> <span class="n">tarfile</span><span class="o">.</span><span class="n">open</span><span class="p">(</span><span class="s2">"sample.tar.gz"</span><span class="p">,</span> <span class="s2">"w:gz"</span><span class="p">)</span>
|
||
<span class="n">tar</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s2">"foo"</span><span class="p">,</span> <span class="nb">filter</span><span class="o">=</span><span class="n">reset</span><span class="p">)</span>
|
||
<span class="n">tar</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="supported-tar-formats">
|
||
<span id="tar-formats"></span><h2>受支持的 tar 格式<a class="headerlink" href="#supported-tar-formats" title="永久链接至标题">¶</a></h2>
|
||
<p>通过 <a class="reference internal" href="#module-tarfile" title="tarfile: Read and write tar-format archive files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">tarfile</span></code></a> 模块可以创建三种 tar 格式:</p>
|
||
<ul>
|
||
<li><p>The POSIX.1-1988 ustar 格式 (<a class="reference internal" href="#tarfile.USTAR_FORMAT" title="tarfile.USTAR_FORMAT"><code class="xref py py-const docutils literal notranslate"><span class="pre">USTAR_FORMAT</span></code></a>)。 它支持最多 256 个字符的文件名长度和最多 100 个字符的链接名长度。 文件大小上限为 8 GiB。 这是一种老旧但广受支持的格式。</p></li>
|
||
<li><p>GNU tar 格式 (<a class="reference internal" href="#tarfile.GNU_FORMAT" title="tarfile.GNU_FORMAT"><code class="xref py py-const docutils literal notranslate"><span class="pre">GNU_FORMAT</span></code></a>)。 它支持长文件名和链接名、大于 8 GiB 的文件以及稀疏文件。 它是 GNU/Linux 系统上的事实标准。 <a class="reference internal" href="#module-tarfile" title="tarfile: Read and write tar-format archive files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">tarfile</span></code></a> 完全支持针对长名称的 GNU tar 扩展，稀疏文件支持则限制为只读。</p></li>
|
||
<li><p>POSIX.1-2001 pax 格式 (<a class="reference internal" href="#tarfile.PAX_FORMAT" title="tarfile.PAX_FORMAT"><code class="xref py py-const docutils literal notranslate"><span class="pre">PAX_FORMAT</span></code></a>)。 它是几乎无限制的最灵活格式。 它支持长文件名和链接名，大文件以及使用便捷方式存储路径名。 现代的 tar 实现，包括 GNU tar, bsdtar/libarchive 和 star，完全支持扩展 <em>pax</em> 特性；某些老旧或不维护的库可能不受支持，但应当会将 <em>pax</em> 归档视为广受支持的 <em>ustar</em> 格式。 这是目前新建归档的默认格式。</p>
|
||
<p>它扩展了现有的 <em>ustar</em> 格式，包括用于无法以其他方式存储的附加标头。 存在两种形式的 pax 标头：扩展标头只影响后续的文件标头，全局标头则适用于完整归档并会影响所有后续的文件。 为了便于移植，在 pax 标头中的所有数据均以 <em>UTF-8</em> 编码。</p>
|
||
</li>
|
||
</ul>
|
||
<p>还有一些 tar 格式的其他变种，它们可以被读取但不能被创建:</p>
|
||
<ul class="simple">
|
||
<li><p>古老的 V7 格式。 这是来自 Unix 第七版的第一个 tar 格式，它只存储常规文件和目录。 名称长度不能超过 100 个字符，并且没有用户/分组名信息。 某些归档在带有非 ASCII 字符字段的情况下会产生计算错误的标头校验和。</p></li>
|
||
<li><p>SunOS tar 扩展格式。 此格式是 POSIX.1-2001 pax 格式的一个变种，但并不保持兼容。</p></li>
|
||
</ul>
|
||
</section>
|
||
<section id="unicode-issues">
|
||
<span id="tar-unicode"></span><h2>Unicode 问题<a class="headerlink" href="#unicode-issues" title="永久链接至标题">¶</a></h2>
|
||
<p>最初 tar 格式被设计用来在磁带机上生成备份，主要关注于保存文件系统信息。 现在 tar 归档通常用于文件分发和在网络上交换归档。 最初格式（它是所有其他格式的基础）的一个问题是它没有支持不同字符编码格式的概念。 例如，一个在 <em>UTF-8</em> 系统上创建的普通 tar 归档如果包含非 <em>ASCII</em> 字符则将无法在 <em>Latin-1</em> 系统上被正确读取。 文本元数据（例如文件名，链接名，用户/分组名）将变为损坏状态。 不幸的是，没有什么办法能够自动检测一个归档的编码格式。 pax 格式被设计用来解决这个问题。 它使用通用字符编码格式 <em>UTF-8</em> 来存储非 ASCII 元数据。</p>
|
||
<p>在 <a class="reference internal" href="#module-tarfile" title="tarfile: Read and write tar-format archive files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">tarfile</span></code></a> 中字符转换的细节由 <a class="reference internal" href="#tarfile.TarFile" title="tarfile.TarFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarFile</span></code></a> 类的 <em>encoding</em> 和 <em>errors</em> 关键字参数控制。</p>
|
||
<p><em>encoding</em> 定义了用于归档中元数据的字符编码格式。 默认值为 <a class="reference internal" href="sys.html#sys.getfilesystemencoding" title="sys.getfilesystemencoding"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.getfilesystemencoding()</span></code></a> 或是回退选项 <code class="docutils literal notranslate"><span class="pre">'ascii'</span></code>。 根据归档是被读取还是被写入，元数据必须被解码或编码。 如果没有正确设置 <em>encoding</em>，转换可能会失败。</p>
|
||
<p><em>errors</em> 参数定义了不能被转换的字符将如何处理。 可能的取值在 <a class="reference internal" href="codecs.html#error-handlers"><span class="std std-ref">错误处理方案</span></a> 小节列出。 默认方案为 <code class="docutils literal notranslate"><span class="pre">'surrogateescape'</span></code>，它也被 Python 用于文件系统调用，参见 <a class="reference internal" href="os.html#os-filenames"><span class="std std-ref">文件名，命令行参数，以及环境变量。</span></a>。</p>
|
||
<p>对于 <a class="reference internal" href="#tarfile.PAX_FORMAT" title="tarfile.PAX_FORMAT"><code class="xref py py-const docutils literal notranslate"><span class="pre">PAX_FORMAT</span></code></a> 归档（默认格式），<em>encoding</em> 通常是不必要的，因为所有元数据都使用 <em>UTF-8</em> 来存储。 <em>encoding</em> 仅在解码二进制 pax 标头或存储带有替代字符的字符串等少数场景下会被使用。</p>
|
||
</section>
|
||
</section>
|
||
|
||
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
||
<div class="sphinxsidebarwrapper">
|
||
<h3><a href="../contents.html">目录</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">tarfile</span></code> --- 读写tar归档文件</a><ul>
|
||
<li><a class="reference internal" href="#tarfile-objects">TarFile 对象</a></li>
|
||
<li><a class="reference internal" href="#tarinfo-objects">TarInfo 对象</a></li>
|
||
<li><a class="reference internal" href="#extraction-filters">解压缩过滤器</a><ul>
|
||
<li><a class="reference internal" href="#default-named-filters">默认的命名过滤器</a></li>
|
||
<li><a class="reference internal" href="#filter-errors">过滤器错误</a></li>
|
||
<li><a class="reference internal" href="#hints-for-further-verification">进一步核验的提示</a></li>
|
||
<li><a class="reference internal" href="#supporting-older-python-versions">支持较早的 Python 版本</a></li>
|
||
<li><a class="reference internal" href="#stateful-extraction-filter-example">有状态的提取过滤器示例</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#command-line-interface">命令行接口</a><ul>
|
||
<li><a class="reference internal" href="#command-line-options">命令行选项</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#examples">例子</a></li>
|
||
<li><a class="reference internal" href="#supported-tar-formats">受支持的 tar 格式</a></li>
|
||
<li><a class="reference internal" href="#unicode-issues">Unicode 问题</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<h4>上一个主题</h4>
|
||
<p class="topless"><a href="zipfile.html"
|
||
title="上一章"><code class="xref py py-mod docutils literal notranslate"><span class="pre">zipfile</span></code> --- 使用ZIP存档</a></p>
|
||
<h4>下一个主题</h4>
|
||
<p class="topless"><a href="fileformats.html"
|
||
title="下一章">文件格式</a></p>
|
||
<div role="note" aria-label="source link">
|
||
<h3>本页</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="../bugs.html">报告 Bug</a></li>
|
||
<li>
|
||
<a href="https://github.com/python/cpython/blob/3.8/Doc/library/tarfile.rst"
|
||
rel="nofollow">显示源代码
|
||
</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="clearer"></div>
|
||
</div>
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>导航</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="总目录"
|
||
>索引</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python 模块索引"
|
||
>模块</a> |</li>
|
||
<li class="right" >
|
||
<a href="fileformats.html" title="文件格式"
|
||
>下一页</a> |</li>
|
||
<li class="right" >
|
||
<a href="zipfile.html" title="zipfile --- 使用ZIP存档"
|
||
>上一页</a> |</li>
|
||
|
||
<li><img src="../_static/py.svg" alt="python logo" style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li class="switchers">
|
||
<div class="language_switcher_placeholder"></div>
|
||
<div class="version_switcher_placeholder"></div>
|
||
</li>
|
||
<li>
|
||
|
||
</li>
|
||
<li id="cpython-language-and-version">
|
||
<a href="../index.html">3.8.20 Documentation</a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >Python 标准库</a> »</li>
|
||
<li class="nav-item nav-item-2"><a href="archiving.html" >数据压缩和存档</a> »</li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="快速搜索" aria-label="快速搜索" type="text" name="q" />
|
||
<input type="submit" value="转向" />
|
||
<input type="hidden" name="check_keywords" value="yes" />
|
||
<input type="hidden" name="area" value="default" />
|
||
</form>
|
||
</div>
|
||
|
|
||
</li>
|
||
|
||
</ul>
|
||
</div>
|
||
<div class="footer">
|
||
© <a href="../copyright.html">版权所有</a> 2001-2024, Python Software Foundation.
|
||
<br />
|
||
This page is licensed under the Python Software Foundation License Version 2.
|
||
<br />
|
||
Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.
|
||
<br />
|
||
|
||
<br />
|
||
|
||
The Python Software Foundation is a non-profit corporation.
|
||
<a href="https://www.python.org/psf/donations/">Please donate.</a>
|
||
<br />
|
||
<br />
|
||
|
||
最后更新于 12月 09, 2024.
|
||
<a href="https://docs.python.org/3/bugs.html">Found a bug</a>?
|
||
<br />
|
||
|
||
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 2.4.4.
|
||
</div>
|
||
|
||
</body>
|
||
</html> |