zlib --- 與 gzip 兼容的壓縮

---

此模塊為需要數(shù)據(jù)壓縮的程序提供了一系列函數(shù)，用于壓縮和解壓縮。這些函數(shù)使用了 zlib 庫(kù)。zlib 庫(kù)的項(xiàng)目主頁(yè)是 http://www.zlib.net. 版本低于 1.1.3 的 zlib 與此 Python 模塊之間存在已知的不兼容。1.1.3 版本的 zlib 存在一個(gè)安全漏洞，我們推薦使用 1.1.4 或更新的版本。

zlib 的函數(shù)有很多選項(xiàng)，一般需要按特定順序使用。本文檔沒(méi)有覆蓋全部的用法。更多詳細(xì)信息請(qǐng)于 http://www.zlib.net/manual.html 參閱官方手冊(cè)。

要讀寫 .gz 格式的文件，請(qǐng)參考 gzip 模塊。

此模塊中可用的異常和函數(shù)如下：

exception zlib.error

在壓縮或解壓縮過(guò)程中發(fā)生錯(cuò)誤時(shí)的異常。

zlib.adler32(data[, value])

計(jì)算 data 的 Adler-32 校驗(yàn)值。(Adler-32 校驗(yàn)的可靠性與 CRC32 基本相當(dāng)，但比計(jì)算 CRC32 更高效。) 計(jì)算的結(jié)果是一個(gè) 32 位的整數(shù)。參數(shù) value 是校驗(yàn)時(shí)的起始值，其默認(rèn)值為 1。借助參數(shù) value 可為分段的輸入計(jì)算校驗(yàn)值。此算法沒(méi)有加密強(qiáng)度，不應(yīng)用于身份驗(yàn)證和數(shù)字簽名。此算法的目的僅為驗(yàn)證數(shù)據(jù)的正確性，不適合作為通用散列算法。

在 3.0 版更改: 返回值永遠(yuǎn)是無(wú)符號(hào)數(shù)。要在所有的 Python 版本和平臺(tái)上獲得相同的值，請(qǐng)使用 adler32(data) & 0xffffffff。

zlib.compress(data, level=-1)

壓縮 data 中的字節(jié)，返回含有已壓縮內(nèi)容的 bytes 對(duì)象。參數(shù) level 為整數(shù)，可取值為 0 到 9 或 -1，用于指定壓縮等級(jí)。1 (Z_BEST_SPEED) 表示最快速度和最低壓縮率，9 (Z_BEST_COMPRESSION) 表示最慢速度和最高壓縮率。0 (Z_NO_COMPRESSION) 表示不壓縮。參數(shù)默認(rèn)值為 -1 (Z_DEFAULT_COMPRESSION)。Z_DEFAULT_COMPRESSION 是速度和壓縮率之間的平衡 (一般相當(dāng)于設(shè)壓縮等級(jí)為 6)。函數(shù)發(fā)生錯(cuò)誤時(shí)拋出 error 異常。

在 3.6 版更改: 現(xiàn)在，level 可作為關(guān)鍵字參數(shù)。

zlib.compressobj(level=-1, method=DEFLATED, wbits=MAX_WBITS, memLevel=DEF_MEM_LEVEL, strategy=Z_DEFAULT_STRATEGY[, zdict])

返回一個(gè) 壓縮對(duì)象，用來(lái)壓縮內(nèi)存中難以容下的數(shù)據(jù)流。

參數(shù) level 為壓縮等級(jí)，是整數(shù)，可取值為 0 到 9 或 -1。1 (Z_BEST_SPEED) 表示最快速度和最低壓縮率，9 (Z_BEST_COMPRESSION) 表示最慢速度和最高壓縮率。0 (Z_NO_COMPRESSION) 表示不壓縮。參數(shù)默認(rèn)值為 -1 (Z_DEFAULT_COMPRESSION)。Z_DEFAULT_COMPRESSION 是速度和壓縮率之間的平衡 (一般相當(dāng)于設(shè)壓縮等級(jí)為 6)。

