zipfile — 處理 ZIP 存檔

原始碼: Lib/zipfile/

---

ZIP 檔案格式是一種常見的存檔和壓縮標準。本模組提供建立、讀取、寫入、追加和列出 ZIP 檔案的工具。任何高階使用本模組都需要理解該格式，該格式定義在 PKZIP 應用程式說明中。

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

本模組定義了以下項

異常 zipfile.BadZipFile

無效 ZIP 檔案引發的錯誤。

在 3.2 版本加入。

異常 zipfile.BadZipfile

BadZipFile 的別名，用於相容舊版 Python。

自 3.2 版本棄用。

異常 zipfile.LargeZipFile

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

類 zipfile.ZipFile

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

類 zipfile.Path

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

在 3.8 版本加入。

類 zipfile.PyZipFile

用於建立包含 Python 庫的 ZIP 存檔的類。

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

將 date_time、壓縮屬性和外部屬性解析為 ZipFile.writestr() 使用的合適預設值。

返回自身以進行鏈式呼叫。

在 3.14 版本加入。

zipfile.is_zipfile(filename)

如果 filename 是一個有效的 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 模組。

備註

在 APPNOTE 6.3.7 中，方法 ID 20 分配給 Zstandard 壓縮。這在 APPNOTE 6.3.8 中更改為方法 ID 93，以避免衝突，方法 ID 20 被棄用。為了相容性，zipfile 模組讀取這兩個方法 ID，但只寫入方法 ID 93 的資料。

在 3.14 版本加入。

備註

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

參見

PKZIP 應用程式說明

Phil Katz（該格式和所用演算法的建立者）提供的 ZIP 檔案格式文件。

Info-ZIP 主頁

有關 Info-ZIP 專案的 ZIP 存檔程式和開發庫的資訊。

ZipFile 物件

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

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

mode 引數應為 'r' 用於讀取現有檔案，'w' 用於截斷並寫入新檔案，'a' 用於追加到現有檔案，或 'x' 用於獨佔建立並寫入新檔案。如果 mode 為 'x' 且 file 指向現有檔案，則會引發 FileExistsError。如果 mode 為 'a' 且 file 指向現有 ZIP 檔案，則會向其新增更多檔案。如果 file 不指向 ZIP 檔案，則會將一個新的 ZIP 存檔追加到該檔案。這旨在將 ZIP 存檔新增到另一個檔案（例如 python.exe）。如果 mode 為 'a' 且檔案根本不存在，則會建立它。如果 mode 為 'r' 或 'a'，則檔案應可查詢。

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（預設值），當 zip 檔案大於 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 的檔案，也會發生類似的行為，時間戳也會設定為限制。

當模式為 'r' 時，可以設定 metadata_encoding 為編解碼器的名稱，該編解碼器將用於解碼元資料，例如成員名稱和 ZIP 註釋。

如果檔案以 'w'、'x' 或 'a' 模式建立，然後在未向存檔新增任何檔案的情況下 關閉，則會向檔案中寫入空存檔的相應 ZIP 結構。

ZipFile 也是一個上下文管理器，因此支援 with 語句。在示例中，在 with 語句的程式碼塊完成後，即使發生異常，myzip 也會關閉。

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 版本中更改: 增加了對寫入不可查詢流的支援。增加了對 'x' 模式的支援。

在 3.6 版本中更改: 以前，對於無法識別的壓縮值會引發一個普通的 RuntimeError。

在 3.6.2 版本中更改: file 引數接受 路徑類物件。

在 3.7 版本中更改: 添加了 compresslevel 引數。

在 3.8 版本中更改: strict_timestamps 僅限關鍵字引數。

在 3.11 版本中更改: 增加了對指定成員名稱編碼的支援，用於讀取 zip 檔案目錄和檔案頭中的元資料。

ZipFile.close()

關閉存檔檔案。您必須在程式退出前呼叫 close()，否則重要記錄將不會被寫入。

ZipFile.getinfo(name)

返回一個 ZipInfo 物件，其中包含有關存檔成員 name 的資訊。如果為當前存檔中不包含的名稱呼叫 getinfo()，將引發 KeyError。

ZipFile.infolist()

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

ZipFile.namelist()

按名稱返回存檔成員列表。

ZipFile.open(name, mode='r', pwd=None, *, force_zip64=False)

