zipfile --- 處理 ZIP 封存檔案

原始碼：Lib/zipfile/

---

ZIP 檔案格式是一種常見的封存 (archive) 與壓縮標準。本模組提供了建立、讀取、寫入、附加與列出 ZIP 檔案的工具。任何對本模組的進階使用都將需要對 PKZIP Application Note 中定義的格式有所理解。

本模組不處理多組件 (multipart) ZIP 檔案。它可以處理使用 ZIP64 擴充（即大於 4 GiB 的 ZIP 檔案）的 ZIP 檔案。它支援解密 ZIP 封存檔案中的加密檔案，但目前無法建立加密檔案。解密速度極慢，因為它是在原生 Python 中實作，而不是 C。

Handling compressed archives requires optional modules such as zlib, bz2, lzma, and compression.zstd. If any of them are missing from your copy of CPython, look for documentation from your distributor (that is, whoever provided Python to you). If you are the distributor, see 可選模組的需求.

本模組定義了以下項目：

exception zipfile.BadZipFile

對於損壞的 ZIP 檔案所引發的錯誤。

在 3.2 版被加入.

exception zipfile.BadZipfile

BadZipFile 的別名，為了與舊版 Python 相容。

在 3.2 版之後被棄用.

exception zipfile.LargeZipFile

當 ZIP 檔案需要 ZIP64 功能但該功能未被啟用時所引發的錯誤。

class zipfile.ZipFile

用於讀取和寫入 ZIP 檔案的類別。有關建構函式的詳細資訊，請參閱 ZipFile 物件 章節。

class zipfile.Path

實作了 pathlib.Path 所提供介面子集的類別，包括完整的 importlib.resources.abc.Traversable 介面。

在 3.8 版被加入.

class zipfile.PyZipFile

用於建立包含 Python 函式庫的 ZIP 封存檔案的類別。

class zipfile.ZipInfo(filename='NoName', date_time=(1980, 1, 1, 0, 0, 0))

用於表示封存檔案中成員資訊的類別。此類別的實例由 ZipFile 物件的 getinfo() 和 infolist() 方法回傳。大多數 zipfile 模組的使用者不需要建立這些實例，而只需使用本模組所建立的。filename 應為封存成員的完整名稱，而 date_time 應為一個包含六個欄位的元組，用以描述檔案的最後修改時間；這些欄位在 ZipInfo 物件 章節中有所描述。

在 3.13 版的變更: 新增了一個公開的 compress_level 屬性，以公開先前受保護的 _compresslevel。為了向後相容，舊的受保護名稱仍可作為一個特性繼續運作。

_for_archive(archive)

Resolve the date_time, compression attributes, and external attributes to suitable defaults as used by ZipFile.writestr().

Returns self for chaining.

在 3.14 版被加入.

zipfile.is_zipfile(filename)

如果 filename 根據其魔術數字（magic number）是一個有效的 ZIP 檔案，則回傳 True，否則回傳 False。filename 也可以是一個檔案或類檔案物件。

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

zipfile.ZIP_STORED

用於未壓縮封存成員的數值常數。

zipfile.ZIP_DEFLATED

用於常用的 ZIP 壓縮方法的數值常數。這需要 zlib 模組。

zipfile.ZIP_BZIP2

用於 BZIP2 壓縮方法的數值常數。這需要 bz2 模組。

在 3.3 版被加入.

zipfile.ZIP_LZMA

用於 LZMA 壓縮方法的數值常數。這需要 lzma 模組。

在 3.3 版被加入.

zipfile.ZIP_ZSTANDARD

用於 Zstandard 壓縮方法的數值常數。這需要 compression.zstd 模組。

備註

In APPNOTE 6.3.7, the method ID 20 was assigned to Zstandard compression. This was changed in APPNOTE 6.3.8 to method ID 93 to avoid conflicts, with method ID 20 being deprecated. For compatibility, the zipfile module reads both method IDs but will only write data with method ID 93.

在 3.14 版被加入.

備註

ZIP 檔案格式規範自 2001 年起已包含對 bzip2 壓縮的支援、自 2006 年起支援 LZMA 壓縮、自 2020 年起支援 Zstandard 壓縮。然而某些工具（包括舊版的 Python）不支援這些壓縮方法，可能會完全拒絕處理該 ZIP 檔案，或無法解壓縮個別檔案。

也參考

PKZIP Application Note

由 Phil Katz（該格式與所用演算法的創造者）所撰寫的關於 ZIP 檔案格式的文件。

Info-ZIP 首頁

關於 Info-ZIP 專案的 ZIP 封存程式和開發函式庫的資訊。

ZipFile 物件

class zipfile.ZipFile(file, mode='r', compression=ZIP_STORED, allowZip64=True, compresslevel=None, *, strict_timestamps=True, metadata_encoding=None)

開啟一個 ZIP 檔案，其中 file 可以是一個檔案的路徑（一個字串）、一個類檔案物件或一個 path-like object。

