Pythontarfile读写tar归档文件

TarFile 对象¶

TarFile 对象提供了一个 tar 归档的接口。 一个 tar 归档就是数据块的序列。 一个归档成员（被保存文件）是由一个标头块加多个数据块组成的。 一个文件可以在一个 tar 归档中多次被保存。 每个归档成员都由一个 TarInfo 对象来代表，详情参见 TarInfo 对象。

TarFile 对象可在 with 语句中作为上下文管理器使用。 当语句块结束时它将自动被关闭。 请注意在发生异常事件时被打开用于写入的归档将不会被终结；只有内部使用的文件对象将被关闭。 相关用例请参见 例子。

class tarfile.TarFile(name=None, mode='r', fileobj=None, format=DEFAULT_FORMAT, tarinfo=TarInfo, dereference=False, ignore_zeros=False, encoding=ENCODING, errors='surrogateescape', pax_headers=None, debug=0, errorlevel=0)

下列所有参数都是可选项并且也可作为实例属性来访问。

name 是归档的路径名称。 name 可以是一个 path-like object。 如果给定了 fileobj 则它可以被省略。 在此情况下，如果对象的 name 属性存在则它会被使用。

mode 可以为 'r' 表示从现有归档读取，'a' 表示将数据追加到现有文件，'w' 表示创建新文件覆盖现有文件，或者 'x' 表示仅在文件不存在时创建新文件。

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

注解

当 TarFile 被关闭时，fileobj 不会被关闭。

format 控制归档格式。 它必须为在模块层级定义的常量 USTAR_FORMAT, GNU_FORMAT 或 PAX_FORMAT 中的一个。

tarinfo 参数可以被用来将默认的 TarInfo 类替换为另一个。

如果 dereference 为 False，则会将符号链接和硬链接添加到归档中。 如果为 True，则会将目标文件的内容添加到归档中。 在不支持符号链接的系统上参数将不起作用。

如果 ignore_zeros 为 False，则会将空的数据块当作归档的末尾来处理。 如果为 True，则会跳过空的（和无效的）数据块并尝试获取尽可能多的成员。 此参数仅适用于读取拼接的或损坏的归档。

debug 可设为从 0 (无调试消息) 到 3 (全部调试消息)。 消息会被写入到 sys.stderr。

如果 errorlevel 为 0，则当使用 TarFile.extract() 时会忽略所有错误。 无论何种情况，当启用调试时它们都将被显示为调试输出的错误消息。 如果为 1，则所有 fatal 错误会被作为 OSError 异常被引发。 如果为 2，则所有 non-fatal 错误也会被作为 TarError 异常被引发。

encoding 和 errors 参数定义了读取或写入归档所使用的字符编码格式以及要如何处理转换错误。 默认设置将适用于大多数用户。 要深入了解详情可参阅 Unicode 问题 小节。

可选的 pax_headers 参数是字符串的字典，如果 format 为 PAX_FORMAT 它将被作为 pax 全局标头被添加。

在 3.2 版更改: 使用 'surrogateescape' 作为 errors 参数的默认值。

在 3.5 版更改: 添加了 'x' (仅创建) 模式。

在 3.6 版更改: name 形参接受一个 path-like object。

classmethod TarFile.open(...)¶

作为替代的构造器。 tarfile.open() 函数实际上是这个类方法的快捷方式。

TarFile.getmember(name)¶

返回成员 name 的 TarInfo 对象。 如果 name 在归档中找不到，则会引发 KeyError。

注解

如果一个成员在归档中出现超过一次，它的最后一次出现会被视为是最新的版本。

TarFile.getmembers()¶

以 TarInfo 对象列表的形式返回归档的成员。 列表的顺序与归档中成员的顺序一致。

TarFile.getnames()¶

以名称列表的形式返回成员。 它的顺序与 getmembers() 所返回列表的顺序一致。

TarFile.list(verbose=True, *, members=None)¶

将内容清单打印到 sys.stdout。 如果 verbose 为 False，则将只打印成员名称。 如果为 True，则输出将类似于 ls -l 的输出效果。 如果给定了可选的 members，它必须为 getmembers() 所返回的列表的一个子集。

在 3.5 版更改: 添加了 members 形参。

TarFile.next()¶

当 TarFile 被打开用于读取时，以 TarInfo 对象的形式返回归档的下一个成员。 如果不再有可用对象则返回 None。

TarFile.extractall(path=".", members=None, *, numeric_owner=False)¶