method 表示壓縮算法?，F(xiàn)在只支持 DEFLATED 這個(gè)算法。

參數(shù) wbits 指定壓縮數(shù)據(jù)時(shí)所使用的歷史緩沖區(qū)的大小 (窗口大小)，并指定壓縮輸出是否包含頭部或尾部。參數(shù)的默認(rèn)值是 15 (MAX_WBITS)。參數(shù)的值分為幾個(gè)范圍：

• +9 到 +15：窗口大小以 2 為底的對(duì)數(shù)。即這些值對(duì)應(yīng)著 512 到 32768 的窗口大小。更大的值會(huì)提供更好的壓縮，同時(shí)內(nèi)存開(kāi)銷也會(huì)更大。壓縮輸出會(huì)包含 zlib 特定格式的頭部和尾部。

• ?9 到 ?15：絕對(duì)值為窗口大小以 2 為底的對(duì)數(shù)。壓縮輸出僅包含壓縮數(shù)據(jù)，沒(méi)有頭部和尾部。

• +25 到 +31 = 16 + (9 到 15)：后 4 個(gè)比特位為窗口大小以 2 為底的對(duì)數(shù)。壓縮輸出包含一個(gè)基本的 gzip 頭部，并以校驗(yàn)和為尾部。

參數(shù) memLevel 指定內(nèi)部壓縮操作時(shí)所占用內(nèi)存大小。參數(shù)取 1 到 9。更大的值占用更多的內(nèi)存，同時(shí)速度也更快輸出也更小。

參數(shù) strategy 用于調(diào)節(jié)壓縮算法?？扇≈禐? Z_DEFAULT_STRATEGY、Z_FILTERED、Z_HUFFMAN_ONLY、Z_RLE (zlib 1.2.0.1) 或 Z_FIXED (zlib 1.2.2.2)。

參數(shù) zdict 指定預(yù)定義的壓縮字典。它是一個(gè)字節(jié)序列 (如 bytes 對(duì)象)，其中包含用戶認(rèn)為要壓縮的數(shù)據(jù)中可能頻繁出現(xiàn)的子序列。頻率高的子序列應(yīng)當(dāng)放在字典的尾部。

在 3.3 版更改: 添加關(guān)鍵字參數(shù) zdict。

zlib.crc32(data[, value])

計(jì)算 data 的 CRC (循環(huán)冗余校驗(yàn)) 值。計(jì)算的結(jié)果是一個(gè) 32 位的整數(shù)。參數(shù) value 是校驗(yàn)時(shí)的起始值，其默認(rèn)值為 0。借助參數(shù) value 可為分段的輸入計(jì)算校驗(yàn)值。此算法沒(méi)有加密強(qiáng)度，不應(yīng)用于身份驗(yàn)證和數(shù)字簽名。此算法的目的僅為驗(yàn)證數(shù)據(jù)的正確性，不適合作為通用散列算法。

在 3.0 版更改: 返回值永遠(yuǎn)是無(wú)符號(hào)數(shù)。要在所有的 Python 版本和平臺(tái)上獲得相同的值，請(qǐng)使用 crc32(data) & 0xffffffff。

zlib.decompress(data, wbits=MAX_WBITS, bufsize=DEF_BUF_SIZE)

解壓 data 中的字節(jié)，返回含有已解壓內(nèi)容的 bytes 對(duì)象。參數(shù) wbits 取決于 data 的格式，具體參見(jiàn)下邊的說(shuō)明。bufsize 為輸出緩沖區(qū)的起始大小。函數(shù)發(fā)生錯(cuò)誤時(shí)拋出 error 異常。

wbits 形參控制歷史緩沖區(qū)（或稱“窗口尺寸”）的大小以及所期望的頭部和尾部格式。 它類似于 compressobj() 的形參，但可接受更大范圍的值：

• +8 至 +15：窗口尺寸以二為底的對(duì)數(shù)。 輸入必須包含 zlib 頭部和尾部。

• 0：根據(jù) zlib 頭部自動(dòng)確定窗口大小。 只從 zlib 1.2.3.5 版起受支持。

