ZipFile 物件¶

classzipfile.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；無法識別的值將導致引發NotImplementedError。如果指定了ZIP_DEFLATED、ZIP_BZIP2 或ZIP_LZMA，但對應的模組（zlib、bz2 或lzma）不可用，則會引發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）。

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 陳述式的程式碼區塊執行完畢後會被關閉 --- 即使發生例外也是如此：

withZipFile('spam.zip','w')asmyzip: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,*,force_zip64=False)¶

以二進位類檔案物件的形式存取封存檔案中的一個成員。name 可以是封存檔案內的檔案名稱，或是一個ZipInfo 物件。mode 參數如果包含，則必須是'r'（預設值）或'w'。pwd 是用於解密加密 ZIP 檔案的密碼，為一個bytes 物件。

open() 也是一個情境管理器，因此支援with 陳述式：

withZipFile('spam.zip')asmyzip:withmyzip.open('eggs.txt')asmyfile:print(myfile.read())

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

在mode='w' 時，會回傳一個可寫的檔案控點 (file handle)，它支援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 以universal newlines 模式讀取壓縮的文字檔。

在 3.6 版的變更:ZipFile.open() 現在可以用於以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 共享點和開頭的（反）斜線將被移除，例如：在 Unix 上///foo/bar 變成foo/bar，在 Windows 上C:\foo\bar 變成foo\bar。並且成員檔名中所有的".." 元件將被移除，例如：../../foo../../ba..r 變成foo../ba..r。在 Windows 上，非法字元（:、<、>、|、"、? 和*）會被底線（_）取代。

在 3.6 版的變更:在一個已關閉的 ZipFile 上呼叫extract() 將會引發ValueError。先前，會引發一個RuntimeError。

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

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 參數接受一個path-like object。

ZipFile.printdir()¶

將封存檔案的內容目錄印出到sys.stdout。

ZipFile.setpassword(pwd)¶

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

ZipFile.read(name,pwd=None)¶

回傳封存檔案中name 檔案的位元組。name 是封存檔案中檔案的名稱，或是一個ZipInfo 物件。封存檔案必須以讀取或附加模式開啟。pwd 是用於加密檔案的密碼，為一個bytes 物件，如果指定，將會覆寫用setpassword() 設定的預設密碼。在一個使用ZIP_STORED、ZIP_DEFLATED、ZIP_BZIP2 或ZIP_LZMA 以外壓縮方法的 ZipFile 上呼叫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 檔案標準在歷史上並未指定元資料編碼，但為了互通性 (interoperability) 強烈建議使用 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 將覆寫為建構函式中compression 參數為新條目指定的值，或覆寫zinfo_or_arcname（如果它是一個ZipInfo 實例）中的值。同樣地，如果給定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 位元組。超過此長度的註解將被截斷。

Path 物件¶

classzipfile.Path(root,at='')¶

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

at 指定此 Path 在 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 提供了最新的 path 物件功能的向後移植版本。使用zipp.Path 來取代zipfile.Path 以提早使用變更。

PyZipFile 物件¶

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

classzipfile.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')>>>defnotests(s):...fn=os.path.basename(s)...return(not(fn=='test'orfn.startswith('test_')))...>>>zf.writepy('myprog',filterfunc=notests)

writepy() 方法會建立帶有如下檔名的封存檔案：

string.pyc# 頂層名稱test/__init__.pyc# 套件目錄test/testall.pyc# 模組 test.testalltest/bogus/__init__.pyc# 子套件目錄test/bogus/myfile.pyc# 子模組 test.bogus.myfile

在 3.4 版的變更:新增filterfunc 參數。

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

在 3.7 版的變更:遞迴會對目錄條目進行排序。

ZipInfo 物件¶

ZipInfo 類別的實例由ZipFile 物件的getinfo() 和infolist() 方法回傳。每個物件儲存關於 ZIP 封存檔案單一成員的資訊。

有一個類別方法可以為檔案系統中的檔案建立一個ZipInfo 實例：

classmethodZipInfo.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 參數接受一個path-like object。

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

實例具有以下方法和屬性：

ZipInfo.is_dir()¶

如果此封存成員是一個目錄，則回傳True。

這會使用條目的名稱：目錄應總是以/ 結尾。

在 3.6 版被加入.

ZipInfo.filename¶

封存檔案中檔案的名稱。

ZipInfo.date_time¶

封存成員的最後修改時間和日期。這是一個包含六個值的元組：

索引	值
0	年（>= 1980）
1	月（從 1 開始）
2	日（從 1 開始）
3	時（從 0 開始）
4	分（從 0 開始）
5	秒（從 0 開始）

備註

ZIP 檔案格式不支援 1980 年以前的時間戳記。

ZipInfo.compress_type¶

封存成員的壓縮型別。

ZipInfo.comment¶

個別封存成員的註解，為一個bytes 物件。

ZipInfo.extra¶

擴充欄位資料。PKZIP Application Note 包含一些關於此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-mzipfile-cmonty.zipspam.txteggs.txt

傳遞一個目錄也是可以的：

$python-mzipfile-cmonty.ziplife-of-brian_1979/

如果你想將一個 ZIP 封存檔案解壓縮到指定的目錄，請使用-e 選項：

$python-mzipfile-emonty.ziptarget-dir/

要列出 ZIP 封存檔案中的檔案，請使用-l 選項：

$python-mzipfile-lmonty.zip

解壓縮的陷阱¶

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