12.5. tarfile —读写 tar 存档文件

2.3 版的新Function。

源代码： Lib/tarfile.py

tarfile模块可以读取和写入 tarFiles，包括使用 gzip 或 bz2 压缩的 Files。使用zipfile模块读取或写入.zip文件，或使用shutil中的更高级Function。

一些事实和数据：

2.6 版的新Function。

Note

不支持多流 bzip2 文件的处理。诸如bz2file之类的模块可帮助您克服这一问题。

mode action
'r' or 'r:*' 打开以透明压缩方式阅读(推荐)。
'r:' 仅打开即可阅读，无需压缩。
'r:gz' pass gzip 压缩打开以供阅读。
'r:bz2' 打开以使用 bzip2 压缩进行阅读。
'a' or 'a:' 打开以进行追加而没有压缩。如果文件不存在，则创建该文件。
'w' or 'w:' 打开以进行未压缩的写入。
'w:gz' 打开以进行 gzip 压缩书写。
'w:bz2' 打开以进行 bzip2 压缩写入。

请注意，不能使用'a:gz'或'a:bz2'。如果* mode 不适合打开某个(压缩的)文件进行读取，则会引发ReadError。使用 mode * 'r'避免这种情况。如果不支持压缩方法，则会引发CompressionError。

如果指定了* fileobj ，它将用作为 name *打开的文件对象的替代。它应该位于位置 0.

对于模式'w:gz'，'r:gz'，'w:bz2'，'r:bz2'，tarfile.open()接受关键字参数* compresslevel *(默认为9)来指定文件的压缩级别。

出于特殊目的，* mode 还有第二种格式：'filemode|[compression]'。 tarfile.open()将返回一个TarFile对象，该对象将其数据作为块流处理。不会对文件进行随机查找。如果给定， fileobj 可以是具有read()或write()方法的任何对象(取决于 mode *)。 * bufsize *指定块大小，默认为20 * 512字节。结合使用此变体，例如sys.stdin，套接字文件对象或磁带设备。但是，这样的TarFile对象受到限制，因为它不允许随机访问，请参见Examples。当前可能的模式：

Mode Action
'r|*' 打开 tar 数据块流以透明压缩方式进行读取。
'r|' 打开未压缩的 tar 块的“流”以进行读取。
'r|gz' 打开一个 gzip 压缩的* stream *进行阅读。
'r|bz2' 打开一个 bzip2 压缩的* stream *进行读取。
'w|' 打开未压缩的* stream *进行写入。
'w|gz' 打开一个压缩的* stream * gzip 进行编写。
'w|bz2' 打开一个 bzip2 压缩的* stream *进行写入。

自 2.6 版起弃用：TarFileCompat类已在 Python 3 中删除。

以下常量在模块级别可用：

2.6 版的新Function。

以下每个常量定义tarfile模块能够创建的 tar 存档格式。有关详情，请参见支持的 tar 格式部分。

See also

12.5.1. TarFile 对象

TarFile对象提供 tar 存档的接口。 tar 存档是一系列块。存档成员(存储的文件)由标题块和数据块组成。可以将文件多次存储在 tar 归档中。每个存档成员由TarInfo对象表示，有关详细信息，请参见TarInfo Objects。

TarFile对象可用作with语句中的上下文 Management 器。块完成后，它将自动关闭。请注意，如果发生 exceptions，打开的存档归档文件将不会finally确定；仅内部使用的文件对象将被关闭。有关用例，请参见Examples部分。

2.7 版的新Function：添加了对上下文 Management 协议的支持。

如果给出* fileobj ，则用于读取或写入数据。如果可以确定，则 mode 被 fileobj *的 mode 覆盖。 * fileobj *将从位置 0 开始使用。

Note

TarFile关闭时，* fileobj *没有关闭。

2.6 版的新Function。

2.6 版的新Function。

如果* dereference *为False，则将符号链接和硬链接添加到存档。如果为True，则将目标文件的内容添加到存档中。这对不支持符号链接的系统没有影响。

如果* ignore_zeros *为False，则将一个空块视为存档的结尾。如果是True，请跳过空的(和无效的)块，并try获取尽可能多的成员。这仅对读取串联或损坏的 Files 有用。

如果* errorlevel 为0，则使用TarFile.extract()时将忽略所有错误。但是，启用调试后，它们将作为错误消息出现在调试输出中。如果为1，则所有致命*错误都会引发为OSError或IOErrorexception。如果为2，则所有非致命错误也会作为TarError异常引发。

2.6 版的新Function。

2.6 版的新Function。

Note

如果成员在存档中出现多次，则假定其最后一次出现是最新版本。

Warning

未经事先检查，切勿从不受信任的来源中提取 Files。文件可能是在* path *之外创建的，例如具有以"/"开头的绝对文件名或带有两个点".."的文件名的成员。