以二進位制類檔案物件訪問存檔的成員。name 可以是存檔中檔案的名稱，也可以是 ZipInfo 物件。mode 引數（如果包含）必須是 'r'（預設）或 'w'。pwd 是用於解密加密 ZIP 檔案的密碼，作為 bytes 物件。

open() 也是一個上下文管理器，因此支援 with 語句。

with ZipFile('spam.zip') as myzip:
    with myzip.open('eggs.txt') as myfile:
        print(myfile.read())

在 mode 為 'r' 時，類檔案物件 (ZipExtFile) 是隻讀的，並提供以下方法：read()、readline()、readlines()、seek()、tell()、__iter__()、__next__()。這些物件可以獨立於 ZipFile 執行。

當 mode='w' 時，返回一個可寫的檔案控制代碼，它支援 write() 方法。當可寫檔案控制代碼開啟時，嘗試讀取或寫入 ZIP 檔案中的其他檔案將引發 ValueError。

在這兩種情況下，類檔案物件也具有屬性 name（等同於存檔中的檔名）和 mode（根據輸入模式為 'rb' 或 'wb'）。

寫入檔案時，如果檔案大小事先未知但可能超過 2 GiB，請傳遞 force_zip64=True 以確保標頭檔案格式能夠支援大檔案。如果檔案大小事先已知，請構造一個設定了 file_size 的 ZipInfo 物件，並將其用作 name 引數。

備註

open()、read() 和 extract() 方法可以接受檔名或 ZipInfo 物件。當您嘗試讀取包含具有重複名稱成員的 ZIP 檔案時，您會發現這很有用。

在 3.6 版本中更改: 移除了對 mode='U' 的支援。請使用 io.TextIOWrapper 以 通用換行 模式讀取壓縮文字檔案。

在 3.6 版本中更改: 現在可以使用 mode='w' 選項將檔案寫入存檔中。

在 3.6 版本中更改: 對已關閉的 ZipFile 呼叫 open() 將引發 ValueError。以前會引發 RuntimeError。

在 3.13 版本中更改: 為可寫入的類檔案物件添加了屬性 name 和 mode。可讀的類檔案物件的 mode 屬性的值從 'r' 更改為 'rb'。

ZipFile.extract(member, path=None, pwd=None)

將存檔中的成員提取到當前工作目錄；member 必須是其完整名稱或 ZipInfo 物件。其檔案資訊將盡可能準確地提取。path 指定要提取到的不同目錄。member 可以是檔名或 ZipInfo 物件。pwd 是用於加密檔案的密碼，作為 bytes 物件。

返回建立的規範化路徑（目錄或新檔案）。

備註

如果成員檔名是絕對路徑，則會剝離驅動器/UNC 共享點和前導（反）斜槓，例如：///foo/bar 在 Unix 上變為 foo/bar，C:\foo\bar 在 Windows 上變為 foo\bar。並且成員檔名中的所有 ".." 元件都將被刪除，例如：../../foo../../ba..r 變為 foo../ba..r。在 Windows 上，非法字元（:、<、>、|、"、? 和 *）將替換為下劃線（_）。

在 3.6 版本中更改: 對已關閉的 ZipFile 呼叫 extract() 將引發 ValueError。以前會引發 RuntimeError。

在 3.6.2 版本中更改: path 引數接受 路徑類物件。

ZipFile.extractall(path=None, members=None, pwd=None)

將存檔中的所有成員提取到當前工作目錄。path 指定要提取到的不同目錄。members 是可選的，並且必須是 namelist() 返回列表的子集。pwd 是用於加密檔案的密碼，作為 bytes 物件。

警告

切勿在未經事先檢查的情況下從不受信任的來源提取存檔。檔案可能會在 path 之外建立，例如，檔名以 "/" 開頭或包含兩個點 ".." 的檔名。本模組試圖阻止這種情況。請參閱 extract() 註釋。

在 3.6 版本中更改: 對已關閉的 ZipFile 呼叫 extractall() 將引發 ValueError。以前會引發 RuntimeError。

在 3.6.2 版本中更改: path 引數接受 路徑類物件。

ZipFile.printdir()

將存檔的目錄表列印到 sys.stdout。

ZipFile.setpassword(pwd)

將 pwd（一個 bytes 物件）設定為解密加密檔案的預設密碼。

