tarfile --- 讀寫tar歸檔文件?

TarFile 對(duì)象?

TarFile 對(duì)象提供了一個(gè) tar 歸檔的接口。 一個(gè) tar 歸檔就是數(shù)據(jù)塊的序列。 一個(gè)歸檔成員（被保存文件）是由一個(gè)標(biāo)頭塊加多個(gè)數(shù)據(jù)塊組成的。 一個(gè)文件可以在一個(gè) tar 歸檔中多次被保存。 每個(gè)歸檔成員都由一個(gè) TarInfo 對(duì)象來(lái)代表，詳情參見(jiàn) TarInfo 對(duì)象。

TarFile 對(duì)象可在 with 語(yǔ)句中作為上下文管理器使用。 當(dāng)語(yǔ)句塊結(jié)束時(shí)它將自動(dòng)被關(guān)閉。 請(qǐng)注意在發(fā)生異常事件時(shí)被打開(kāi)用于寫入的歸檔將不會(huì)被終結(jié)；只有內(nèi)部使用的文件對(duì)象將被關(guān)閉。 相關(guān)用例請(qǐng)參見(jiàn) 例子。

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

下列所有參數(shù)都是可選項(xiàng)并且也可作為實(shí)例屬性來(lái)訪問(wèn)。

name 是歸檔的路徑名稱。 name 可以是一個(gè) path-like object。 如果給定了 fileobj 則它可以被省略。 在此情況下，如果對(duì)象的 name 屬性存在則它會(huì)被使用。

mode 可以為 'r' 表示從現(xiàn)有歸檔讀取，'a' 表示將數(shù)據(jù)追加到現(xiàn)有文件，'w' 表示創(chuàng)建新文件覆蓋現(xiàn)有文件，或者 'x' 表示僅在文件不存在時(shí)創(chuàng)建新文件。

如果給定了 fileobj，它會(huì)被用于讀取或?qū)懭霐?shù)據(jù)。 如果可以被確定，則 mode 會(huì)被 fileobj 的模式所覆蓋。 fileobj 的使用將從位置 0 開(kāi)始。

備注

當(dāng) TarFile 被關(guān)閉時(shí)，fileobj 不會(huì)被關(guān)閉。

format 控制用于寫入的歸檔格式。 它必須為在模塊層級(jí)定義的常量 USTAR_FORMAT, GNU_FORMAT 或 PAX_FORMAT 中的一個(gè)。 當(dāng)讀取時(shí)，格式將被自動(dòng)檢測(cè)，即使單個(gè)歸檔中存在不同的格式。

tarinfo 參數(shù)可以被用來(lái)將默認(rèn)的 TarInfo 類替換為另一個(gè)。

如果 dereference 為 False，則會(huì)將符號(hào)鏈接和硬鏈接添加到歸檔中。 如果為 True，則會(huì)將目標(biāo)文件的內(nèi)容添加到歸檔中。 在不支持符號(hào)鏈接的系統(tǒng)上參數(shù)將不起作用。

如果 ignore_zeros 為 False，則會(huì)將空的數(shù)據(jù)塊當(dāng)作歸檔的末尾來(lái)處理。 如果為 True，則會(huì)跳過(guò)空的（和無(wú)效的）數(shù)據(jù)塊并嘗試獲取盡可能多的成員。 此參數(shù)僅適用于讀取拼接的或損壞的歸檔。

debug 可設(shè)為從 0 (無(wú)調(diào)試消息) 到 3 (全部調(diào)試消息)。 消息會(huì)被寫入到 sys.stderr。

如果 errorlevel 為 0，則當(dāng)使用 TarFile.extract() 時(shí)會(huì)忽略所有錯(cuò)誤。 無(wú)論何種情況，當(dāng)啟用調(diào)試時(shí)它們都將被顯示為調(diào)試輸出的錯(cuò)誤消息。 如果為 1，則所有 fatal 錯(cuò)誤會(huì)被作為 OSError 異常被引發(fā)。 如果為 2，則所有 non-fatal 錯(cuò)誤也會(huì)被作為 TarError 異常被引發(fā)。

encoding 和 errors 參數(shù)定義了讀取或?qū)懭霘w檔所使用的字符編碼格式以及要如何處理轉(zhuǎn)換錯(cuò)誤。 默認(rèn)設(shè)置將適用于大多數(shù)用戶。 要深入了解詳情可參閱 Unicode 問(wèn)題 小節(jié)。

