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

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

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

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

此模塊中可用的異常和函數如下：

exception zlib.error?

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

zlib.adler32(data[, value])?

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

在 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).

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

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

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

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

Raises the error exception if any error occurs.

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

在 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è) 壓縮對象，用來(lái)壓縮內存中難以容下的數據流。

參數 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 表示壓縮算法?，F在只支持 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().

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

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

參數 zdict 指定預定義的壓縮字典。它是一個(gè)字節序列 (如 bytes 對象)，其中包含用戶(hù)認為要壓縮的數據中可能頻繁出現的子序列。頻率高的子序列應當放在字典的尾部。

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

zlib.crc32(data[, value])?

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

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

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

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

wbits 形參控制歷史緩沖區的大?。ɑ蚍Q(chēng)“窗口大小”）以及所期望的頭部和尾部格式。 它類(lèi)似于 compressobj() 的形參，但可接受更大范圍的值：

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

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

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

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

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

當解壓縮一個(gè)數據流時(shí)，窗口大小必須不小于用于壓縮數據流的原始窗口大??；使用太小的值可能導致 error 異常。 默認 wbits 值對應于最大的窗口大小并且要求包括 zlib 頭部和尾部。

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

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

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

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

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

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

備注

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

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

壓縮對象支持以下方法：

Compress.compress(data)?

壓縮 data 并返回 bytes 對象，這個(gè)對象含有 data 的部分或全部?jì)热莸囊褖嚎s數據。所得的對象必須拼接在上一次調用 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 關(guān)閉已壓縮數據流并不允許再壓縮其他數據，Z_FINISH 以外的值皆允許這個(gè)對象繼續壓縮數據。調用 flush() 方法并將 mode 設為 Z_FINISH 后會(huì )無(wú)法再次調用 compress()，此時(shí)只能刪除這個(gè)對象。

Compress.copy()?

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

解壓縮對象支持以下方法：

Decompress.unused_data?

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

Decompress.unconsumed_tail?

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

Decompress.eof?

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

這使得區分正確構造的壓縮數據流和不完整或被截斷的壓縮數據流成為可能。

3.3 新版功能.

Decompress.decompress(data, max_length=0)?

解壓縮 data 并返回 bytes 對象，其中包含對應于 string 中至少一部分數據的解壓縮數據。 此數據應當被拼接到之前任何對 decompress() 方法的調用所產(chǎn)生的輸出。 部分輸入數據可能會(huì )被保留在內部緩沖區以供后續處理。

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

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

Decompress.flush([length])?

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

可選的形參 length 設置輸出緩沖區的初始大小。

Decompress.copy()?

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

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

zlib.ZLIB_VERSION?

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

zlib.ZLIB_RUNTIME_VERSION?

解釋器所加載的 zlib 庫的版本字符串。

3.3 新版功能.