ZipFile.read(name, pwd=None)

返回存檔中檔案 name 的位元組。name 是存檔中的檔名，或 ZipInfo 物件。存檔必須以讀取或追加模式開啟。pwd 是用於加密檔案的密碼，作為 bytes 物件，如果指定，則覆蓋透過 setpassword() 設定的預設密碼。如果 ZipFile 使用除 ZIP_STORED、ZIP_DEFLATED、ZIP_BZIP2、ZIP_LZMA 或 ZIP_ZSTANDARD 之外的壓縮方法，則呼叫 read() 將引發 NotImplementedError。如果相應的壓縮模組不可用，也將引發錯誤。

在 3.6 版本中更改: 對已關閉的 ZipFile 呼叫 read() 將引發 ValueError。以前會引發 RuntimeError。

ZipFile.testzip()

讀取存檔中的所有檔案並檢查其 CRC 和檔案頭。返回第一個損壞檔案的名稱，否則返回 None。

在 3.6 版本中更改: 對已關閉的 ZipFile 呼叫 testzip() 將引發 ValueError。以前會引發 RuntimeError。

ZipFile.write(filename, arcname=None, compress_type=None, compresslevel=None)

將名為 filename 的檔案寫入存檔，並賦予它存檔名稱 arcname（預設情況下，這將與 filename 相同，但沒有驅動器磁碟機代號並移除了前導路徑分隔符）。如果給出 compress_type，它將覆蓋為建構函式的新條目 compression 引數指定的值。同樣，如果給定 compresslevel，它將覆蓋建構函式。存檔必須以 'w'、'x' 或 'a' 模式開啟。

備註

ZIP 檔案標準歷來未指定元資料編碼，但強烈推薦使用 CP437（原始 IBM PC 編碼）以實現互操作性。最新版本允許（僅）使用 UTF-8。在此模組中，如果成員名稱包含任何非 ASCII 字元，將自動使用 UTF-8 寫入成員名稱。不能以 ASCII 或 UTF-8 以外的任何編碼寫入成員名稱。

備註

存檔名稱應相對於存檔根目錄，即不應以路徑分隔符開頭。

備註

如果 arcname（如果未給定 arcname，則為 filename）包含空位元組，則存檔中的檔名將在空位元組處被截斷。

備註

檔名中的前導斜槓可能導致某些 Windows 系統上的 zip 程式無法開啟存檔。

在 3.6 版本中更改: 對以 'r' 模式建立的 ZipFile 或已關閉的 ZipFile 呼叫 write() 將引發 ValueError。以前會引發 RuntimeError。

ZipFile.writestr(zinfo_or_arcname, data, compress_type=None, compresslevel=None)

將檔案寫入存檔。內容是 data，它可以是 str 或 bytes 例項；如果它是 str，則首先將其編碼為 UTF-8。zinfo_or_arcname 是檔案在存檔中將被賦予的名稱，或者是 ZipInfo 例項。如果它是一個例項，則至少必須給出檔名、日期和時間。如果它是一個名稱，則日期和時間將設定為當前日期和時間。存檔必須以 'w'、'x' 或 'a' 模式開啟。

如果給出 compress_type，它將覆蓋為建構函式的新條目或 zinfo_or_arcname（如果它是 ZipInfo 例項）的 compression 引數指定的值。同樣，如果給出 compresslevel，它將覆蓋建構函式。

備註

當將 ZipInfo 例項作為 zinfo_or_arcname 引數傳遞時，使用的壓縮方法將是給定 ZipInfo 例項的 compress_type 成員中指定的方法。預設情況下，ZipInfo 建構函式將此成員設定為 ZIP_STORED。

在 3.2 版本中更改: compress_type 引數。

在 3.6 版本中更改: 對以 'r' 模式建立的 ZipFile 或已關閉的 ZipFile 呼叫 writestr() 將引發 ValueError。以前會引發 RuntimeError。

ZipFile.mkdir(zinfo_or_directory, mode=511)

在存檔中建立一個目錄。如果 zinfo_or_directory 是一個字串，則在存檔中建立一個目錄，其模式由 mode 引數指定。然而，如果 zinfo_or_directory 是一個 ZipInfo 例項，則 mode 引數將被忽略。

存檔必須以 'w'、'x' 或 'a' 模式開啟。

