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.ExtractError¶
在使用
TarFile.extract()時針對非致命錯誤引發，但僅限於TarFile.errorlevel== 2時。
- exception tarfile.HeaderError¶
如果
TarInfo.frombuf()得到的緩衝區無效，則引發此例外。
- 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()回傳的值。