mode 參數應為 'r' 來讀取一個現有檔案、'w' 來清空並寫入一個新檔案、'a' 來附加到一個現有檔案，或 'x' 來獨佔性地建立並寫入一個新檔案。如果 mode 為 'x' 且 file 指向一個現有檔案，將會引發 FileExistsError。如果 mode 為 'a' 且 file 指向一個現有的 ZIP 檔案，則會將額外的檔案加入其中。如果 file 並非指向一個 ZIP 檔案，則一個新的 ZIP 封存檔案會被附加到該檔案之後。這適用於將一個 ZIP 封存檔案附加到另一個檔案（例如 python.exe）。如果 mode 為 'a' 且檔案完全不存在，它會被建立。如果 mode 為 'r' 或 'a'，該檔案應為可定位的 (seekable)。

compression 是寫入封存檔案時要使用的 ZIP 壓縮方法，應為 ZIP_STORED、ZIP_DEFLATED、ZIP_BZIP2、ZIP_LZMA 或 ZIP_ZSTANDARD；無法識別的值將導致引發 NotImplementedError。如果指定了 ZIP_DEFLATED、ZIP_BZIP2、ZIP_LZMA 或 ZIP_ZSTANDARD，但對應的模組（zlib、bz2、lzma 或 compression.zstd）不可用，則會引發 RuntimeError。預設為 ZIP_STORED。

如果 allowZip64 為 True（預設值），當 zipfile 大於 4 GiB 時，zipfile 將會建立使用 ZIP64 擴充的 ZIP 檔案。如果為 false，當 ZIP 檔案需要 ZIP64 擴充時，zipfile 將會引發一個例外。

compresslevel 參數控制寫入檔案到封存時使用的壓縮層級。當使用 ZIP_STORED 或 ZIP_LZMA 時，它沒有效果。當使用 ZIP_DEFLATED 時，接受整數 0 到 9（更多資訊請參閱 zlib）。當使用 ZIP_BZIP2 時，接受整數 1 到 9（更多資訊請參閱 bz2）。當使用 ZIP_ZSTANDARD 時，通常接受整數 -131072 到 22（更多關於檢索有效值及其含義，請參閱 CompressionParameter.compression_level）。

strict_timestamps 引數，當設為 False 時，允許壓縮早於 1980-01-01 的檔案，代價是將時間戳記設為 1980-01-01。對於晚於 2107-12-31 的檔案，也會有類似的行為，時間戳記同樣會被設為極限值。

當 mode 為 'r' 時，metadata_encoding 可以設為一個編解碼器的名稱，該編解碼器將被用來解碼元資料，例如成員名稱和 ZIP 註解。

如果檔案以 'w'、'x' 或 'a' 模式建立，然後在沒有向封存檔案中加入任何檔案的情況下 關閉，則適用於空封存檔案的 ZIP 結構將被寫入檔案中。

ZipFile 也是一個情境管理器，因此支援 with 陳述式。在範例中，myzip 在 with 陳述式的程式碼區塊執行完畢後會被關閉 --- 即使發生例外也是如此：

with ZipFile('spam.zip', 'w') as myzip:
    myzip.write('eggs.txt')

備註

metadata_encoding 是 ZipFile 的一個實例範圍設定。無法以每個成員為基礎來設定此項。

此屬性是針對舊版實作的變通方法，這些實作會以目前區域編碼或頁碼（主要在 Windows 上）產生帶有名稱的封存檔案。根據 .ZIP 標準，元資料的編碼可以透過封存檔案標頭中的一個旗標指定為 IBM 頁碼（預設）或 UTF-8。該旗標的優先級高於 metadata_encoding，後者是 Python 特有的擴充。

在 3.2 版的變更: 新增 ZipFile 作為情境管理器使用的能力。

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

在 3.4 版的變更: ZIP64 擴充預設為啟用。

在 3.5 版的變更: 新增了對寫入不可定位的 (unseekable) 串流的支援。新增了對 'x' 模式的支援。

在 3.6 版的變更: 先前，對於無法識別的壓縮值，會引發一個單純的 RuntimeError。

在 3.6.2 版的變更: file 參數接受一個 path-like object。

在 3.7 版的變更: 新增 compresslevel 參數。

在 3.8 版的變更: strict_timestamps 僅限關鍵字參數。

在 3.11 版的變更: 新增了在讀取 zipfile 目錄和檔案標頭中的元資料時，可指定成員名稱編碼的支援。

ZipFile.close()

關閉封存檔案。你必須在結束程式前呼叫 close()，否則必要的記錄將不會被寫入。

ZipFile.getinfo(name)

回傳一個帶有關於封存成員 name 資訊的 ZipInfo 物件。對一個目前不包含在封存檔案中的名稱呼叫 getinfo() 將會引發 KeyError。

ZipFile.infolist()

回傳一個串列，其中為每個封存成員包含一個 ZipInfo 物件。如果開啟的是一個現有的封存檔案，這些物件的順序與它們在磁碟上實際 ZIP 檔案中的條目順序相同。

ZipFile.namelist()

依名稱回傳封存成員的串列。

ZipFile.open(name, mode='r', pwd=None,