tarfile --- 讀取與寫入 tar 封存檔案

原始碼：Lib/tarfile.py

tarfile 模組用於讀取與寫入 tar 封存檔案，包括使用 gzip、bz2 和 lzma 壓縮的檔案。使用 zipfile 模組來讀取或寫入 .zip 檔案，或使用 shutil 中的更高階函式。

一些事實和數據：

  • 若相對應的模組可用，則可讀取與寫入 gzip、bz2、compression.zstd 和 lzma 壓縮的封存檔。

    如果你的 CPython 副本中缺少這些選用模組 (optional modules)，請查閱你的發行者（即提供 Python 給你的人）的文件。如果你就是發行者，請參閱 可選模組的需求。

  • 支援 POSIX.1-1988 (ustar) 格式的讀取與寫入。

  • 支援 GNU tar 格式的讀取與寫入，包括 longname 和 longlink 擴充功能，以及所有 sparse 擴充功能變體的唯讀支援，包括還原稀疏檔案 (sparse files)。

  • 支援 POSIX.1-2001 (pax) 格式的讀取與寫入。

  • 處理目錄、一般檔案、硬連結 (hardlinks)、符號連結 (symbolic links)、fifos、字元裝置 (character devices) 和區塊裝置 (block devices)，並能夠取得與還原檔案資訊，如時間戳記、存取權限和擁有者。

在 3.3 版的變更: 新增對 lzma 壓縮的支援。

在 3.12 版的變更: 解壓縮封存檔時會使用篩選器 (filter)，你可以用它來限制一些意外或危險的功能，或是明確表示這些功能是你預期的，而且封存檔是完全可信任的。

在 3.14 版的變更: 將預設解壓縮篩選器設為 data，這會禁止一些危險的功能，例如指向絕對路徑或目的地之外路徑的連結。在此之前，篩選器策略等同於 fully_trusted。

在 3.14 版的變更: 新增對 Zstandard 壓縮的支援（使用 compression.zstd）。

tarfile.open(name=None, mode='r', fileobj=None, bufsize=10240, **kwargs)

回傳路徑名稱 name 的 TarFile 物件。關於 TarFile 物件與允許的關鍵字引數的詳細資訊，請參閱 TarFile 物件。

mode 必須是 'filemode[:compression]' 形式的字串，預設為 'r'。以下是所有可能的模式組合：

模式

操作

'r' 或 'r:*'

開啟以讀取，自動偵測壓縮格式（建議使用）。

'r:'

開啟以讀取未壓縮的檔案。

'r:gz'

開啟以讀取 gzip 壓縮的檔案。

'r:bz2'

開啟以讀取 bzip2 壓縮的檔案。

'r:xz'

開啟以讀取 lzma 壓縮的檔案。

'r:zst'

開啟以讀取 Zstandard 壓縮的檔案。

'x' 或 'x:'

建立一個不壓縮的 tarfile（獨佔模式）。如果檔案已存在，則引發 FileExistsError 例外。

'x:gz'

建立一個使用 gzip 壓縮的 tar 檔案。如果檔案已存在則引發 FileExistsError 例外。

'x:bz2'

建立一個使用 bzip2 壓縮的 tar 檔案。如果檔案已存在，則引發 FileExistsError 例外。

'x:xz'

建立一個使用 lzma 壓縮的 tar 檔案。如果檔案已存在，則引發 FileExistsError 例外。

'x:zst'

建立一個使用 Zstandard 壓縮的 tar 檔案。如果檔案已存在，則引發 FileExistsError 例外。

'a' 或 'a:'

開啟以附加內容且不使用壓縮。如果檔案不存在則建立它。

'w' 或 'w:'

開啟以寫入未壓縮的內容。

'w:gz'

開啟以進行 gzip 壓縮寫入。

'w:bz2'

開啟以進行 bzip2 壓縮寫入。

'w:xz'

開啟以進行 lzma 壓縮寫入。

'w:zst'

開啟以進行 Zstandard 壓縮寫入。

請注意 'a:gz'、'a:bz2' 或 'a:xz' 是不可能的。如果 mode 不適合開啟特定（壓縮）檔案以進行讀取，則會引發 ReadError。使用 mode 'r' 可避免此問題。如果不支援某個壓縮方法，則會引發 CompressionError。

如果指定了 fileobj，則它會被用作 name 以二進位模式開啟的檔案物件 的替代方案。它應該位於位置 0。

對於模式 'w:gz'、'x:gz'、'w|gz'、'w:bz2'、'x:bz2'、'w|bz2'，tarfile.open() 接受關鍵字引數 compresslevel（預設為 9）來指定檔案的壓縮等級。

對於模式 'w:xz'、'x:xz' 和 'w|xz'，tarfile.open() 接受關鍵字引數 preset 來指定檔案的壓縮等級。

對於模式 'w:zst'、'x:zst' 和 'w|zst'，tarfile.open() 接受關鍵字引數 level 來指定檔案的壓縮等級。也可以傳遞關鍵字引數 options，提供由 CompressionParameter 描述的進階 Zstandard 壓縮參數。可以傳遞關鍵字引數 zstd_dict 以提供 ZstdDict，這是一個用於改善較小資料量壓縮效果的 Zstandard 字典。

對於特殊用途，mode 有第二種格式：'filemode|[compression]'。tarfile.open() 會回傳一個 TarFile 物件，該物件將其資料作為區塊串流處理。不會對檔案進行隨機尋找。如果提供了 fileobj，它可以是任何具有 read() 或 write() 方法（取決於 mode）且能處理位元組的物件。bufsize 指定區塊大小，預設為 20 * 512 位元組。此變體可與 sys.stdin.buffer、socket 檔案物件 或磁帶裝置等結合使用。但是，這樣的 TarFile 物件受到限制，因為它不允許隨機存取，請參閱 範例。目前可能的模式：

