tarfile

2.3版本的新功能。

源代码： Lib / tarfile.py

该tarfile模块可以读写tar档案，包括使用gzip或bz2压缩的档案。使用该zipfile模块读取或写入.zip文件，或shutil中的更高级别的函数。

一些事实和数字：

• 如果各个模块可用，则读取和写入gzip并bz2压缩归档。

• 读/写支持POSIX.1-1988（ustar）格式。

• 对GNU tar格式的读/写支持，包括长名称和长链接扩展，对稀疏扩展的只读支持。

• 读/写支持POSIX.1-2001（pax）格式。

2.6版本中的新功能。

• 处理目录，常规文件，硬链接，符号链接，fifo，字符设备和块设备，并能够获取和恢复文件信息，如时间戳，访问权限和所有者。

版本3.3中更改：增加了对lzma压缩的支持。

tarfile.open（name = None，mode ='r'，fileobj = None，bufsize = 10240，** kwargs）

TarFile为路径名称返回一个对象。有关TarFile允许的对象和关键字参数的详细信息，请参阅TarFile对象。

模式必须是表单的字符串'filemode[:compression]'，它默认为'r'。以下是模式组合的完整列表：

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

如果指定了fileobj，那么它将用作 以二进制模式打开的名称文件对象的替代方案。它应该在位置0。

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

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

类tarfile.TarFile

阅读和编写tar档案的类。不要直接使用这个类：tarfile.open()改为使用。请参阅TarFile对象。

tarfile.is_tarfile（名字）

True如果名称是一个tar档案文件，则返回该tarfile 模块可以读取的内容。

该tarfile模块定义了以下例外情况：

异常tarfile.TarError

所有tarfile例外的基类。

异常tarfile.ReadError

当tar档案被打开时引发，或者不能被tarfile模块处理 或者以某种方式无效。

异常tarfile.CompressionError

当不支持压缩方法或无法正确解码数据时引发。

异常tarfile.StreamError

针对流式TarFile 物体的典型局限性而提出。

异常tarfile.ExtractError

在使用时引发非致命错误TarFile.extract()，但仅 在使用时引发。TarFile.errorlevel== 2

异常tarfile.HeaderError

TarInfo.frombuf()如果获取的缓冲区无效，则会引发此问题。

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

tarfile.ENCODING

默认字符编码：'utf-8'在Windows上，sys.getfilesystemencoding()否则返回值 。

以下每个常量都定义了tarfile模块能够创建的tar归档格式 。有关详细信息，请参阅支持的焦油格式部分

tarfile.USTAR_FORMAT

POSIX.1-1988（ustar）格式。

tarfile.GNU_FORMAT

GNU tar格式。

tarfile.PAX_FORMAT

POSIX.1-2001（pax）格式。

tarfile.DEFAULT_FORMAT

创建档案的默认格式。这是目前GNU_FORMAT。

另请参阅 模 zipfilezipfile标准模块的文档。归档操作由标准shutil模块提供的更高级归档工具的文档。GNU tar手册，基本Tar格式tar归档文件的文档，包括GNU tar扩展。

TarFile对象

该TarFile对象提供了一个tar档案的接口。tar档案是一系列块。一个档案成员（一个存储文件）由一个头块和数据块组成。可以将文件存储在tar归档文件中多次。每个存档成员都由一个TarInfo 对象表示，有关详细信息，请参阅TarInfo对象。

一个TarFile对象可以在with 语句中用作上下文管理器。块完成后它会自动关闭。请注意，如果发生例外情况，开放撰写的档案将不会最终确定; 只有内部使用的文件对象将被关闭。有关用例，请参阅 示例部分。

3.2版新增功能：增加了对上下文管理协议的支持。

类tarfile.TarFile（名=无，模式= 'R'，FileObj文件=无，格式= DEFAULT_FORMAT，tarinfo = TarInfo，解除引用=假，ignore_zeros =假，编码= ENCODING，误差= 'surrogateescape'，pax_headers =无，调试= 0，errorlevel = 0）

以下所有参数都是可选的，并且可以作为实例属性来访问。

name是存档的路径名。名称可能是一个类似于路径的对象。如果给出fileobj，它可以被忽略。在这种情况下，如果文件对象name存在，则使用该文件对象的属性。

模式是'r'从现有存档读取'a'数据，将数据附加到现有文件，'w'创建覆盖现有文件的新文件，或'x'仅在尚不存在的情况下创建新文件。

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

注意

关闭时fileobj未TarFile关闭。

格式控制存档格式。它必须是常量之一 USTAR_FORMAT，GNU_FORMAT或者PAX_FORMAT是在模块级定义的。

该tarinfo参数可以用来替换缺省TarInfo使用不同的一类。

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

如果ignore_zeros是False，则将空块视为归档的结尾。如果是这样True，跳过空（和无效）块，尽量争取尽可能多的成员。这仅用于阅读级联或损坏的档案。

调试可以设置从0（无调试消息）到3（所有调试消息）。消息被写入sys.stderr。