可選的 pax_headers 參數(shù)是字符串的字典，如果 format 為 PAX_FORMAT 它將被作為 pax 全局標(biāo)頭被添加。

在 3.2 版更改: 使用 'surrogateescape' 作為 errors 參數(shù)的默認(rèn)值。

在 3.5 版更改: 添加了 'x' (單獨(dú)創(chuàng)建) 模式。

在 3.6 版更改: name 形參接受一個(gè) path-like object。

classmethod TarFile.open(...)?

作為替代的構(gòu)造器。 tarfile.open() 函數(shù)實(shí)際上是這個(gè)類方法的快捷方式。

TarFile.getmember(name)?

返回成員 name 的 TarInfo 對(duì)象。 如果 name 在歸檔中找不到，則會(huì)引發(fā) KeyError。

備注

如果一個(gè)成員在歸檔中出現(xiàn)超過(guò)一次，它的最后一次出現(xiàn)會(huì)被視為是最新的版本。

TarFile.getmembers()?

以 TarInfo 對(duì)象列表的形式返回歸檔的成員。 列表的順序與歸檔中成員的順序一致。

TarFile.getnames()?

以名稱列表的形式返回成員。 它的順序與 getmembers() 所返回列表的順序一致。

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

將內(nèi)容清單打印到 sys.stdout。 如果 verbose 為 False，則將只打印成員名稱。 如果為 True，則輸出將類似于 ls -l 的輸出效果。 如果給定了可選的 members，它必須為 getmembers() 所返回的列表的一個(gè)子集。

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

TarFile.next()?

當(dāng) TarFile 被打開(kāi)用于讀取時(shí)，以 TarInfo 對(duì)象的形式返回歸檔的下一個(gè)成員。 如果不再有可用對(duì)象則返回 None。

TarFile.extractall(path='.', members=None, *, numeric_owner=False)?

將歸檔中的所有成員提取到當(dāng)前工作目錄或 path 目錄。 如果給定了可選的 members，則它必須為 getmembers() 所返回的列表的一個(gè)子集。 字典信息例如所有者、修改時(shí)間和權(quán)限會(huì)在所有成員提取完畢后被設(shè)置。 這樣做是為了避免兩個(gè)問(wèn)題：目錄的修改時(shí)間會(huì)在每當(dāng)在其中創(chuàng)建文件時(shí)被重置。 并且如果目錄的權(quán)限不允許寫入，提取文件到目錄的操作將失敗。

如果 numeric_owner 為 True，則將使用來(lái)自 tarfile 的 uid 和 gid 數(shù)值來(lái)設(shè)置被提取文件的所有者/用戶組。 在其他情況下，則會(huì)使用來(lái)自 tarfile 的名稱值。

警告

絕不要未經(jīng)預(yù)先檢驗(yàn)就從不可靠的源中提取歸檔文件。 這樣有可能在 path 之外創(chuàng)建文件，例如某些成員具有以 "/" 開(kāi)始的絕對(duì)路徑文件名或帶有兩個(gè)點(diǎn)號(hào) ".." 的文件名。

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

在 3.6 版更改: path 形參接受一個(gè) path-like object。

TarFile.extract(member, path='', set_attrs=True, *, numeric_owner=False)?

從歸檔中提取出一個(gè)成員放入當(dāng)前工作目錄，將使用其完整名稱。 成員的文件信息會(huì)盡可能精確地被提取。 member 可以是一個(gè)文件名或 TarInfo 對(duì)象。 你可以使用 path 指定一個(gè)不同的目錄。 path 可以是一個(gè) path-like object。 將會(huì)設(shè)置文件屬性 (owner, mtime, mode) 除非 set_attrs 為假值。

如果 numeric_owner 為 True，則將使用來(lái)自 tarfile 的 uid 和 gid 數(shù)值來(lái)設(shè)置被提取文件的所有者/用戶組。 在其他情況下，則會(huì)使用來(lái)自 tarfile 的名稱值。

備注

extract() 方法不會(huì)處理某些提取問(wèn)題。 在大多數(shù)情況下你應(yīng)當(dāng)考慮使用 extractall() 方法。

警告

查看 extractall() 的警告信息。

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

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

在 3.6 版更改: path 形參接受一個(gè) path-like object。

TarFile.extractfile(member)?

