zlib --- 相容於 gzip 的壓縮

---

對於需要資料壓縮的應用程式，此模組提供了能夠使用 zlib 函式庫進行壓縮和解壓縮的函式。zlib 函式庫有自己的主頁 https://www.zlib.net。已知 Python 模組與早於 1.1.3 的 zlib 函式庫版本之間並不相容；1.1.3 存在安全漏洞，因此我們建議使用 1.1.4 或更新的版本。

zlib 的函式有很多選項，且通常需要按特定順序使用。本文件並不打算解說所有選項排列組合的效果；相關官方資訊，請參閱 http://www.zlib.net/manual.html 上的 zlib 手冊。

若要讀寫 .gz 文件，請參閱 gzip 模組。

該模組中可用的例外和函式是：

exception zlib.error

當壓縮和解壓縮發生錯誤時引發的例外。

zlib.adler32(data[, value])

計算 data 的 Adler-32 核對和 (checksum)。（Adler-32 核對和幾乎與 CRC32 一樣可靠，但計算速度更快。）結果是一個 unsigned（無符號的）32-bit 整數。如果有提供 value，則將其用作核對和的起始值，否則使用預設值 1。傳入 value 允許了於多個輸入的串聯 (concatenation) 上計算核對和。該演算法的加密強度不夠高，不該用於身份驗證 (authentication) 或數位簽章 (digital signature)。由於該演算法是為核對和演算法而設計的，它並不適合作為通用的雜湊演算法。

在 3.0 版的變更: 結果總是為 unsigned。

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 引數控制了壓縮資料時所使用的歷史紀錄緩衝區 (history buffer) 大小（或「視窗大小」），以及輸出中是否包含標題和尾末 (trailer)。它可以採用多個值的範圍，預設為 15 (MAX_WBITS)：

• +9 到 +15：視窗大小的以二為底的對數，因此範圍在 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（Cyclic Redundancy Check，循環冗餘核對）核對和，結果會是一個 unsigned 32-bit 整數。如果 value 存在，則將其用作核對和的起始值，否則使用預設值 0。傳入 value 允許在多個輸入的串聯上計算核對和。該演算法的加密強度不夠高，不該用於身份驗證或數位簽章。由於該演算法是為核對和演算法而設計的，它並不適合作為通用的雜湊演算法。

在 3.0 版的變更: 結果總是為 unsigned。

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

解壓縮 data 中的位元組，回傳包含未壓縮資料的位元組物件。 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 是一個可變物件 (mutable object)（例如一個 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 會完成壓縮串流並同時防止壓縮更多資料。在 mode 設定為 Z_FINISH 的情況下呼叫 flush() 後，無法再次呼叫 compress() 方法；唯一可行的作法是刪除物件。

Compress.copy()

回傳壓縮物件的副本，這可用於有效壓縮一組共用初始前綴的資料。

在 3.8 版的變更: 於壓縮物件新增對 copy.copy() 和 copy.deepcopy() 的支援。

解壓縮物件支援以下方法和屬性：

Decompress.unused_data

一個位元組物件，它包含壓縮資料結束之後的任何位元組。也就是說，在包含壓縮資料的最後一個位元組可用之前，它會一直保持為 b""。如果整個位元組字串 (bytestring) 有包含壓縮資料，這會是 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()

回傳解壓物件的副本，這可用於在資料串流中途保存解壓縮器的狀態，以便在未來某個時間點加速對串流的隨機搜索 (random seek)。

在 3.8 版的變更: 於解壓縮物件新增對 copy.copy() 和 copy.deepcopy() 支援。

有關正在使用的 zlib 函式庫版本資訊可通過以下常數獲得：

zlib.ZLIB_VERSION

用於建置模組的 zlib 函式庫版本字串。這可能與實際在執行環境 (runtime) 使用的 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 手冊解釋了函式庫中許多函式的語義和用法。