# `zlib` --- 相容於 gzip 的壓縮

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

zlib 的函式有很多選項，且通常需要按特定順序使用。本文件並不打算解說所有選項排列組合的效果；相關官方資訊，請參閱 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=Z_DEFAULT_COMPRESSION, wbits=MAX_WBITS)

  壓縮 data 中的位元組，回傳一個包含壓縮資料的位元組物件。 level 是從 `0` 到 `9` 或 `-1` 的整數，控制了壓縮的級別；請見 `Z_BEST_SPEED` (`1`)、`Z_BEST_COMPRESSION` (`9`)、`Z_NO_COMPRESSION` (`0`)，以及預設值 `Z_DEFAULT_COMPRESSION` (`-1`) 以得到更多關於這些值的資訊。

  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=Z_DEFAULT_COMPRESSION, method=DEFLATED, wbits=MAX_WBITS, memLevel=DEF_MEM_LEVEL, strategy=Z_DEFAULT_STRATEGY[, zdict])

  回傳一個壓縮物件，用於壓縮不能一次全部放入記憶體中的資料串流。

  level is the compression level -- an integer from `0` to `9` or `-1`. See `Z_BEST_SPEED` (`1`), `Z_BEST_COMPRESSION` (`9`), `Z_NO_COMPRESSION` (`0`), and the default, `Z_DEFAULT_COMPRESSION` (`-1`) for more information about these values.

  method 代表壓縮演算法。目前唯一支援的值是 `DEFLATED`。

  wbits 參數控制歷史紀錄緩衝區的大小（或「視窗大小」），以及將使用的標頭和尾末格式。它與前面敘述的 compress() 具有相同的含義。

  memLevel 引數控制用於內部壓縮狀態的記憶體大小。有效值範圍為 `1` 到 `9`。較高的值會使用更多的記憶體，但速度更快並產生更小的輸出。

  strategy 被用於調整壓縮演算法。可用的值為 `Z_DEFAULT_STRATEGY`、`Z_FILTERED`、`Z_HUFFMAN_ONLY`、`Z_RLE` 和 `Z_FIXED`。

  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` 或 `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`; no compression.

  在 3.6 版被加入.

zlib.Z_BEST_SPEED

  Compression level `1`; fastest and produces the least compression.

zlib.Z_BEST_COMPRESSION

  Compression level `9`; slowest and produces the most compression.

zlib.Z_DEFAULT_COMPRESSION

  Default compression level (`-1`); a compromise between speed and compression. Currently equivalent to compression level `6`.

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.