將歸檔中的一個(gè)成員提取為文件對(duì)象。 member 可以是一個(gè)文件名或 TarInfo 對(duì)象。 如果 member 是一個(gè)常規(guī)文件或鏈接，則會(huì)返回一個(gè) io.BufferedReader 對(duì)象。 對(duì)于所有其他現(xiàn)有成員，則都將返回 None。 如果 member 未在歸檔中出現(xiàn)，則會(huì)引發(fā) KeyError。

在 3.3 版更改: 返回一個(gè) io.BufferedReader 對(duì)象。

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

將文件 name 添加到歸檔。 name 可以為任意類型的文件（目錄、fifo、符號(hào)鏈接等等）。 如果給出 arcname 則它將為歸檔中的文件指定一個(gè)替代名稱。 默認(rèn)情況下會(huì)遞歸地添加目錄。 這可以通過(guò)將 recursive 設(shè)為 False 來(lái)避免。 遞歸操作會(huì)按排序順序添加條目。 如果給定了 filter，它應(yīng)當(dāng)為一個(gè)接受 TarInfo 對(duì)象并返回已修改 TarInfo 對(duì)象的函數(shù)。 如果它返回 None 則 TarInfo 對(duì)象將從歸檔中被排除。 具體示例參見(jiàn) 例子。

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

在 3.7 版更改: 遞歸操作按排序順序添加條目。

TarFile.addfile(tarinfo, fileobj=None)?

將 TarInfo 對(duì)象 tarinfo 添加到歸檔。 如果給定了 fileobj，它應(yīng)當(dāng)是一個(gè) binary file，并會(huì)從中讀取 tarinfo.size 個(gè)字節(jié)添加到歸檔。 你可以直接創(chuàng)建 TarInfo 對(duì)象，或是使用 gettarinfo() 來(lái)創(chuàng)建。

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

基于 os.stat() 的結(jié)果或者現(xiàn)有文件的相同數(shù)據(jù)創(chuàng)建一個(gè) TarInfo。 文件或者是命名為 name，或者是使用文件描述符指定為一個(gè) file object fileobj。 name 可以是一個(gè) path-like object。 如果給定了 arcname，則它將為歸檔中的文件指定一個(gè)替代名稱，在其他情況下，名稱將從 fileobj 的 name 屬性或 name 參數(shù)獲取。 名稱應(yīng)當(dāng)是一個(gè)文本字符串。

你可以在使用 addfile() 添加 TarInfo 的某些屬性之前修改它們。 如果文件對(duì)象不是從文件開(kāi)頭進(jìn)行定位的普通文件對(duì)象，size 之類的屬性就可能需要修改。 例如 GzipFile 之類的文件就屬于這種情況。 name 也可以被修改，在這種情況下 arcname 可以是一個(gè)占位字符串。

在 3.6 版更改: name 形參接受一個(gè) path-like object。

TarFile.close()?

關(guān)閉 TarFile。 在寫入模式下，會(huì)向歸檔添加兩個(gè)表示結(jié)束的零數(shù)據(jù)塊。

TarFile.pax_headers?

一個(gè)包含 pax 全局標(biāo)頭的鍵值對(duì)的字典。

TarInfo 對(duì)象?

TarInfo 對(duì)象代表 TarFile 中的一個(gè)文件。 除了會(huì)存儲(chǔ)所有必要的文件屬性（例如文件類型、大小、時(shí)間、權(quán)限、所有者等），它還提供了一些確定文件類型的有用方法。 此對(duì)象 并不 包含文件數(shù)據(jù)本身。

TarInfo 對(duì)象可通過(guò) TarFile 的方法 getmember(), getmembers() 和 gettarinfo() 返回。

class tarfile.TarInfo(name='')?

創(chuàng)建一個(gè) TarInfo 對(duì)象。

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

基于字符串緩沖區(qū) buf 創(chuàng)建并返回一個(gè) TarInfo 對(duì)象。

如果緩沖區(qū)無(wú)效則會(huì)引發(fā) HeaderError。

classmethod TarInfo.fromtarfile(tarfile)?

從 TarFile 對(duì)象 tarfile 讀取下一個(gè)成員并將其作為 TarInfo 對(duì)象返回。

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

基于 TarInfo 對(duì)象創(chuàng)建一個(gè)字符串緩沖區(qū)。 有關(guān)參數(shù)的信息請(qǐng)參見(jiàn) TarFile 類的構(gòu)造器。

在 3.2 版更改: 使用 'surrogateescape' 作為 errors 參數(shù)的默認(rèn)值。

