"zlib" --- 与 **gzip** 兼容的压缩
*********************************

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

对于需要数据压缩的应用程序，此模块中的函数可以执行压缩和解压缩操作，使
用 zlib 库。

这是一个 *optional module*。 如果它在你的 CPython 副本中缺失，请查看你
的发行方（也就是说，向你提供 Python 的人）的文档。 如果你就是发行方，
请参阅 针对可选模块的要求。

zlib 的函数有很多选项并且往往需要按特定顺序来使用。 本文档不试图覆盖所
有使用组合；请参看 zlib 手册 来获取权威信息。

要读写 ".gz" 格式的文件，请参考 "gzip" 模块。

此模块中可用的异常和函数如下：

exception zlib.error

   在压缩或解压缩过程中发生错误时的异常。

zlib.adler32(data[, value])

   计算 *data* 的 Adler-32 校验值。(Adler-32 校验的可靠性与 CRC32 基本
   相当，但比计算 CRC32 更高效。) 计算的结果是一个无符号 32 位的整数。
   参数 *value* 是校验时的起始值，其默认值为 1。借助参数 *value* 可为
   分段的输入计算校验值。此算法没有加密强度，不应用于身份验证和数字签
   名。此算法的目的仅为验证数据的正确性，不适合作为通用散列算法。

   在 3.0 版本发生变更: 结果将总是不带符号的。

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.

   Added in version 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* 控制压缩数据时所使用的历史缓冲区大小（或称“窗口大小”）
   ，以及输出中是否包括头部和尾部。 它可以接受几个范围内的值，默认值为
   "15" ("MAX_WBITS"):

   * +9 至 +15：窗口大小以二为底的对数。 即这些值对应着 512 至 32768
     的窗口大小。 更大的值会提供更好的压缩，同时内存开销也会更大。 压
     缩输出会包含 zlib 特定格式的头部和尾部。

   * −9 至 −15：绝对值为窗口大小以二为底的对数。 压缩输出仅包含压缩数
     据，没有头部和尾部。

   * +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* 为压缩级别 -- 一个 "0" 到 "9" 之间的整数或 "-1"。 请参阅
   "Z_BEST_SPEED" ("1"), "Z_BEST_COMPRESSION" ("9"),
   "Z_NO_COMPRESSION" ("0") 及默认值 "Z_DEFAULT_COMPRESSION" ("-1") 了
   解有关这些值的详情。

   *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 (循环冗余校验) 值。计算的结果是一个无符号 32 位
   的整数。参数 *value* 是校验时的起始值，其默认值为 0。借助参数
   *value* 可为分段的输入计算校验值。此算法没有加密强度，不应用于身份
   验证和数字签名。此算法的目的仅为验证数据的正确性，不适合作为通用散
   列算法。

   在 3.0 版本发生变更: 结果将总是不带符号的。

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.

   Added in version 3.15.

zlib.decompress(data, /, wbits=MAX_WBITS, bufsize=DEF_BUF_SIZE)

   解压 *data* 中的字节，返回含有已解压内容的 bytes 对象。参数 *wbits*
   取决于 *data* 的格式，具体参见下边的说明。*bufsize* 为输出缓冲区的
   起始大小。函数发生错误时抛出 "error" 异常。

   *wbits* 形参控制历史缓冲区的大小（或称“窗口大小”）以及所期望的头部
   和尾部格式。 它类似于 "compressobj()" 的形参，但可接受更大范围的值
   ：

   * +8 至 +15：窗口尺寸以二为底的对数。 输入必须包含 zlib 头部和尾部
     。

   * 0：根据 zlib 头部自动确定窗口大小。 只从 zlib 1.2.3.5 版起受支持
     。

   * −8 至 −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* 是一个可变对象 (例如 "bytearray")，则你不可在对
     "decompressobj()" 的调用和对解压器的 "decompress()" 方法的调用之
     间修改其内容。

   在 3.3 版本发生变更: 增加了 *zdict* 形参。

压缩对象支持以下方法：

Compress.compress(data)

   压缩 *data* 并返回 bytes 对象，这个对象含有 *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"
   将关闭已压缩流并阻止再压缩更多数据。 在调用 "flush()" 并将 *mode*
   设为 "Z_FINISH" 之后，"compress()" 方法将无法被再次调用；唯一可做的
   操作就是删除该对象。

Compress.copy()

   返回此压缩对象的一个拷贝。它可以用来高效压缩一系列拥有相同前缀的数
   据。

在 3.8 版本发生变更: 添加了对压缩对象执行 "copy.copy()" 和
"copy.deepcopy()" 的支持。

解压缩对象支持以下方法和属性：

Decompress.unused_data

   一个 bytes 对象，其中包含压缩数据结束之后的任何字节数据。 也就是说
   ，它将为 "b""" 直到包含压缩数据的末尾字节可用。 如果整个结果字节串
   都包含压缩数据，它将为一个空的 bytes 对象 "b"""。

Decompress.unconsumed_tail

   一个 bytes 对象，其中包含未被上一次 "decompress()" 调用所消耗的任何
   数据。 此数据不能被 zlib 机制看到，因此你必须将其送回（可能要附带额
   外的数据拼接）到后续的 "decompress()" 方法调用以获得正确的输出。