将归档中的所有成员提取到当前工作目录或 path 目录。 如果给定了可选的 members，则它必须为 getmembers() 所返回的列表的一个子集。 字典信息例如所有者、修改时间和权限会在所有成员提取完毕后被设置。 这样做是为了避免两个问题：目录的修改时间会在每当在其中创建文件时被重置。 并且如果目录的权限不允许写入，提取文件到目录的操作将失败。

如果 numeric_owner 为 True，则将使用来自 tarfile 的 uid 和 gid 数值来设置被提取文件的所有者/用户组。 在其他情况下，则会使用来自 tarfile 的名称值。

警告

绝不要未经预先检验就从不可靠的源中提取归档文件。 这样有可能在 path 之外创建文件，例如某些成员具有以 "/" 开始的绝对路径文件名或带有两个点号 ".." 的文件名。

在 3.5 版更改: 添加了 numeric_owner 形参。

在 3.6 版更改: path 形参接受一个 path-like object。

TarFile.extract(member, path="", set_attrs=True, *, numeric_owner=False)¶

从归档中提取出一个成员放入当前工作目录，将使用其完整名称。 成员的文件信息会尽可能精确地被提取。 member 可以是一个文件名或 TarInfo 对象。 你可以使用 path 指定一个不同的目录。 path 可以是一个 path-like object。 将会设置文件属性 (owner, mtime, mode) 除非 set_attrs 为假值。

如果 numeric_owner 为 True，则将使用来自 tarfile 的 uid 和 gid 数值来设置被提取文件的所有者/用户组。 在其他情况下，则会使用来自 tarfile 的名称值。

注解

extract() 方法不会处理某些提取问题。 在大多数情况下你应当考虑使用 extractall() 方法。

警告

参看 extractall() 的警告信息。

在 3.2 版更改: 添加了 set_attrs 形参。

在 3.5 版更改: 添加了 numeric_owner 形参。

在 3.6 版更改: path 形参接受一个 path-like object。

TarFile.extractfile(member)¶

将归档中的一个成员提取为文件对象。 member 可以是一个文件名或 TarInfo 对象。 如果 member 是一个常规文件或链接，则会返回一个 io.BufferedReader 对象。 在其他情况下将返回 None。

在 3.3 版更改: 返回一个 io.BufferedReader 对象。

TarFile.add(name, arcname=None, recursive=True, *, filter=None)¶

将文件 name 添加到归档。 name 可以为任意类型的文件（目录、fifo、符号链接等等）。 如果给出 arcname 则它将为归档中的文件指定一个替代名称。 默认情况下会递归地添加目录。 这可以通过将 recursive 设为 False 来避免。 递归操作会按排序顺序添加条目。 如果给定了 filter，它应当为一个接受 TarInfo 对象并返回已修改 TarInfo 对象的函数。 如果它返回 None 则 TarInfo 对象将从归档中被排除。 具体示例参见 例子。

在 3.2 版更改: 添加了 filter 形参。

在 3.7 版更改: 递归操作按排序顺序添加条目。

TarFile.addfile(tarinfo, fileobj=None)¶

将 TarInfo 对象 tarinfo 添加到归档。 如果给定了 fileobj，它应当是一个 binary file，并会从中读取 tarinfo.size 个字节添加到归档。 你可以直接创建 TarInfo 对象，或是通过使用 gettarinfo()。

TarFile.gettarinfo(name=None, arcname=None, fileobj=None)¶

基于 os.stat() 的结果或者现有文件的相同数据创建一个 TarInfo。 文件或者是命名为 name，或者是使用文件描述符指定为一个 file objectfileobj。 name 可以是一个 path-like object。 如果给定了 arcname，则它将为归档中的文件指定一个替代名称，在其他情况下，名称将从 fileobj 的 name 属性或 name 参数获取。 名称应当是一个文本字符串。

你可以在使用 addfile() 添加 TarInfo 的某些属性之前修改它们。 如果文件对象不是从文件开头进行定位的普通文件对象，size 之类的属性就可能需要修改。 例如 GzipFile 之类的文件就属于这种情况。 name 也可以被修改，在这种情况下 arcname 可以是一个占位字符串。

在 3.6 版更改: name 形参接受一个 path-like object。

TarFile.close()¶

关闭 TarFile。 在写入模式下，会向归档添加两个表示结束的零数据块。

TarFile.pax_headers¶

一个包含 pax 全局标头的键值对的字典。

TarInfo 对象¶

TarInfo 对象代表 TarFile 中的一个文件。 除了会存储所有必要的文件属性（例如文件类型、大小、时间、权限、所有者等），它还提供了一些确定文件类型的有用方法。 此对象 并不 包含文件数据本身。