在 3.11 版本中新增。

以下資料屬性也可用：

ZipFile.filename

ZIP 檔案的名稱。

ZipFile.debug

要使用的除錯輸出級別。此值可以設定為 0（預設，無輸出）到 3（最多輸出）。除錯資訊寫入 sys.stdout。

ZipFile.comment

與 ZIP 檔案關聯的註釋，作為 bytes 物件。如果為以 'w'、'x' 或 'a' 模式建立的 ZipFile 例項分配註釋，則註釋不應超過 65535 位元組。超過此長度的註釋將被截斷。

路徑物件

類 zipfile.Path(root, at='')

從 root zipfile 構造一個 Path 物件（它可以是 ZipFile 例項或適合傳遞給 ZipFile 建構函式的 file）。

at 指定此路徑在 zipfile 中的位置，例如“dir/file.txt”、“dir/”或“”。預設為空字串，表示根目錄。

備註

Path 類不會清理 ZIP 存檔中的檔名。與 ZipFile.extract() 和 ZipFile.extractall() 方法不同，呼叫者有責任驗證或清理檔名以防止路徑遍歷漏洞（例如，包含“..”或絕對路徑的檔名）。處理不受信任的存檔時，請考慮使用 os.path.abspath() 解析檔名並使用 os.path.commonpath() 檢查目標目錄。

Path 物件公開了 pathlib.Path 物件的以下功能

Path 物件可以使用 / 運算子或 joinpath 進行遍歷。

Path.name

最終路徑元件。

Path.open(mode='r', *, pwd, **)

在當前路徑上呼叫 ZipFile.open()。允許透過支援的模式（'r', 'w', 'rb', 'wb'）開啟進行讀取或寫入，文字或二進位制。位置引數和關鍵字引數在以文字模式開啟時傳遞給 io.TextIOWrapper，否則忽略。pwd 是 ZipFile.open() 的 pwd 引數。

在 3.9 版本中更改: 增加了對 open 的文字和二進位制模式的支援。預設模式現在是文字。

在 3.11.2 版本中更改: encoding 引數可以作為位置引數提供，而不會導致 TypeError。正如在 3.9 中一樣。需要與未打補丁的 3.10 和 3.11 版本相容的程式碼必須將所有 io.TextIOWrapper 引數（包括 encoding）作為關鍵字引數傳遞。

Path.iterdir()

列舉當前目錄的子項。

Path.is_dir()

如果當前上下文引用目錄，則返回 True。

Path.is_file()

如果當前上下文引用檔案，則返回 True。

Path.is_symlink()

如果當前上下文引用符號連結，則返回 True。

3.12 新版功能.

在 3.13 版本中更改: 以前，is_symlink 將無條件返回 False。

Path.exists()

如果當前上下文引用 zip 檔案中的檔案或目錄，則返回 True。

Path.suffix

最終元件的最後一個點分隔部分（如果有）。這通常被稱為副檔名。

在 3.11 版本中新增: 添加了 Path.suffix 屬性。

Path.stem

最終路徑元件，不帶字尾。

在 3.11 版本中新增: 添加了 Path.stem 屬性。

Path.suffixes

路徑字尾的列表，通常稱為副檔名。

在 3.11 版本中新增: 添加了 Path.suffixes 屬性。

Path.read_text(*, **)

將當前檔案作為 unicode 文字讀取。位置引數和關鍵字引數傳遞給 io.TextIOWrapper（除了 buffer，它由上下文隱式提供）。

在 3.11.2 版本中更改: encoding 引數可以作為位置引數提供，而不會導致 TypeError。正如在 3.9 中一樣。需要與未打補丁的 3.10 和 3.11 版本相容的程式碼必須將所有 io.TextIOWrapper 引數（包括 encoding）作為關鍵字引數傳遞。

Path.read_bytes()

將當前檔案作為位元組讀取。

Path.joinpath(*other)

返回一個新 Path 物件，其中每個 other 引數都已連線。以下是等效的

>>> Path(...).joinpath('child').joinpath('grandchild')
>>> Path(...).joinpath('child', 'grandchild')
>>> Path(...) / 'child' / 'grandchild'

在 3.10 版本中更改: 在 3.10 之前，joinpath 未文件化，且只接受一個引數。