• ?8 to ?15：使用 wbits 的絕對(duì)值作為窗口大小以二為底的對(duì)數(shù)。 輸入必須為原始數(shù)據(jù)流，沒(méi)有頭部和尾部。

• +24 至 +31 = 16 + (8 至 15)：使用后 4 個(gè)比特位作為窗口大小以二為底的對(duì)數(shù)。 輸入必須包括 gzip 頭部和尾部。

• +40 至 +47 = 32 + (8 至 15)：使用后 4 個(gè)比特位作為窗口大小以二為底的對(duì)數(shù)，并且自動(dòng)接受 zlib 或 gzip 格式。

當(dāng)解壓縮一個(gè)數(shù)據(jù)流時(shí)，窗口大小必須不小于用于壓縮數(shù)據(jù)流的原始窗口大?。皇褂锰〉闹悼赡軐?dǎo)致 error 異常。 默認(rèn) wbits 值對(duì)應(yīng)于最大的窗口大小并且要求包括 zlib 頭部和尾部。

bufsize 是用于存放解壓數(shù)據(jù)的緩沖區(qū)初始大小。 如果需要更大空間，緩沖區(qū)大小將按需增加，因此你不需要讓這個(gè)值完全精確；對(duì)其進(jìn)行調(diào)整僅會(huì)節(jié)省一點(diǎn)對(duì) malloc() 的調(diào)用次數(shù)。

在 3.6 版更改: wbits 和 bufsize 可用作關(guān)鍵字參數(shù)。

zlib.decompressobj(wbits=MAX_WBITS[, zdict])

返回一個(gè)解壓對(duì)象，用來(lái)解壓無(wú)法被一次性放入內(nèi)存的數(shù)據(jù)流。

wbits 形參控制歷史緩沖區(qū)的大?。ɑ蚍Q“窗口大小”）以及所期望的頭部和尾部格式。 它的含義與 對(duì) decompress() 的描述 相同。

zdict 形參指定指定一個(gè)預(yù)定義的壓縮字典。 如果提供了此形參，它必須與產(chǎn)生將解壓數(shù)據(jù)的壓縮器所使用的字典相同。

注解

如果 zdict 是一個(gè)可變對(duì)象 (例如 bytearray)，則你不可在對(duì) decompressobj() 的調(diào)用和對(duì)解壓器的 decompress() 方法的調(diào)用之間修改其內(nèi)容。

在 3.3 版更改: 增加了 zdict 形參。

壓縮對(duì)象支持以下方法：

Compress.compress(data)

壓縮 data 并返回 bytes 對(duì)象，這個(gè)對(duì)象含有 data 的部分或全部?jī)?nèi)容的已壓縮數(shù)據(jù)。所得的對(duì)象必須拼接在上一次調(diào)用 compress() 方法所得數(shù)據(jù)的后面。緩沖區(qū)中可能留存部分輸入以供下一次調(diào)用。

Compress.flush([mode])

壓縮所有緩沖區(qū)的數(shù)據(jù)并返回已壓縮的數(shù)據(jù)。參數(shù) mode 可以傳入的常量為：Z_NO_FLUSH、Z_PARTIAL_FLUSH、Z_SYNC_FLUSH、Z_FULL_FLUSH、Z_BLOCK (zlib 1.2.3.4) 或 Z_FINISH。默認(rèn)值為 Z_FINISH。Z_FINISH 關(guān)閉已壓縮數(shù)據(jù)流并不允許再壓縮其他數(shù)據(jù)，Z_FINISH 以外的值皆允許這個(gè)對(duì)象繼續(xù)壓縮數(shù)據(jù)。調(diào)用 flush() 方法并將 mode 設(shè)為 Z_FINISH 后會(huì)無(wú)法再次調(diào)用 compress()，此時(shí)只能刪除這個(gè)對(duì)象。

Compress.copy()

返回此壓縮對(duì)象的一個(gè)拷貝。它可以用來(lái)高效壓縮一系列擁有相同前綴的數(shù)據(jù)。