TarInfo 对象可通过 TarFile 的方法 getmember(), getmembers() 和 gettarinfo() 返回。

class tarfile.TarInfo(name="")¶

创建一个 TarInfo 对象。

classmethod TarInfo.frombuf(buf, encoding, errors)¶

基于字符串缓冲区 buf 创建并返回一个 TarInfo 对象。

如果缓冲区无效则会引发 HeaderError。

classmethod TarInfo.fromtarfile(tarfile)¶

从 TarFile 对象 tarfile 读取下一个成员并将其作为 TarInfo 对象返回。

TarInfo.tobuf(format=DEFAULT_FORMAT, encoding=ENCODING, errors='surrogateescape')¶

基于 TarInfo 对象创建一个字符串缓冲区。 有关参数的信息请参见 TarFile 类的构造器。

在 3.2 版更改: 使用 'surrogateescape' 作为 errors 参数的默认值。

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

TarInfo.name¶

归档成员的名称。

TarInfo.size¶

以字节表示的大小。

TarInfo.mtime¶

上次修改的时间。

TarInfo.mode¶

权限位。

TarInfo.type¶

文件类型。 type 通常为以下常量之一: REGTYPE, AREGTYPE, LNKTYPE, SYMTYPE, DIRTYPE, FIFOTYPE, CONTTYPE, CHRTYPE, BLKTYPE, GNUTYPE_SPARSE。 要更方便地确定一个 TarInfo 对象的类型，请使用下述的 is*() 方法。

TarInfo.linkname¶

目标文件名的名称，该属性仅在类型为 LNKTYPE 和 SYMTYPE 的 TarInfo 对象中存在。

TarInfo.uid¶

最初保存该成员的用户的用户 ID。

TarInfo.gid¶

最初保存该成员的用户的分组 ID。

TarInfo.uname¶

用户名。

TarInfo.gname¶

分组名。

TarInfo.pax_headers¶

一个包含所关联的 pax 扩展标头的键值对的字典。

TarInfo 对象还提供了一些便捷查询方法:

TarInfo.isfile()¶

如果 Tarinfo 对象为普通文件则返回 True。

TarInfo.isreg()¶

与 isfile() 相同。

TarInfo.isdir()¶

如果为目录则返回 True。

TarInfo.issym()¶

如果为符号链接则返回 True。

TarInfo.islnk()¶

如果为硬链接则返回 True。

TarInfo.ischr()¶

如果为字符设备则返回 True。

TarInfo.isblk()¶

如果为块设备则返回 True。

TarInfo.isfifo()¶

如果为 FIFO 则返回 True。.

TarInfo.isdev()¶

如果为字符设备、块设备或 FIFO 之一则返回 True。

命令行界面¶

tarfile 模块提供了简单的命令行接口以便与 tar 归档进行交互。

如果你想要创建一个新的 tar 归档，请在 -c 选项后指定其名称然后列出应当被包含的文件名:

$python -m tarfile -c monty.tar  spam.txt eggs.txt

传入一个字典也是可接受的:

$ python -m tarfile -c monty.tar life-of-brian_1979/

如果你想要将一个 tar 归档提取到指定的目录，请使用 -e 选项:

$ python -m tarfile -e monty.tar

你也可以通过传入目录名称将一个 tar 归档提取到不同的目录:

$ python -m tarfile -e monty.tar  other-dir/

要获取一个 tar 归档中文件的列表，请使用 -l 选项:

$ python -m tarfile -l monty.tar

例子¶

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

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

如何通过 TarFile.extractall() 使用生成器函数而非列表来提取一个 tar 归档的子集:

importos
importtarfile
defpy_files(members):
fortarinfoinmembers:
ifos.path.splitext(tarinfo.name)[1]==".py":
yieldtarinfo
tar=tarfile.open("sample.tar.gz")
tar.extractall(members=py_files(tar))
tar.close()

如何基于一个文件名列表创建未压缩的 tar 归档:

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

使用 with 语句的同一个示例:

importtarfile
withtarfile.open("sample.tar","w")astar:
fornamein["foo","bar","quux"]:
tar.add(name)

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

importtarfile
tar=tarfile.open("sample.tar.gz","r:gz")
fortarinfointar:
print(tarinfo.name,"is",tarinfo.size,"bytes in size and is ",end="")
iftarinfo.isreg():
print("a regular file.")
eliftarinfo.isdir():
print("a directory.")
else:
print("something else.")
tar.close()

如何创建一个归档并使用 TarFile.add() 中的 filter 形参来重置用户信息:

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