Decompress.eof

   一个布尔值，指明是否已到达压缩数据流的末尾。

   这使得区分正确构造的压缩数据流和不完整或被截断的流成为可能。

   Added in version 3.3.

Decompress.decompress(data, max_length=0)

   解压缩 *data* 并返回 bytes 对象，其中包含对应于 *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])

   所有挂起的输入会被处理，并且返回包含剩余未压缩输出的 bytes 对象。
   在调用 "flush()" 之后，"decompress()" 方法将无法被再次调用；唯一可
   行的操作是删除该对象。

   可选的形参 *length* 设置输出缓冲区的初始大小。

Decompress.copy()

   返回解压缩对象的一个拷贝。 它可以用来在数据流的中途保存解压缩器的状
   态以便加快随机查找数据流后续位置的速度。

在 3.8 版本发生变更: 添加了对解压缩对象执行 "copy.copy()" 和
"copy.deepcopy()" 的支持。

下列常量可被用于配置压缩和解压缩行为：

zlib.DEFLATED

   紧凑压缩方法。

zlib.MAX_WBITS

   最大窗口尺寸，表示为 2 的幂。 例如，如果 "MAX_WBITS" 为 "15" 则窗口
   尺寸将为 "32 KiB"。

zlib.DEF_MEM_LEVEL

   用于压缩对象的默认内存级别。

zlib.DEF_BUF_SIZE

   用于解压缩操作的默认缓冲区大小。

zlib.Z_NO_COMPRESSION

   压缩级别 "0"；无压缩。

   Added in version 3.6.

zlib.Z_BEST_SPEED

   压缩级别 "1"；速度最快而压缩率最低。

zlib.Z_BEST_COMPRESSION

   压缩级别 "9"；速度最慢而压缩率最高。

zlib.Z_DEFAULT_COMPRESSION

   默认压缩级别 ("-1")；平衡速度和压缩率。 目前等价于压缩级别 "6"。

zlib.Z_DEFAULT_STRATEGY

   默认压缩策略，针对普通数据。

zlib.Z_FILTERED

   针对过滤器（或预测器）所产生数据的压缩策略。

zlib.Z_HUFFMAN_ONLY

   强制仅使用 Huffman 代码的压缩策略。

zlib.Z_RLE

   限制匹配距离为一的压缩策略（游程编码）。

   此常量仅在 Python 编译时使用了 zlib 1.2.0.1 或更高版本的情况下可用
   。

   Added in version 3.6.

zlib.Z_FIXED

   避免使用动态 Huffman 代码的压缩策略。

   此常量仅在 Python 编译时启用了 zlib 1.2.2.2 或更高版本的情况下可用
   。

   Added in version 3.6.

zlib.Z_NO_FLUSH

   刷新模式 "0"。 没有特殊的刷新行为。

   Added in version 3.6.

zlib.Z_PARTIAL_FLUSH

   刷新模式 "1"。 尽可能多地刷新输出。

zlib.Z_SYNC_FLUSH

   刷新模式 "2"。 刷新所有输出并将输出对齐到字节边界。

zlib.Z_FULL_FLUSH

   刷新模式 "3"。 刷新所有输出并重置压缩状态。

zlib.Z_FINISH

   刷新模式 "4"。 处理所有待处理输入，不再接受输入。

zlib.Z_BLOCK

   刷新模式 "5"。 完成并发送一个收缩块。

   此常量仅在 Python 编译时启用了 zlib 1.2.2.2 或更高版本的情况下可用
   。

   Added in version 3.6.

zlib.Z_TREES

   刷新模式 "6"，用于膨胀操作。 指令膨胀操作在其达到下一个收缩块边界时
   返回。

   此常量仅在 Python 编译时启用了 zlib 1.2.3.4 或更高版本的情况下可用
   。

   Added in version 3.6.

通过下列常量可获取模块所使用的 zlib 库的版本信息：

zlib.ZLIB_VERSION

   构建此模块时所用的 zlib 库的版本字符串。它的值可能与运行时所加载的
   zlib 不同。运行时加载的 zlib 库的版本字符串为
   "ZLIB_RUNTIME_VERSION"。

zlib.ZLIB_RUNTIME_VERSION

   解释器所加载的 zlib 库的版本字符串。

   Added in version 3.3.

zlib.ZLIBNG_VERSION

   如果使用了 zlib-ng，则为用于构建该模块的 zlib-ng 库的版本字符串。
   当存在时，"ZLIB_VERSION" 和 "ZLIB_RUNTIME_VERSION" 常量将反映由
   zlib-ng 提供的 zlib API 版本。

   如果 zlib-ng 未被用于构建该模块，此常量将不存在。

   Added in version 3.14.

参见:

  模块 "gzip"
     读写 **gzip** 格式的文件。

  https://www.zlib.net
     zlib 库项目主页。

  https://www.zlib.net/manual.html
     zlib 库用户手册。提供了库的许多功能的解释和用法。

  对于 gzip (解)压缩成为瓶颈的情况，python-isal 软件包会使用大体兼容的
  API 来加快 (解)压缩的速度。
