zlib --- 相容於 gzip 的壓縮

For applications that require data compression, the functions in this module allow compression and decompression, using the zlib library. The zlib library has its own home page at https://www.zlib.net. zlib 1.2.2.1 is the minium supported version.

zlib's functions have many options and often need to be used in a particular order. This documentation doesn't attempt to cover all of the permutations; consult the zlib manual for authoritative information.

若要讀寫 .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.adler32_combine(adler1, adler2, len2, /)

Combine two Adler-32 checksums into one.

Given the Adler-32 checksum adler1 of a sequence A and the Adler-32 checksum adler2 of a sequence B of length len2, return the Adler-32 checksum of A and B concatenated.

This function is typically useful to combine Adler-32 checksums that were concurrently computed. To compute checksums sequentially, use adler32() with the running checksum as the value argument.

在 3.15 版被加入.

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.crc32_combine(crc1, crc2, len2, /)

Combine two CRC-32 checksums into one.

Given the CRC-32 checksum crc1 of a sequence A and the CRC-32 checksum crc2 of a sequence B of length len2, return the CRC-32 checksum of A and B concatenated.

This function is typically useful to combine CRC-32 checksums that were concurrently computed. To compute checksums sequentially, use crc32() with the running checksum as the value argument.

在 3.15 版被加入.

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() 支援。

The following constants are available to configure compression and decompression behavior:

zlib.DEFLATED

The deflate compression method.

zlib.MAX_WBITS

The maximum window size, expressed as a power of 2. For example, if MAX_WBITS is 15 it results in a window size of 32 KiB.

zlib.DEF_MEM_LEVEL

The default memory level for compression objects.

zlib.DEF_BUF_SIZE

The default buffer size for decompression operations.

zlib.Z_NO_COMPRESSION

Compression level 0.

在 3.6 版被加入.

zlib.Z_BEST_SPEED

Compression level 1.

zlib.Z_BEST_COMPRESSION

Compression level 9.

zlib.Z_DEFAULT_COMPRESSION

Default compression level (-1).

zlib.Z_DEFAULT_STRATEGY

Default compression strategy, for normal data.

zlib.Z_FILTERED

Compression strategy for data produced by a filter (or predictor).

zlib.Z_HUFFMAN_ONLY

Compression strategy that forces Huffman coding only.

zlib.Z_RLE

Compression strategy that limits match distances to one (run-length encoding).

This constant is only available if Python was compiled with zlib 1.2.0.1 or greater.

在 3.6 版被加入.

zlib.Z_FIXED

Compression strategy that prevents the use of dynamic Huffman codes.

This constant is only available if Python was compiled with zlib 1.2.2.2 or greater.

在 3.6 版被加入.

zlib.Z_NO_FLUSH

Flush mode 0. No special flushing behavior.

在 3.6 版被加入.

zlib.Z_PARTIAL_FLUSH

Flush mode 1. Flush as much output as possible.

zlib.Z_SYNC_FLUSH

Flush mode 2. All output is flushed and the output is aligned to a byte boundary.

zlib.Z_FULL_FLUSH

Flush mode 3. All output is flushed and the compression state is reset.

zlib.Z_FINISH

Flush mode 4. All pending input is processed, no more input is expected.

zlib.Z_BLOCK

Flush mode 5. A deflate block is completed and emitted.

This constant is only available if Python was compiled with zlib 1.2.2.2 or greater.

在 3.6 版被加入.

zlib.Z_TREES

Flush mode 6, for inflate operations. Instructs inflate to return when it gets to the next deflate block boundary.

This constant is only available if Python was compiled with zlib 1.2.3.4 or greater.

在 3.6 版被加入.

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

zlib.ZLIB_VERSION

用於建置模組的 zlib 函式庫版本字串。這可能與實際在執行環境 (runtime) 使用的 zlib 函式庫不同，後者以 ZLIB_RUNTIME_VERSION 提供。

zlib.ZLIB_RUNTIME_VERSION

直譯器實際載入的 zlib 函式庫版本字串。

在 3.3 版被加入.

zlib.ZLIBNG_VERSION

The version string of the zlib-ng library that was used for building the module if zlib-ng was used. When present, the ZLIB_VERSION and ZLIB_RUNTIME_VERSION constants reflect the version of the zlib API provided by zlib-ng.

If zlib-ng was not used to build the module, this constant will be absent.

在 3.14 版被加入.

也參考

gzip 模組

讀寫 gzip 格式的檔案。

https://www.zlib.net

zlib 函式庫首頁。

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

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

In case gzip (de)compression is a bottleneck, the python-isal package speeds up (de)compression with a mostly compatible API.