"zlib" --- 相容於 **gzip** 的壓縮
*********************************

======================================================================

For applications that require data compression, the functions in this
module allow compression and decompression, using the zlib library.

This is an *optional module*. If it is missing from your copy of
CPython, look for documentation from your distributor (that is,
whoever provided Python to you). If you are the distributor, see 可選
模組的需求.

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.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=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.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" 或 "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()"
   方法所產生的輸出。一些輸入資料可能會保存在內部緩衝區中以供後續處理
   。

   If the optional parameter *max_length* is non-zero then the return
   value will be no longer than *max_length*. This may mean that not
   all of the compressed input can be processed; and unconsumed data
   will be stored in the attribute "unconsumed_tail". This bytestring
   must be passed to a subsequent call to "decompress()" if
   decompression is to continue.  If *max_length* is zero then the
   whole input is decompressed, and "unconsumed_tail" is empty. For
   example, the full content could be read like:

      process_output(d.decompress(data, max_length))
      while chunk := d.decompress(d.unconsumed_tail, max_length):
          process_output(chunk)

   在 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

   壓縮物件的預設記憶體層級。

zlib.DEF_BUF_SIZE

   解壓縮操作的預設緩衝區大小。

zlib.Z_NO_COMPRESSION

   壓縮等級 "0"；不壓縮。

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