如果错误级别是0，则使用时将忽略所有错误TarFile.extract()。不过，在调试启用时，它们在调试输出中显示为错误消息。如果1所有致命错误都作为OSError 例外提出。如果2所有非致命错误都作为TarError 例外提出。

该编码和错误参数定义用于读取或写入档案，以及如何转换错误将要处理的字符编码。默认设置适用于大多数用户。有关详细信息，请参阅Unicode问题部分。

所述pax_headers参数是将要添加作为PAX全局头如果串的一个可选的字典的格式是PAX_FORMAT。

在3.2版本中更改：使用'surrogateescape'作为默认的错误说法。

改变在3.5版本：将'x'加入（独家创作）模式。

改变在3.6版本：该名称参数接受路径状物体。

classmethodTarFile.open（...）

替代构造函数。这个tarfile.open()函数实际上是这个classmethod的一个捷径。

TarFile.getmember（名字）

返回一个TarInfo成员名称的对象。如果在存档中找不到名称，KeyError则会提出。

注意

如果一个成员在存档中多次出现，则认为其最后一次出现是最新的版本。

TarFile.getmembers（）

将档案成员作为TarInfo对象列表返回。该列表与归档中的成员具有相同的顺序。

TarFile.getnames（）

返回成员名单。它与返回的列表具有相同的顺序getmembers()。

TarFile.list（verbose = True，*，members = None）

打印目录到sys.stdout。如果详细是False，则仅打印成员的名称。如果是True，则产生与ls -l类似的输出。如果给出可选成员，它必须是返回列表的子集getmembers()。

版本3.5中已更改：添加了成员参数。

TarFile.next（）

TarInfo当TarFile打开阅读时，将档案的下一个成员作为对象 返回。None如果没有更多可用，则返回。

TarFile.extractall（path =“。”，members = None，*，numeric_owner = False）

将存档中的所有成员提取到当前工作目录或目录路径。如果给出可选成员，它必须是返回列表的子集getmembers()。在提取所有成员之后设置所有者，修改时间和权限等目录信息。这样做是为了解决两个问题：每次在其中创建文件时，都会重置目录的修改时间。而且，如果一个目录的权限不允许写入，解压文件将失败。

如果numeric_owner是True，则tarfile中的uid和gid数字用于设置提取文件的所有者/组。否则，使用tarfile中的命名值。

警告

切勿在未事先检查的情况下从不受信任的来源提取档案。有可能文件是在路径之外创建的，例如具有"/"以两个点开头的绝对文件名或具有两个点的文件名的成员".."。

版本3.5中已更改：添加了numeric_owner参数。

改变在3.6版本：该路径参数接受路径状物体。

TarFile.extract（member，path =“”，set_attrs = True，*，numeric_owner = False）

使用其全名将存档中的成员提取到当前工作目录。其文件信息尽可能准确地提取。成员 可能是文件名或TarInfo对象。您可以使用路径指定不同的目录。路径可能是一个类似于路径的对象。文件属性（owner，mtime，mode）被设置，除非set_attrs为false。

如果numeric_owner是True，则tarfile中的uid和gid数字用于设置提取文件的所有者/组。否则，使用tarfile中的命名值。

注意

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

警告

请参阅警告extractall()。

版本3.2中已更改：添加了set_attrs参数。

版本3.5中已更改：添加了numeric_owner参数。

改变在3.6版本：该路径参数接受路径状物体。

TarFile.extractfile（成员）

从存档中提取成员作为文件对象。成员可能是文件名或TarInfo对象。如果成员是常规文件或链接，io.BufferedReader则返回一个 对象。否则，None返回。

版本3.3中更改：返回一个io.BufferedReader对象。

TarFile.add（name，arcname = None，recursive = True，*，filter = None）

将文件名添加到存档。名称可以是任何类型的文件（目录，fifo，符号链接等）。如果给定，则arcname为档案中的文件指定替代名称。目录默认递归添​​加。这可以通过设置递归来 避免False。递归按排序顺序添加条目。如果给出了过滤器，它应该是一个接受TarInfo对象参数并返回已更改TarInfo对象的函数。如果它返回，则 None该TarInfo对象将从档案中排除。见实施例中的示例。

在版本3.2中更改：添加了过滤器参数。

在版本3.7中更改：递归按排序顺序添加条目。

TarFile.addfile（tarinfo，fileobj = None）

将TarInfo对象tarinfo添加到存档。如果给出fileobj，它应该是一个二进制文件，并 tarinfo.size从中读取字节并将其添加到存档中。您可以TarInfo直接创建对象，也可以使用gettarinfo()。

TarFile.gettarinfo（name = None，arcname = None，fileobj = None）

根据现有文件TarInfo的结果os.stat()或等效项创建一个对象。该文件可以按名称命名，也可以用文件描述符 指定为文件对象 fileobj。 名称可能是一个类似于路径的对象。如果给定，arcname为档案中的文件指定替代名称，否则，该名称取自fileobj的 name属性或名称参数。该名称应该是一个文本字符串。

