zlib --- 與 gzip 兼容的壓縮?
此模塊為需要數據壓縮的程序提供了一系列函數，用于壓縮和解壓縮。這些函數使用了 zlib 庫。zlib 庫的項目主頁是 http://www.zlib.net. 版本低于 1.1.3 的 zlib 與此 Python 模塊之間存在已知的不兼容。1.1.3 版本的 zlib 存在一個安全漏洞，我們推薦使用 1.1.4 或更新的版本。
zlib 的函數有很多選項，一般需要按特定順序使用。本文檔沒有覆蓋全部的用法。更多詳細信息請于 http://www.zlib.net/manual.html 參閱官方手冊。
要讀寫 .gz 格式的文件，請參考 gzip 模塊。
此模塊中可用的異常和函數如下：
-
exception
zlib.error? 在壓縮或解壓縮過程中發生錯誤時的異常。
-
zlib.adler32(data[, value])? 計算 data 的 Adler-32 校驗值。(Adler-32 校驗的可靠性與 CRC32 基本相當，但比計算 CRC32 更高效。) 計算的結果是一個 32 位的整數。參數 value 是校驗時的起始值，其默認值為 1。借助參數 value 可為分段的輸入計算校驗值。此算法沒有加密強度，不應用于身份驗證和數字簽名。此算法的目的僅為驗證數據的正確性，不適合作為通用散列算法。
在 3.0 版更改: 返回值永遠是無符號數。要在所有的 Python 版本和平臺上獲得相同的值，請使用
adler32(data) & 0xffffffff。
-
zlib.compress(data, level=-1)? 壓縮 data 中的字節，返回含有已壓縮內容的 bytes 對象。參數 level 為整數，可取值為
0到9或-1，用于指定壓縮等級。1(Z_BEST_SPEED) 表示最快速度和最低壓縮率，9(Z_BEST_COMPRESSION) 表示最慢速度和最高壓縮率。0(Z_NO_COMPRESSION) 表示不壓縮。參數默認值為-1(Z_DEFAULT_COMPRESSION)。Z_DEFAULT_COMPRESSION 是速度和壓縮率之間的平衡 (一般相當于設壓縮等級為 6)。函數發生錯誤時拋出error異常。在 3.6 版更改: 現在，level 可作為關鍵字參數。
-
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 指定壓縮數據時所使用的歷史緩沖區的大小 (窗口大小)，并指定壓縮輸出是否包含頭部或尾部。參數的默認值是
15(MAX_WBITS)。參數的值分為幾個范圍：+9 到 +15：窗口大小以 2 為底的對數。即這些值對應著 512 到 32768 的窗口大小。更大的值會提供更好的壓縮，同時內存開銷也會更大。壓縮輸出會包含 zlib 特定格式的頭部和尾部。
?9 到 ?15：絕對值為窗口大小以 2 為底的對數。壓縮輸出僅包含壓縮數據，沒有頭部和尾部。
+25 到 +31 = 16 + (9 到 15)：后 4 個比特位為窗口大小以 2 為底的對數。壓縮輸出包含一個基本的 gzip 頭部，并以校驗和為尾部。
參數 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 版更改: 返回值永遠是無符號數。要在所有的 Python 版本和平臺上獲得相同的值，請使用
crc32(data) & 0xffffffff。
-
zlib.decompress(data, wbits=MAX_WBITS, bufsize=DEF_BUF_SIZE)? 解壓 data 中的字節，返回含有已解壓內容的 bytes 對象。參數 wbits 取決于 data 的格式，具體參見下邊的說明。bufsize 為輸出緩沖區的起始大小。函數發生錯誤時拋出
error異常。wbits 形參控制歷史緩沖區（或稱“窗口尺寸”）的大小以及所期望的頭部和尾部格式。 它類似于
compressobj()的形參，但可接受更大范圍的值：+8 至 +15：窗口尺寸以二為底的對數。 輸入必須包含 zlib 頭部和尾部。
0：根據 zlib 頭部自動確定窗口大小。 只從 zlib 1.2.3.5 版起受支持。
?8 to ?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 并返回 bytes 對象，這個對象含有 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()? 返回此壓縮對象的一個拷貝。它可以用來高效壓縮一系列擁有相同前綴的數據。
解壓縮對象支持以下方法：
-
Decompress.unused_data? 一個 bytes 對象，其中包含壓縮數據結束之后的任何字節數據。 也就是說，它將為
b""直到包含壓縮數據的末尾字節可用。 如果整個結果字節串都包含壓縮數據，它將為一個空的 bytes 對象b""。
-
Decompress.unconsumed_tail? 一個 bytes 對象，其中包含未被上一次
decompress()調用所消耗的任何數據。 此數據不能被 zlib 機制看到，因此你必須將其送回（可能要附帶額外的數據拼接）到后續的decompress()方法調用以獲得正確的輸出。
-
Decompress.eof? 一個布爾值，指明是否已到達壓縮數據流的末尾。
這使得區分正確構造的壓縮數據流和不完整或被截斷的壓縮數據流成為可能。
3.3 新版功能.
-
Decompress.decompress(data, max_length=0)? 解壓縮 data 并返回 bytes 對象，其中包含對應于 string 中至少一部分數據的解壓縮數據。 此數據應當被拼接到之前任何對
decompress()方法的調用所產生的輸出。 部分輸入數據可能會被保留在內部緩沖區以供后續處理。如果可選的形參 max_length 非零則返回值將不會長于 max_length。 這可能意味著不是所有已壓縮輸入都能被處理；并且未被消耗的數據將被保存在
unconsumed_tail屬性中。 如果要繼續解壓縮則這個字節串必須被傳給對decompress()的后續調用。 如果 max_length 為零則整個輸入都會被解壓縮，并且unconsumed_tail將為空。在 3.6 版更改: max_length 可用作關鍵字參數。
-
Decompress.flush([length])? 所有掛起的輸入會被處理，并且返回包含剩余未壓縮輸出的 bytes 對象。 在調用
flush()之后，decompress()方法將無法被再次調用；唯一可行的操作是刪除該對象。可選的形參 length 設置輸出緩沖區的初始大小。
-
Decompress.copy()? 返回解壓縮對象的一個拷貝。 它可以用來在數據流的中途保存解壓縮器的狀態以便加快隨機查找數據流后續位置的速度。
通過下列常量可獲取模塊所使用的 zlib 庫的版本信息：
-
zlib.ZLIB_VERSION? 構建此模塊時所用的 zlib 庫的版本字符串。它的值可能與運行時所加載的 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 庫用戶手冊。提供了庫的許多功能的解釋和用法。