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 是從 09-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 是壓縮級別 -- 從 09-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 引數控制用於內部壓縮狀態的記憶體大小。有效值範圍為 19。較高的值會使用更多的記憶體,但速度更快並產生更小的輸出。

strategy 被用於調整壓縮演算法。可用的值為 Z_DEFAULT_STRATEGYZ_FILTEREDZ_HUFFMAN_ONLYZ_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 版的變更: wbitsbufsize 可以用作關鍵字引數。

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_FLUSHZ_PARTIAL_FLUSHZ_SYNC_FLUSHZ_FULL_FLUSHZ_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

一個布林值,代表是否已到達壓縮資料串流的尾末。

這使其能夠區分有正確建構的壓縮串流和不完整或被截斷的串流。

Added in version 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 函式庫版本字串。

Added in version 3.3.

也參考

gzip 模組

讀寫 gzip 格式的檔案。

http://www.zlib.net

zlib 函式庫首頁。

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

zlib 手冊解釋了函式庫中許多函式的語義和用法。