zipp 專案提供了最新路徑物件功能對舊版 Python 的反向移植。使用 zipp.Path 代替 zipfile.Path 可提前訪問更改。

PyZipFile 物件

PyZipFile 建構函式接受與 ZipFile 建構函式相同的引數，以及一個額外的引數 optimize。

類 zipfile.PyZipFile(file, mode='r', compression=ZIP_STORED, allowZip64=True, optimize=-1)

在 3.2 版本中更改: 添加了 optimize 引數。

在 3.4 版本中更改: ZIP64 擴充套件預設啟用。

除了 ZipFile 物件的方法之外，例項還有一個方法

writepy(pathname, basename='', filterfunc=None)

搜尋檔案 *.py 並將相應的檔案新增到存檔中。

如果未給出 PyZipFile 的 optimize 引數或為 -1，則相應的檔案是 *.pyc 檔案，必要時進行編譯。

如果 PyZipFile 的 optimize 引數為 0、1 或 2，則只有具有該最佳化級別（參見 compile()）的檔案才被新增到存檔中，必要時進行編譯。

如果 pathname 是一個檔案，檔名必須以 .py 結尾，並且只有（相應的 *.pyc）檔案被新增到頂層（沒有路徑資訊）。如果 pathname 是一個不以 .py 結尾的檔案，則會引發 RuntimeError。如果它是一個目錄，並且該目錄不是包目錄，則所有 *.pyc 檔案都新增到頂層。如果該目錄是包目錄，則所有 *.pyc 檔案都作為檔案路徑新增到包名稱下，並且如果有任何子目錄是包目錄，則所有這些子目錄都以排序順序遞迴新增。

basename 僅供內部使用。

filterfunc（如果給定）必須是一個接受單個字串引數的函式。在將每個路徑（包括每個單獨的完整檔案路徑）新增到存檔之前，將傳遞給它。如果 filterfunc 返回一個假值，則該路徑將不會被新增，如果它是一個目錄，其內容將被忽略。例如，如果我們的測試檔案都在 test 目錄中或以字串 test_ 開頭，我們可以使用 filterfunc 來排除它們。

>>> zf = PyZipFile('myprog.zip')
>>> def notests(s):
...     fn = os.path.basename(s)
...     return (not (fn == 'test' or fn.startswith('test_')))
...
>>> zf.writepy('myprog', filterfunc=notests)

writepy() 方法建立的檔案存檔名稱如下所示

string.pyc                   # Top level name
test/__init__.pyc            # Package directory
test/testall.pyc             # Module test.testall
test/bogus/__init__.pyc      # Subpackage directory
test/bogus/myfile.pyc        # Submodule test.bogus.myfile

在 3.4 版本中更改: 添加了 filterfunc 引數。

在 3.6.2 版本中更改: pathname 引數接受 路徑類物件。

在 3.7 版本中更改: 遞迴對目錄條目進行排序。

ZipInfo 物件

ZipFile 物件的 getinfo() 和 infolist() 方法會返回 ZipInfo 類的例項。每個物件儲存有關 ZIP 存檔單個成員的資訊。

有一個類方法用於為檔案系統檔案建立 ZipInfo 例項。

classmethod ZipInfo.from_file(filename, arcname=None, *, strict_timestamps=True)

為檔案系統上的檔案構造 ZipInfo 例項，以準備將其新增到 zip 檔案中。

filename 應該是檔案系統上檔案或目錄的路徑。

如果指定了 arcname，它將用作存檔中的名稱。如果未指定 arcname，則名稱將與 filename 相同，但會去除任何驅動器磁碟機代號和前導路徑分隔符。

當 strict_timestamps 引數設定為 False 時，允許壓縮早於 1980-01-01 的檔案，代價是將時間戳設定為 1980-01-01。對於晚於 2107-12-31 的檔案，也會發生類似的行為，時間戳也會設定為限制。

在 3.6 版本加入。

3.6.2 版本中的變化： filename 引數接受路徑類物件。

3.8 版本中的變化： 添加了 strict_timestamps 僅限關鍵字的引數。

例項具有以下方法和屬性

ZipInfo.is_dir()

如果此歸檔成員是目錄，則返回 True。

這使用條目名稱：目錄應始終以 / 結尾。

在 3.6 版本加入。

ZipInfo.filename

歸檔中檔案的名稱。