TarInfo 對(duì)象具有以下公有數(shù)據(jù)屬性:

TarInfo.name?

歸檔成員的名稱。

TarInfo.size?

以字節(jié)表示的大小。

TarInfo.mtime?

上次修改的時(shí)間。

TarInfo.mode?

權(quán)限位。

TarInfo.type?

文件類型。 type 通常為以下常量之一: REGTYPE, AREGTYPE, LNKTYPE, SYMTYPE, DIRTYPE, FIFOTYPE, CONTTYPE, CHRTYPE, BLKTYPE, GNUTYPE_SPARSE。 要更方便地確定一個(gè) TarInfo 對(duì)象的類型，請(qǐng)使用下述的 is*() 方法。

TarInfo.linkname?

目標(biāo)文件名的名稱，該屬性僅在類型為 LNKTYPE 和 SYMTYPE 的 TarInfo 對(duì)象中存在。

TarInfo.uid?

最初保存該成員的用戶的用戶 ID。

TarInfo.gid?

最初保存該成員的用戶的分組 ID。

TarInfo.uname?

用戶名。

TarInfo.gname?

分組名。

TarInfo.pax_headers?

一個(gè)包含所關(guān)聯(lián)的 pax 擴(kuò)展標(biāo)頭的鍵值對(duì)的字典。

TarInfo 對(duì)象還提供了一些便捷查詢方法:

TarInfo.isfile()?

如果 Tarinfo 對(duì)象為普通文件則返回 True。

TarInfo.isreg()?

與 isfile() 相同。

TarInfo.isdir()?

如果為目錄則返回 True。

TarInfo.issym()?

如果為符號(hào)鏈接則返回 True。

TarInfo.islnk()?

如果為硬鏈接則返回 True。

TarInfo.ischr()?

如果為字符設(shè)備則返回 True。

TarInfo.isblk()?

如果為塊設(shè)備則返回 True。

TarInfo.isfifo()?

如果為 FIFO 則返回 True。.

TarInfo.isdev()?

如果為字符設(shè)備、塊設(shè)備或 FIFO 之一則返回 True。

命令行接口?

tarfile 模塊提供了簡(jiǎn)單的命令行接口以便與 tar 歸檔進(jìn)行交互。

如果你想要?jiǎng)?chuàng)建一個(gè)新的 tar 歸檔，請(qǐng)?jiān)?-c 選項(xiàng)后指定其名稱然后列出應(yīng)當(dāng)被包含的文件名:

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

傳入一個(gè)字典也是可接受的:

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

如果你想要將一個(gè) tar 歸檔提取到指定的目錄，請(qǐng)使用 -e 選項(xiàng):

$ python -m tarfile -e monty.tar

你也可以通過(guò)傳入目錄名稱將一個(gè) tar 歸檔提取到不同的目錄:

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

要獲取一個(gè) tar 歸檔中文件的列表，請(qǐng)使用 -l 選項(xiàng):

$ python -m tarfile -l monty.tar

例子?

如何將整個(gè) tar 歸檔提取到當(dāng)前工作目錄:

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

如何通過(guò) TarFile.extractall() 使用生成器函數(shù)而非列表來(lái)提取一個(gè) 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()

如何基于一個(gè)文件名列表創(chuàng)建未壓縮的 tar 歸檔:

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

使用 with 語(yǔ)句的同一個(gè)示例:

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

如何讀取一個(gè) 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()

如何創(chuàng)建一個(gè)歸檔并使用 TarFile.add() 中的 filter 形參來(lái)重置用戶信息:

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 格式?

通過(guò) tarfile 模塊可以創(chuàng)建三種 tar 格式:

• The POSIX.1-1988 ustar 格式 (USTAR_FORMAT)。 它支持最多 256 個(gè)字符的文件名長(zhǎng)度和最多 100 個(gè)字符的鏈接名長(zhǎng)度。 文件大小上限為 8 GiB。 這是一種老舊但廣受支持的格式。

• GNU tar 格式 (GNU_FORMAT)。 它支持長(zhǎng)文件名和鏈接名、大于 8 GiB 的文件以及稀疏文件。 它是 GNU/Linux 系統(tǒng)上的事實(shí)標(biāo)準(zhǔn)。 tarfile 完全支持針對(duì)長(zhǎng)名稱的 GNU tar 擴(kuò)展，稀疏文件支持則限制為只讀。

