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 以提供