zlib — 與 gzip 相容的壓縮¶
對於需要資料壓縮的應用程式，此模組中的函式允許使用 zlib 庫進行壓縮和解壓縮。zlib 庫在 https://www.zlib.net 有自己的主頁。Python 模組與早於 1.1.3 的 zlib 庫版本之間存在已知的不相容性；1.1.3 有一個 安全漏洞，因此我們建議使用 1.1.4 或更高版本。
zlib 的函式有很多選項，並且通常需要按特定的順序使用。本文件不嘗試涵蓋所有排列組合；有關權威資訊，請參閱 http://www.zlib.net/manual.html 上的 zlib 手冊。
有關讀取和寫入 .gz 檔案，請參閱 gzip 模組。
此模組中可用的異常和函式是
- 異常 zlib.error¶
在壓縮和解壓縮錯誤時引發的異常。
- zlib.adler32(data[, value])¶
計算 data 的 Adler-32 校驗和。（Adler-32 校驗和幾乎與 CRC32 一樣可靠，但可以更快地計算。）結果是一個無符號的 32 位整數。如果存在 value，則將其用作校驗和的起始值；否則，使用預設值 1。傳入 value 允許計算多個輸入連線的執行校驗和。該演算法在密碼學上並不強大，不應用於身份驗證或數字簽名。由於該演算法設計為用作校驗和演算法，因此不適合用作通用雜湊演算法。
在 3.0 版本中更改: 結果始終是無符號的。
- zlib.compress(data, /, level=-1, wbits=MAX_WBITS)¶
壓縮 data 中的位元組，返回包含壓縮資料的位元組物件。level 是一個從
0到9或-1的整數，控制壓縮級別；1(Z_BEST_SPEED) 最快併產生最少的壓縮，9(Z_BEST_COMPRESSION) 最慢併產生最多的壓縮。0(Z_NO_COMPRESSION) 是不壓縮。預設值為-1(Z_DEFAULT_COMPRESSION)。Z_DEFAULT_COMPRESSION 表示速度和壓縮之間的預設折衷方案（目前相當於級別 6）。wbits 引數控制壓縮資料時使用的歷史緩衝區（或“視窗大小”）的大小，以及輸出中是否包含標頭和尾部。它可以採用多個值範圍，預設為
15(MAX_WBITS)+9 到 +15：視窗大小的以 2 為底的對數，因此範圍在 512 到 32768 之間。較大的值會產生更好的壓縮，但代價是記憶體使用量更大。生成的輸出將包含特定於 zlib 的標頭和尾部。
−9 到 −15：使用 wbits 的絕對值作為視窗大小對數，同時生成不帶標頭或尾部校驗和的原始輸出流。
+25 到 +31 = 16 + (9 到 15)：使用該值的低 4 位作為視窗大小對數，同時在輸出中包含基本的 gzip 標頭和尾部校驗和。
如果發生任何錯誤，則引發
error異常。在 3.6 版本中更改: level 現在可以用作關鍵字引數。
在 3.11 版本中更改: wbits 引數現在可用於設定視窗位和壓縮型別。
- zlib.compressobj(level=-1, method=DEFLATED, wbits=MAX_WBITS, memLevel=DEF_MEM_LEVEL, strategy=Z_DEFAULT_STRATEGY[, zdict])¶
返回一個壓縮物件，用於壓縮無法一次裝入記憶體的資料流。
level 是壓縮級別 – 一個從
0到9或-1的整數。值為1(Z_BEST_SPEED) 最快併產生最少的壓縮，而值為9(Z_BEST_COMPRESSION) 最慢併產生最多的壓縮。0(Z_NO_COMPRESSION) 是不壓縮。預設值為-1(Z_DEFAULT_COMPRESSION)。Z_DEFAULT_COMPRESSION 表示速度和壓縮之間的預設折衷方案（目前相當於級別 6）。method 是壓縮演算法。目前，唯一支援的值是
DEFLATED。wbits 引數控制歷史緩衝區（或“視窗大小”）的大小，以及將使用什麼標頭和尾部格式。它與 為 compress() 描述的含義相同。
memLevel 引數控制用於內部壓縮狀態的記憶體量。有效值的範圍從
1到9。較高的值使用更多記憶體，但速度更快併產生較小的輸出。strategy 用於調整壓縮演算法。可能的值是
Z_DEFAULT_STRATEGY、Z_FILTERED、Z_HUFFMAN_ONLY、Z_RLE(zlib 1.2.0.1) 和Z_FIXED(zlib 1.2.2.2)。zdict 是一個預定義的壓縮字典。這是一個位元組序列（例如
bytes物件），其中包含預期在要壓縮的資料中頻繁出現的子序列。預期最常見的子序列應位於字典的末尾。在 3.3 版本中更改: 添加了 zdict 引數和關鍵字引數支援。
- zlib.crc32(data[, value])¶
計算 data 的 CRC（迴圈冗餘校驗）校驗和。結果是一個無符號的 32 位整數。如果存在 value，則將其用作校驗和的起始值；否則，使用預設值 0。傳入 value 允許計算多個輸入連線的執行校驗和。該演算法在密碼學上並不強大，不應用於身份驗證或數字簽名。由於該演算法設計為用作校驗和演算法，因此不適合用作通用雜湊演算法。
在 3.0 版本中更改: 結果始終是無符號的。
- zlib.decompress(data, /, wbits=MAX_WBITS, bufsize=DEF_BUF_SIZE)¶
解壓 data 中的位元組，返回包含解壓資料的位元組物件。wbits 引數取決於 data 的格式，將在下面進一步討論。如果給定 bufsize，它將用作輸出緩衝區的初始大小。如果發生任何錯誤，則引發
error異常。wbits 引數控制歷史緩衝區（或“視窗大小”）的大小，以及預期使用哪種標頭和尾部格式。它類似於
compressobj()的引數，但接受更多值的範圍。+8 到 +15：視窗大小的以 2 為底的對數。輸入必須包含 zlib 標頭和尾部。
0：從 zlib 標頭自動確定視窗大小。僅從 zlib 1.2.3.5 版本開始支援。
−8 到 −15：使用 wbits 的絕對值作為視窗大小的對數。輸入必須是原始流，不包含標頭或尾部。
+24 到 +31 = 16 +（8 到 15）：使用值的低 4 位作為視窗大小的對數。輸入必須包含 gzip 標頭和尾部。
+40 到 +47 = 32 +（8 到 15）：使用值的低 4 位作為視窗大小的對數，並自動接受 zlib 或 gzip 格式。
解壓縮流時，視窗大小不得小於最初用於壓縮流的大小；使用過小的值可能會導致
error異常。預設的 wbits 值對應於最大的視窗大小，並且需要包含 zlib 標頭和尾部。bufsize 是用於儲存解壓縮資料的緩衝區的初始大小。如果需要更多空間，緩衝區大小將根據需要增加，因此您不必精確地獲取此值；調整它只會節省幾次對
malloc()的呼叫。3.6 版本更改: wbits 和 bufsize 可以用作關鍵字引數。
- zlib.decompressobj(wbits=MAX_WBITS[, zdict])¶
返回一個解壓縮物件，用於解壓縮無法一次放入記憶體的資料流。
wbits 引數控制歷史緩衝區（或“視窗大小”）的大小，以及預期使用哪種標頭和尾部格式。它的含義與 decompress() 的描述相同。
zdict 引數指定預定義的壓縮字典。如果提供，則該字典必須與生成要解壓縮的資料的壓縮器所使用的字典相同。
注意
如果 zdict 是一個可變物件（例如
bytearray），則在呼叫decompressobj()和首次呼叫解壓縮器的decompress()方法之間，不能修改其內容。3.3 版本更改: 添加了 zdict 引數。
壓縮物件支援以下方法
- Compress.compress(data)¶
壓縮 data，返回一個位元組物件，其中包含至少部分 data 中的壓縮資料。此資料應與之前對
compress()方法的任何呼叫所產生的輸出連線起來。某些輸入可能保留在內部緩衝區中以供後續處理。
- Compress.flush([mode])¶
處理所有掛起的輸入，並返回包含剩餘壓縮輸出的位元組物件。mode 可以從常量
Z_NO_FLUSH、Z_PARTIAL_FLUSH、Z_SYNC_FLUSH、Z_FULL_FLUSH、Z_BLOCK(zlib 1.2.3.4) 或Z_FINISH中選擇，預設為Z_FINISH。除了Z_FINISH之外，所有常量都允許壓縮更多的資料位元組串，而Z_FINISH完成壓縮流並阻止壓縮任何更多資料。在呼叫flush()且 mode 設定為Z_FINISH後，不能再次呼叫compress()方法；唯一現實的動作是刪除該物件。
- Compress.copy()¶
返回壓縮物件的副本。這可以用於有效地壓縮共享公共初始字首的一組資料。
3.8 版本更改: 向壓縮物件添加了 copy.copy() 和 copy.deepcopy() 支援。
解壓縮物件支援以下方法和屬性
- Decompress.unused_data¶
一個位元組物件，其中包含壓縮資料結尾之後的任何位元組。也就是說，在包含壓縮資料的最後一個位元組可用之前，它仍然是
b""。如果整個位元組串最終包含壓縮資料，則此值是b""，一個空位元組物件。
- Decompress.unconsumed_tail¶
一個位元組物件，其中包含上次
decompress()呼叫未使用的任何資料，因為它超出了未壓縮資料緩衝區的限制。zlib 機制尚未看到此資料，因此您必須將其（可能與進一步的資料連線）反饋到後續的decompress()方法呼叫中，才能獲得正確的輸出。
- Decompress.eof¶
一個布林值，指示是否已到達壓縮資料流的末尾。
這使得能夠區分正確形成的壓縮流和不完整或截斷的壓縮流。
在 3.3 版本中新增。
- Decompress.decompress(data, max_length=0)¶
解壓 data，返回一個位元組物件，其中包含至少部分 string 中的資料對應的解壓縮資料。此資料應與之前對
decompress()方法的任何呼叫所產生的輸出連線起來。某些輸入資料可能保留在內部緩衝區中以供後續處理。如果可選引數 max_length 為非零值，則返回值將不會超過 max_length。這可能意味著並非所有壓縮輸入都可以被處理；未使用的位元組將儲存在屬性
unconsumed_tail中。如果要繼續解壓縮，則必須將此位元組串傳遞給對decompress()的後續呼叫。如果 max_length 為零，則將解壓縮整個輸入，並且unconsumed_tail為空。3.6 版本更改: max_length 可以用作關鍵字引數。
- Decompress.flush([length])¶
處理所有掛起的輸入，並返回包含剩餘未壓縮輸出的位元組物件。在呼叫
flush()後，不能再次呼叫decompress()方法；唯一現實的動作是刪除該物件。可選引數 length 設定輸出緩衝區的初始大小。
- Decompress.copy()¶
返回解壓縮物件的副本。這可以用於在資料流中間儲存解壓縮器的狀態，以便在將來加速對資料流的隨機查詢。
在 3.8 版本中更改: 添加了對解壓縮物件的 copy.copy() 和 copy.deepcopy() 的支援。
有關正在使用的 zlib 庫版本的資訊可透過以下常量獲得
- zlib.ZLIB_VERSION¶
用於構建模組的 zlib 庫的版本字串。 這可能與實際在執行時使用的 zlib 庫不同，後者可透過
ZLIB_RUNTIME_VERSION獲取。
- zlib.ZLIB_RUNTIME_VERSION¶
直譯器實際載入的 zlib 庫的版本字串。
在 3.3 版本中新增。
另請參閱
- 模組
gzip 讀取和寫入 gzip 格式的檔案。
- http://www.zlib.net
zlib 庫主頁。
- http://www.zlib.net/manual.html
zlib 手冊解釋了庫的許多函式的語義和用法。