zlib --- 與 gzip 兼容的壓縮?

對(duì)于需要數(shù)據(jù)壓縮的應(yīng)用，此模塊中的函數(shù)允許使用 zlib 庫(kù)進(jìn)行壓縮和解壓縮。 zlib 庫(kù)的項(xiàng)目主頁(yè)是 https://www.zlib.net。 已知此 Python 模塊與 1.1.3 之前版本的 zlib 庫(kù)存在不兼容；1.1.3 版則存在一個(gè) 安全缺陷，因此我們推薦使用 1.1.4 或更新的版本。

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

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

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

exception zlib.error?

在壓縮或解壓縮過程中發(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)值。此算法沒有加密強(qiáng)度，不應(yīng)用于身份驗(yàn)證和數(shù)字簽名。此算法的目的僅為驗(yàn)證數(shù)據(jù)的正確性，不適合作為通用散列算法。

在 3.0 版更改: The result is always unsigned.

zlib.compress(data, /, level=- 1, wbits=MAX_WBITS)?

Compresses the bytes in data, returning a bytes object containing compressed data. level is an integer from 0 to 9 or -1 controlling the level of compression; 1 (Z_BEST_SPEED) is fastest and produces the least compression, 9 (Z_BEST_COMPRESSION) is slowest and produces the most. 0 (Z_NO_COMPRESSION) is no compression. The default value is -1 (Z_DEFAULT_COMPRESSION). Z_DEFAULT_COMPRESSION represents a default compromise between speed and compression (currently equivalent to level 6).

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

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

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

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

Raises the error exception if any error occurs.

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

在 3.11 版更改: The wbits parameter is now available to set window bits and compression type.

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

返回一個(gè) 壓縮對(duì)象，用來壓縮內(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 表示壓縮算法。現(xiàn)在只支持 DEFLATED 這個(gè)算法。

The wbits parameter controls the size of the history buffer (or the "window size"), and what header and trailer format will be used. It has the same meaning as described for compress().

參數(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)值。此算法沒有加密強(qiáng)度，不應(yīng)用于身份驗(yàn)證和數(shù)字簽名。此算法的目的僅為驗(yàn)證數(shù)據(jù)的正確性，不適合作為通用散列算法。

在 3.0 版更改: The result is always unsigned.

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

解壓 data 中的字節(jié)，返回含有已解壓內(nèi)容的 bytes 對(duì)象。參數(shù) wbits 取決于 data 的格式，具體參見下邊的說明。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 至 ?15：使用 wbits 的絕對(duì)值作為窗口大小以二為底的對(duì)數(shù)。 輸入必須為原始數(shù)據(jù)流，沒有頭部和尾部。

• +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ì)象，用來解壓無法被一次性放入內(nèi)存的數(shù)據(jù)流。

wbits 形參控制歷史緩沖區(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ì)無法再次調(diào)用 compress()，此時(shí)只能刪除這個(gè)對(duì)象。

Compress.copy()?

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

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

Decompress.unused_data?

一個(gè) bytes 對(duì)象，其中包含壓縮數(shù)據(jù)結(jié)束之后的任何字節(jié)數(shù)據(jù)。 也就是說，它將為 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() 方法將無法被再次調(diào)用；唯一可行的操作是刪除該對(duì)象。

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

Decompress.copy()?

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

通過下列常量可獲取模塊所使用的 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 新版功能.