模式

操作

'r|*'

開啟以讀取 tar 區塊的串流，自動偵測壓縮格式。

'r|'

開啟以讀取未壓縮的 tar 區塊串流。

'r|gz'

開啟以讀取 gzip 壓縮的串流。

'r|bz2'

開啟以讀取 bzip2 壓縮的串流。

'r|xz'

開啟以讀取 lzma 壓縮的串流。

'r|zst'

開啟以讀取 Zstandard 壓縮的串流。

'w|'

開啟以寫入未壓縮的串流。

'w|gz'

開啟以寫入 gzip 壓縮的串流。

'w|bz2'

開啟以寫入 bzip2 壓縮的串流。

'w|xz'

開啟以寫入 lzma 壓縮的串流。

'w|zst'

開啟以寫入 Zstandard 壓縮的串流。

在 3.5 版的變更: 新增了 'x'（獨佔建立）模式。

在 3.6 版的變更: name 參數接受類路徑物件。

在 3.12 版的變更: compresslevel 關鍵字引數也適用於串流。

在 3.14 版的變更: preset 關鍵字引數也適用於串流。

class tarfile.TarFile

用於讀取和寫入 tar 封存檔的類別。請勿直接使用此類別：請改用 tarfile.open()。請參閱 TarFile 物件。

tarfile.is_tarfile(name)

如果 name 是一個 tarfile 模組可以讀取的 tar 封存檔，則回傳 True。name 可以是 str、檔案或類檔案物件。

在 3.9 版的變更: 對檔案和類檔案物件的支援。

tarfile 模組定義了以下例外：

exception tarfile.TarError

所有 tarfile 例外的基底類別。

exception tarfile.ReadError

當開啟的 tar 封存檔無法被 tarfile 模組處理或以某種方式無效時引發。

exception tarfile.CompressionError

當壓縮方法不被支援或資料無法正確解碼時引發。

exception tarfile.StreamError

當遇到類似串流的 TarFile 物件的典型限制時引發。

exception tarfile.ExtractError

在使用 TarFile.extract() 時針對非致命錯誤引發，但僅限於 TarFile.errorlevel== 2 時。

exception tarfile.HeaderError

如果 TarInfo.frombuf() 得到的緩衝區無效，則引發此例外。

exception tarfile.FilterError

被篩選器拒絕的成員的基底類別。

tarinfo

篩選器拒絕解壓縮的成員資訊，以 TarInfo 表示。

exception tarfile.AbsolutePathError

當拒絕解壓縮具有絕對路徑的成員時引發。

exception tarfile.OutsideDestinationError

當拒絕解壓縮位於目的地目錄之外的成員時引發。

exception tarfile.SpecialFileError

當拒絕解壓縮特殊檔案（例如裝置或管道）時引發。

exception tarfile.AbsoluteLinkError

當拒絕解壓縮具有絕對路徑的符號連結時引發。

exception tarfile.LinkOutsideDestinationError

當拒絕解壓縮指向目的地目錄之外的符號連結時引發。

exception tarfile.LinkFallbackError

當透過解壓縮另一個封存檔成員來模擬連結（硬連結或符號連結）時，如果該成員會被篩選器位置拒絕，則引發此例外。用於拒絕替代成員的例外可作為 BaseException.__context__ 取得。

在 3.14 版被加入.

以下常數可在模組層級使用：

tarfile.ENCODING

預設字元編碼：在 Windows 上為 'utf-8'，否則為 sys.getfilesystemencoding() 回傳的值。

tarfile.REGTYPE
tarfile.AREGTYPE

一個普通檔案 type。

tarfile.LNKTYPE

一個連結（在 tar 檔案內）type。

tarfile.SYMTYPE

一個符號連結 type。

tarfile.CHRTYPE

一個字元特殊裝置 type。

tarfile.BLKTYPE

一個區塊特殊裝置 type。

tarfile.DIRTYPE

一個目錄 type。

tarfile.FIFOTYPE

一個 FIFO 特殊裝置 type。

tarfile.CONTTYPE

一個連續檔案 type。

tarfile.GNUTYPE_LONGNAME

一個 GNU tar longname type。

一個 GNU tar longlink type。

tarfile.GNUTYPE_SPARSE

一個 GNU tar 稀疏檔案 type。

以下每個常數定義了 tarfile 模組能夠建立的 tar 封存檔格式。詳細資訊請參閱 支援的 tar 格式 一節。

tarfile.USTAR_FORMAT

POSIX.1-1988 (ustar) 格式。

tarfile.GNU_FORMAT

GNU tar 格式。

tarfile.PAX_FORMAT

POSIX.1-2001 (pax) 格式。

tarfile.DEFAULT_FORMAT

建立封存檔的預設格式。目前為 PAX_FORMAT。

在 3.8 版的變更: 新封存檔的預設格式已從 GNU_FORMAT 變更為 PAX_FORMAT。

也參考

zipfile 模組

zipfile 標準模組的文件。

Archiving operations

標準 shutil 模組所提供的更高階封存功能的文件。

GNU tar 手冊，基本 Tar 格式

tar 封存檔案的文件，包括 GNU tar 擴充功能。

TarFile 物件

TarFile 物件提供一個 tar 封存檔的介面。tar 封存檔是一個區塊序列。一個封存檔成員（一個儲存的檔案）由一個標頭區塊和後續的資料區塊組成。可以在 tar 封存檔中多次儲存一個檔案。每個封存檔成員由一個 TarInfo 物件表示，詳細資訊請參閱