您可以TarInfo在添加它之前修改其中的一些属性addfile()。如果文件对象不是位于文件开头的普通文件对象，则size可能需要修改等属性。这是对象的情况，例如GzipFile。的name也可以被修饰，在这种情况下arcname 可能是一个虚设字符串。

改变在3.6版本：该名称参数接受路径状物体。

TarFile.close（）

关闭TarFile。在写入模式下，两个完成零块被附加到存档。

TarFile.pax_headers

包含pax全局标题的键值对的字典。

TarInfo对象

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

TarInfo对象由TarFile方法 返回getmember()，getmembers()并且gettarinfo()。

classtarfile.TarInfo（name =“”）

创建一个TarInfo对象。

classmethodTarInfo.frombuf（buf，encoding，errors）

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

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

classmethodTarInfo.fromtarfile（tarfile）

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

TarInfo.tobuf（format = DEFAULT_FORMAT，encoding = ENCODING，errors ='surrogateescape'）

从一个TarInfo对象创建一个字符串缓冲区。有关参数的信息，请参阅TarFile该类的构造函数。

在3.2版本中更改：使用'surrogateescape'作为默认的错误说法。

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

TarInfo.name

档案成员的名称。

TarInfo.size

字节大小。

TarInfo.mtime

上次修改时间。

TarInfo.mode

权限位。

TarInfo.type

文件类型。 类型通常是这些常量之一：REGTYPE， AREGTYPE，LNKTYPE，SYMTYPE，DIRTYPE，FIFOTYPE，CONTTYPE，CHRTYPE，BLKTYPE， GNUTYPE_SPARSE。要TarInfo更方便地确定对象的类型，请使用is*()下面的方法。

TarInfo.linkname

目标文件名称的名称，它仅存TarInfo在于类型LNKTYPE和对象中SYMTYPE。

TarInfo.uid

最初存储此成员的用户的用户标识。

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。

命令行界面

3.4版新增功能

该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

命令行选项

-l<tarfile>--list<tarfile>

列出tarfile中的文件。

-c<tarfile> <source1> ... <sourceN>--create<tarfile> <source1> ... <sourceN>

从源文件创建tarfile。

-e<tarfile> [<output_dir>]--extract<tarfile> [<output_dir>]

如果未指定output_dir，则将tarfile解压缩到当前目录中。

-t<tarfile>--test<tarfile>

测试tarfile是否有效。

-v,--verbose

详细输出。

示例

如何提取整个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", end="")
    if tarinfo.isreg():
        print("a regular file.")
    elif tarinfo.isdir():
        print("a directory.")
    else:
        print("something else.")
tar.close()

如何使用以下过滤器 参数创建归档并重置用户信息TarFile.add()：

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()

支持的tar格式

有三种可以使用该tarfile模块创建的tar格式：

• POSIX.1-1988 ustar格式（USTAR_FORMAT）。它支持的文件名长度最多为256个字符，链接名称最多为100个字符。最大文件大小为8千兆字节。这是一个古老而有限但广泛支持的格式。

• GNU tar格式（GNU_FORMAT）。它支持长文件名和链接名称，大于8千兆字节的文件和稀疏文件。它是GNU / Linux系统上的事实标准。tarfile完全支持长名称的GNU tar扩展，稀疏文件支持是只读的。

• POSIX.1-2001 pax格式（PAX_FORMAT）。它是最灵活的格式，几乎没有限制。它支持长文件名和链接名称，大文件和便携式存储路径名。但是，今天并非所有的tar实现都能够正确处理pax归档。

在PAX格式的扩展现有的ustar格式。它使用额外的头部来存储不能以其他方式存储的信息。有两种类型的pax头文件：扩展头文件只影响后续文件头文件，全局头文件对整个存档文件有效并影响所有后续文件。出于便携性原因，pax标头中的所有数据都以UTF-8编码。

还有一些可以读取但不能创建的tar格式变体：

• 古代的V7格式。这是Unix第七版的第一个tar格式，只存储常规文件和目录。名称不能超过100个字符，没有用户/组名称信息。某些档案在包含非ASCII字符的字段中错误计算标题校验和。

• SunOS tar扩展格式。这种格式是POSIX.1-2001 pax格式的变体，但不兼容。

5. Unicode问题

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

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

unicode转换的细节由类的编码和错误关键字参数控制TarFile。

编码的默认值是本地字符编码。它是从sys.getfilesystemencoding()和推导出来的sys.getdefaultencoding()。在读取模式下，编码专门用于将来自pax归档的unicode名称转换为本地字符编码中的字符串。在写入模式下，使用编码取决于所选的存档格式。如果PAX_FORMAT包含非ASCII字符的输入名称在被存储为UTF-8字符串之前需要解码。除非使用unicode对象作为输入名称，否则其他格式不使用编码。这些字符串在添加到存档之前会转换为8位字符串。

所述误差参数定义如何字符都被视为不能被转换，或从编码。可能的值在Codec Base Classes部分列出。在读取模式下，还有一个额外的方案'utf-8'，这意味着错误的字符被UTF-8表示所替代。这是默认方案。在写入模式下，错误的默认值是'strict'确保名称信息不被忽视。