• POSIX.1-2001 pax 格式 (PAX_FORMAT)。 它是幾乎無(wú)限制的最靈活格式。 它支持長(zhǎng)文件名和鏈接名，大文件以及使用便捷方式存儲(chǔ)路徑名。 現(xiàn)代的 tar 實(shí)現(xiàn)，包括 GNU tar, bsdtar/libarchive 和 star，完全支持?jǐn)U展 pax 特性；某些老舊或不維護(hù)的庫(kù)可能不受支持，但應(yīng)當(dāng)會(huì)將 pax 歸檔視為廣受支持的 ustar 格式。 這是目前新建歸檔的默認(rèn)格式。

  它擴(kuò)展了現(xiàn)有的 ustar 格式，包括用于無(wú)法以其他方式存儲(chǔ)的附加標(biāo)頭。 存在兩種形式的 pax 標(biāo)頭：擴(kuò)展標(biāo)頭只影響后續(xù)的文件標(biāo)頭，全局標(biāo)頭則適用于完整歸檔并會(huì)影響所有后續(xù)的文件。 為了便于移植，在 pax 標(biāo)頭中的所有數(shù)據(jù)均以 UTF-8 編碼。

還有一些 tar 格式的其他變種，它們可以被讀取但不能被創(chuàng)建:

• 古老的 V7 格式。 這是來(lái)自 Unix 第七版的第一個(gè) tar 格式，它只存儲(chǔ)常規(guī)文件和目錄。 名稱長(zhǎng)度不能超過(guò) 100 個(gè)字符，并且沒(méi)有用戶/分組名信息。 某些歸檔在帶有非 ASCII 字符字段的情況下會(huì)產(chǎn)生計(jì)算錯(cuò)誤的標(biāo)頭校驗(yàn)和。

• SunOS tar 擴(kuò)展格式。 此格式是 POSIX.1-2001 pax 格式的一個(gè)變種，但并不保持兼容。

Unicode 問(wèn)題?

最初 tar 格式被設(shè)計(jì)用來(lái)在磁帶機(jī)上生成備份，主要關(guān)注于保存文件系統(tǒng)信息。 現(xiàn)在 tar 歸檔通常用于文件分發(fā)和在網(wǎng)絡(luò)上交換歸檔。 最初格式（它是所有其他格式的基礎(chǔ)）的一個(gè)問(wèn)題是它沒(méi)有支持不同字符編碼格式的概念。 例如，一個(gè)在 UTF-8 系統(tǒng)上創(chuàng)建的普通 tar 歸檔如果包含非 ASCII 字符則將無(wú)法在 Latin-1 系統(tǒng)上被正確讀取。 文本元數(shù)據(jù)（例如文件名，鏈接名，用戶/分組名）將變?yōu)閾p壞狀態(tài)。 不幸的是，沒(méi)有什么辦法能夠自動(dòng)檢測(cè)一個(gè)歸檔的編碼格式。 pax 格式被設(shè)計(jì)用來(lái)解決這個(gè)問(wèn)題。 它使用通用字符編碼格式 UTF-8 來(lái)存儲(chǔ)非 ASCII 元數(shù)據(jù)。

在 tarfile 中字符轉(zhuǎn)換的細(xì)節(jié)由 TarFile 類的 encoding 和 errors 關(guān)鍵字參數(shù)控制。

encoding 定義了用于歸檔中元數(shù)據(jù)的字符編碼格式。 默認(rèn)值為 sys.getfilesystemencoding() 或是回退選項(xiàng) 'ascii'。 根據(jù)歸檔是被讀取還是被寫入，元數(shù)據(jù)必須被解碼或編碼。 如果沒(méi)有正確設(shè)置 encoding，轉(zhuǎn)換可能會(huì)失敗。

errors 參數(shù)定義了不能被轉(zhuǎn)換的字符將如何處理。 可能的取值在 錯(cuò)誤處理方案 小節(jié)列出。 默認(rèn)方案為 'surrogateescape'，它也被 Python 用于文件系統(tǒng)調(diào)用，參見(jiàn) 文件名，命令行參數(shù)，以及環(huán)境變量。。

對(duì)于 PAX_FORMAT 歸檔（默認(rèn)格式），encoding 通常是不必要的，因?yàn)樗性獢?shù)據(jù)都使用 UTF-8 來(lái)存儲(chǔ)。 encoding 僅在解碼二進(jìn)制 pax 標(biāo)頭或存儲(chǔ)帶有替代字符的字符串等少數(shù)場(chǎng)景下會(huì)被使用。