"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 手冊解釋了函式庫中許多函式的語義和用法。