2.5 版的新Function。

Note

extract()方法无法解决多个提取问题。在大多数情况下，您应该考虑使用extractall()方法。

Warning

请参阅extractall()的警告。

Note

类文件对象是只读的。它提供了read()，readline()，readlines()，seek()，tell()和close()的方法，并且还支持其上的迭代。

在 2.6 版中进行了更改：添加了* exclude *参数。

在 2.7 版中进行了更改：添加了* filter *参数。

从 2.7 版开始不推荐使用：* exclude 参数不推荐使用，请改用 filter 参数。为了获得最大的可移植性，应将 filter 用作关键字参数而不是位置参数，以便在finally删除 exclude *时不会影响代码。

Note

在 Windows 平台上，* fileobj *应该始终以'rb'模式打开，以避免对文件大小产生刺激。

您可以先修改TarInfo的某些属性，然后再使用addfile()添加它。如果文件对象不是位于文件开头的普通文件对象，则可能需要修改诸如size的属性。诸如GzipFile之类的对象就是这种情况。 name也可以被修改，在这种情况下，* arcname *可以是虚拟字符串。

在版本 2.4 中更改：* posix *默认为False。

从 2.6 版开始不推荐使用：而是使用format属性。

2.6 版的新Function。

12.5.2. TarInfo 对象

TarInfo对象代表TarFile中的一个成员。除了存储文件的所有必需属性(如文件类型，大小，时间，权限，所有者等)之外，它还提供了一些有用的方法来确定其类型。它不包含文件本身的数据。

TarInfo对象是由TarFile的方法getmember()，getmembers()和gettarinfo()返回的。

2.6 版中的新增Function：如果缓冲区无效，则引发HeaderError。

2.6 版的新Function。

在 2.6 版中进行了更改：添加了自变量。

TarInfo对象具有以下公共数据属性：

2.6 版的新Function。

TarInfo对象还提供了一些方便的查询方法：

12.5.3. Examples

如何将整个 tar 归档文件提取到当前工作目录：

import tarfile
tar = tarfile.open("sample.tar.gz")
tar.extractall()
tar.close()

如何使用生成器函数而不是列表使用TarFile.extractall()提取 tar 存档的子集：

import os
import tarfile

def py_files(members):
    for tarinfo in members:
        if os.path.splitext(tarinfo.name)[1] == ".py":
            yield tarinfo

tar = tarfile.open("sample.tar.gz")
tar.extractall(members=py_files(tar))
tar.close()

如何从文件名列表创建未压缩的 tar 存档：

import tarfile
tar = tarfile.open("sample.tar", "w")
for name in ["foo", "bar", "quux"]:
    tar.add(name)
tar.close()

使用with语句的相同示例：

import tarfile
with tarfile.open("sample.tar", "w") as tar:
    for name in ["foo", "bar", "quux"]:
        tar.add(name)

如何读取 gzip 压缩的 tar 归档文件并显示一些成员信息：

import tarfile
tar = tarfile.open("sample.tar.gz", "r:gz")
for tarinfo in tar:
    print tarinfo.name, "is", tarinfo.size, "bytes in size and is",
    if tarinfo.isreg():
        print "a regular file."
    elif tarinfo.isdir():
        print "a directory."
    else:
        print "something else."
tar.close()

如何使用TarFile.add()中的* filter *参数创建 Files 并重置用户信息：

import tarfile
def reset(tarinfo):
    tarinfo.uid = tarinfo.gid = 0
    tarinfo.uname = tarinfo.gname = "root"
    return tarinfo
tar = tarfile.open("sample.tar.gz", "w:gz")
tar.add("foo", filter=reset)
tar.close()

12.5.4. 支持的 tar 格式

tarfile模块可以创建三种 tar 格式：

可以读取但无法创建的 tar 格式还有更多变体：

12.5.5. Unicode 问题

tar 格式最初是为了在磁带驱动器上进行备份而设计的，其主要重点是保留文件系统信息。如今，tarFiles 通常用于文件分发和pass网络交换 Files。原始格式(所有其他格式仅仅是其变体)的一个问题是，没有支持不同字符编码的概念。例如，如果在* UTF-8 系统上创建的普通 tar 存档包含非 ASCII 字符，则无法在 Latin-1 *系统上正确读取。包含这些字符的名称(即文件名，链接名，用户/组名)将显示为已损坏。不幸的是，没有办法自动检测 Files 的编码。

pax 格式旨在解决此问题。它使用通用字符编码* UTF-8 存储非 ASCII 名称。读取 pax 存档时，这些 UTF-8 *名称将转换为本地文件系统的编码。

Unicode 转换的详细信息由TarFile类的* encoding 和 errors *关键字参数控制。

首页