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'。以下是模式组合的完整列表：
模式 | 行动 |
|---|---|
'r'?or?'r:*' | 透明压缩打开（推荐）。 |
'r:' | 打开阅读专门没有压缩。 |
'r:gz' | 用gzip压缩打开。 |
'r:bz2' | 用bzip2压缩打开阅读。 |
'r:xz' | 打开阅读lzma压缩。 |
'x'?要么?'x:' | 创建一个tar文件而不压缩。FileExistsError如果它已经存在，则引发异常。 |
'x:gz' | 用gzip压缩创建一个tar文件。FileExistsError如果它已经存在，则引发异常。 |
'x:bz2' | 用bzip2压缩创建一个tar文件。FileExistsError如果它已经存在，则引发异常。 |
'x:xz' | 用lzma压缩创建一个tar文件。FileExistsError如果它已经存在，则引发异常。 |
'a'?or?'a:' | 打开后不需要压缩。如果该文件不存在，则会创建该文件。 |
'w'?or?'w:' | 打开未压缩的文字。 |
'w:gz' | 打开gzip压缩文字。 |
'w:bz2' | 打开bzip2压缩文字。 |
'w:xz' | 打开lzma压缩文字。 |
请注意'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
模式 | 行动 |
|---|---|
'r|*' | 透明压缩打开一个tar块流供阅读。 |
'r|' | 打开一个未压缩的焦油块流供阅读。 |
'r|gz' | 打开一个gzip压缩流供阅读。 |
'r|bz2' | 打开一个bzip2压缩流供阅读。 |
'r|xz' | 打开一个lzma压缩流供阅读。 |
'w|' | 写一个未压缩的流。 |
'w|gz' | 打开gzip压缩流进行写入。 |
'w|bz2' | 打开一个bzip2压缩流进行写入。 |
'w|xz' | 打开一个lzma压缩流进行写入。 |
类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'确保名称信息不被忽视。
本文档系腾讯云开发者社区成员共同维护，如有问题请联系 cloudcommunity@tencent.com