解壓縮對(duì)象支持以下方法：

Decompress.unused_data

一個(gè) bytes 對(duì)象，其中包含壓縮數(shù)據(jù)結(jié)束之后的任何字節(jié)數(shù)據(jù)。 也就是說(shuō)，它將為 b"" 直到包含壓縮數(shù)據(jù)的末尾字節(jié)可用。 如果整個(gè)結(jié)果字節(jié)串都包含壓縮數(shù)據(jù)，它將為一個(gè)空的 bytes 對(duì)象 b""。

Decompress.unconsumed_tail

一個(gè) bytes 對(duì)象，其中包含未被上一次 decompress() 調(diào)用所消耗的任何數(shù)據(jù)。 此數(shù)據(jù)不能被 zlib 機(jī)制看到，因此你必須將其送回（可能要附帶額外的數(shù)據(jù)拼接）到后續(xù)的 decompress() 方法調(diào)用以獲得正確的輸出。

Decompress.eof

一個(gè)布爾值，指明是否已到達(dá)壓縮數(shù)據(jù)流的末尾。

這使得區(qū)分正確構(gòu)造的壓縮數(shù)據(jù)流和不完整或被截?cái)嗟膲嚎s數(shù)據(jù)流成為可能。

3.3 新版功能.

Decompress.decompress(data, max_length=0)

解壓縮 data 并返回 bytes 對(duì)象，其中包含對(duì)應(yīng)于 string 中至少一部分?jǐn)?shù)據(jù)的解壓縮數(shù)據(jù)。 此數(shù)據(jù)應(yīng)當(dāng)被拼接到之前任何對(duì) decompress() 方法的調(diào)用所產(chǎn)生的輸出。 部分輸入數(shù)據(jù)可能會(huì)被保留在內(nèi)部緩沖區(qū)以供后續(xù)處理。

如果可選的形參 max_length 非零則返回值將不會(huì)長(zhǎng)于 max_length。 這可能意味著不是所有已壓縮輸入都能被處理；并且未被消耗的數(shù)據(jù)將被保存在 unconsumed_tail 屬性中。 如果要繼續(xù)解壓縮則這個(gè)字節(jié)串必須被傳給對(duì) decompress() 的后續(xù)調(diào)用。 如果 max_length 為零則整個(gè)輸入都會(huì)被解壓縮，并且 unconsumed_tail 將為空。

在 3.6 版更改: max_length 可用作關(guān)鍵字參數(shù)。

Decompress.flush([length])

所有掛起的輸入會(huì)被處理，并且返回包含剩余未壓縮輸出的 bytes 對(duì)象。 在調(diào)用 flush() 之后，decompress() 方法將無(wú)法被再次調(diào)用；唯一可行的操作是刪除該對(duì)象。

可選的形參 length 設(shè)置輸出緩沖區(qū)的初始大小。

Decompress.copy()

返回解壓縮對(duì)象的一個(gè)拷貝。 它可以用來(lái)在數(shù)據(jù)流的中途保存解壓縮器的狀態(tài)以便加快隨機(jī)查找數(shù)據(jù)流后續(xù)位置的速度。

通過(guò)下列常量可獲取模塊所使用的 zlib 庫(kù)的版本信息：

zlib.ZLIB_VERSION

構(gòu)建此模塊時(shí)所用的 zlib 庫(kù)的版本字符串。它的值可能與運(yùn)行時(shí)所加載的 zlib 不同。運(yùn)行時(shí)加載的 zlib 庫(kù)的版本字符串為 ZLIB_RUNTIME_VERSION。

zlib.ZLIB_RUNTIME_VERSION

解釋器所加載的 zlib 庫(kù)的版本字符串。

3.3 新版功能.

參見(jiàn)

模塊 gzip

讀寫 gzip 格式的文件。

http://www.zlib.net

zlib 庫(kù)項(xiàng)目主頁(yè)。

http://www.zlib.net/manual.html

zlib 庫(kù)用戶手冊(cè)。提供了庫(kù)的許多功能的解釋和用法。