ZipInfo.date_time

歸檔成員上次修改的時間和日期。這是一個包含六個值的元組，表示 ZIP 檔案的中心目錄中的“上次 [修改] 檔案時間”和“上次 [修改] 檔案日期”欄位。

元組包含

索引	值
0	年份（>= 1980）
1	月份（從 1 開始）
2	月份中的日期（從 1 開始）
3	小時（從 0 開始）
4	分鐘（從 0 開始）
5	秒（從 0 開始）

備註

ZIP 格式支援在不同位置（中心目錄、NTFS/UNIX 系統的附加欄位等）的多個時間戳欄位。此屬性特別返回中心目錄中的時間戳。ZIP 檔案中的中心目錄時間戳格式不支援 1980 年之前的時間戳。雖然某些附加欄位格式（例如 UNIX 時間戳）可以表示更早的日期，但此屬性僅返回中心目錄時間戳。

中心目錄時間戳被解釋為表示本地時間，而不是 UTC 時間，以匹配其他 zip 工具的行為。

ZipInfo.compress_type

歸檔成員的壓縮型別。

ZipInfo.comment

作為 bytes 物件的單個歸檔成員的註釋。

ZipInfo.extra

擴充套件欄位資料。PKZIP 應用程式說明 包含對此 bytes 物件中包含的資料的內部結構的一些註釋。

ZipInfo.create_system

建立 ZIP 歸檔的系統。

ZipInfo.create_version

建立 ZIP 歸檔的 PKZIP 版本。

ZipInfo.extract_version

提取歸檔所需的 PKZIP 版本。

ZipInfo.reserved

必須為零。

ZipInfo.flag_bits

ZIP 標誌位。

ZipInfo.volume

檔案頭的卷號。

ZipInfo.internal_attr

內部屬性。

ZipInfo.external_attr

外部檔案屬性。

ZipInfo.header_offset

檔案頭的位元組偏移量。

ZipInfo.CRC

未壓縮檔案的 CRC-32。

ZipInfo.compress_size

壓縮資料的大小。

ZipInfo.file_size

未壓縮檔案的大小。

命令列介面

zipfile 模組提供了一個簡單的命令列介面來與 ZIP 歸檔互動。

如果要建立新的 ZIP 歸檔，請在 -c 選項後指定其名稱，然後列出要包含的檔名。

$ python -m zipfile -c monty.zip spam.txt eggs.txt

傳遞目錄也是可接受的。

$ python -m zipfile -c monty.zip life-of-brian_1979/

如果要將 ZIP 歸檔解壓到指定目錄，請使用 -e 選項。

$ python -m zipfile -e monty.zip target-dir/

要列出 ZIP 歸檔中的檔案，請使用 -l 選項。

$ python -m zipfile -l monty.zip

命令列選項

-l <zipfile>

--list <zipfile>

列出 zipfile 中的檔案。

-c <zipfile> <source1> ... <sourceN>

--create <zipfile> <source1> ... <sourceN>

從原始檔建立 zipfile。

-e <zipfile> <output_dir>

--extract <zipfile> <output_dir>

將 zipfile 解壓到目標目錄。

-t <zipfile>

--test <zipfile>

測試 zipfile 是否有效。

--metadata-encoding <encoding>

指定 -l、-e 和 -t 成員名稱的編碼。

在 3.11 版本中新增。

解壓陷阱

zipfile 模組中的解壓可能會因下面列出的一些陷阱而失敗。

從檔案本身

由於密碼不正確/CRC 校驗和/ZIP 格式或不支援的壓縮方法/解密，解壓可能會失敗。

檔案系統限制

超出不同檔案系統的限制可能導致解壓失敗。例如目錄條目中允許的字元、檔名長度、路徑名長度、單個檔案大小和檔案數量等。

資源限制

記憶體或磁碟空間不足會導致解壓失敗。例如，解壓炸彈（也稱為 ZIP 炸彈）適用於 zipfile 庫，可能導致磁碟空間耗盡。

中斷

解壓過程中的中斷，例如按下 Ctrl-C 或終止解壓程序，可能導致歸檔解壓不完整。

解壓的預設行為

不瞭解預設解壓行為可能導致意外的解壓結果。例如，當兩次解壓同一個歸檔時，它會在不詢問的情況下覆蓋檔案。