zlib — 相容 gzip 的壓縮¶
對於需要資料壓縮的應用程式，此模組中的函式可以使用 zlib 庫進行壓縮和解壓縮。zlib 庫有自己的主頁：https://www.zlib.net。Python 模組與 1.1.3 之前版本的 zlib 庫之間存在已知的不相容性；1.1.3 存在安全漏洞，因此我們建議使用 1.1.4 或更高版本。
zlib 的函式有很多選項，並且通常需要按特定順序使用。本文件不試圖涵蓋所有可能的組合；請查閱zlib 手冊以獲取權威資訊。
有關讀取和寫入 .gz 檔案，請參見 gzip 模組。
此模組中可用的異常和函式是
- exception 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.DEFLATED¶
deflate 壓縮方法。
- zlib.MAX_WBITS¶
最大視窗大小，表示為 2 的冪。例如，如果
MAX_WBITS為15，則視窗大小為32 KiB。
- zlib.DEF_MEM_LEVEL¶
壓縮物件的預設記憶體級別。
- zlib.DEF_BUF_SIZE¶
解壓縮操作的預設緩衝區大小。
- zlib.Z_NO_COMPRESSION¶
壓縮級別
0。在 3.6 版本加入。
- zlib.Z_BEST_SPEED¶
壓縮級別
1。
- zlib.Z_BEST_COMPRESSION¶
壓縮級別
9。
- zlib.Z_DEFAULT_COMPRESSION¶
預設壓縮級別 (
-1)。
- zlib.Z_DEFAULT_STRATEGY¶
預設壓縮策略，用於普通資料。
- zlib.Z_FILTERED¶
用於過濾器（或預測器）生成的資料的壓縮策略。
- zlib.Z_HUFFMAN_ONLY¶
僅強制哈夫曼編碼的壓縮策略。
- zlib.Z_RLE¶
將匹配距離限制為 1 的壓縮策略（行程長度編碼）。
此常量僅在 Python 用 zlib 1.2.0.1 或更高版本編譯時可用。
在 3.6 版本加入。
- zlib.Z_FIXED¶
阻止使用動態哈夫曼編碼的壓縮策略。
此常量僅在 Python 用 zlib 1.2.2.2 或更高版本編譯時可用。
在 3.6 版本加入。
- zlib.Z_NO_FLUSH¶
重新整理模式
0。沒有特殊的重新整理行為。在 3.6 版本加入。
- zlib.Z_PARTIAL_FLUSH¶
重新整理模式
1。儘可能多地重新整理輸出。
- zlib.Z_SYNC_FLUSH¶
重新整理模式
2。所有輸出都被重新整理，並且輸出與位元組邊界對齊。
- zlib.Z_FULL_FLUSH¶
重新整理模式
3。所有輸出都被重新整理，並且壓縮狀態被重置。
- zlib.Z_FINISH¶
重新整理模式
4。所有待處理的輸入都已處理，不再期望更多輸入。
- zlib.Z_BLOCK¶
重新整理模式
5。deflate 塊已完成並輸出。此常量僅在 Python 用 zlib 1.2.2.2 或更高版本編譯時可用。
在 3.6 版本加入。
- zlib.Z_TREES¶
重新整理模式
6，用於 inflate 操作。指示 inflate 在到達下一個 deflate 塊邊界時返回。此常量僅在 Python 用 zlib 1.2.3.4 或更高版本編譯時可用。
在 3.6 版本加入。
有關正在使用的 zlib 庫版本的資訊可透過以下常量獲取
- zlib.ZLIB_VERSION¶
用於構建模組的 zlib 庫的版本字串。這可能與實際執行時使用的 zlib 庫不同，後者可用作
ZLIB_RUNTIME_VERSION。
- zlib.ZLIB_RUNTIME_VERSION¶
直譯器實際載入的 zlib 庫的版本字串。
在 3.3 版本加入。
- zlib.ZLIBNG_VERSION¶
如果使用了 zlib-ng，則為用於構建模組的 zlib-ng 庫的版本字串。當存在時，
ZLIB_VERSION和ZLIB_RUNTIME_VERSION常量反映 zlib-ng 提供的 zlib API 的版本。如果未使用 zlib-ng 構建模組，則此常量將不存在。
在 3.14 版本加入。
參見
- 模組
gzip 讀取和寫入 gzip 格式檔案。
- https://www.zlib.net
zlib 庫主頁。
- https://www.zlib.net/manual.html
zlib 手冊解釋了該庫眾多函式的語義和用法。
如果 gzip（解）壓縮是瓶頸，python-isal 包以大致相容的 API 加速（解）壓縮。