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 校验值。(Adler-32 校验的可靠性与 CRC32 基本相当，但比计算 CRC32 更高效。) 计算的结果是一个 32 位的整数。参数 value 是校验时的起始值，其默认值为 1。借助参数 value 可为分段的输入计算校验值。此算法没有加密强度，不应用于身份验证和数字签名。此算法的目的仅为验证数据的正确性，不适合作为通用散列算法。
在 3.0 版本发生变更: 结果将总是不带符号的。
- 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.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()方法的调用所产生的输出。 部分输入数据可能会被保留在内部缓冲区以供后续处理。如果可选的形参 max_length 非零则返回值将不会长于 max_length。 这可能意味着不是所有已压缩输入都能被处理；并且未被消耗的数据将被保存在
unconsumed_tail属性中。 如果要继续解压缩则这个字节串必须被传给对decompress()的后续调用。 如果 max_length 为零则整个输入都会被解压缩，并且unconsumed_tail将为空。在 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.
参见
- 模块
gzip 读写 gzip 格式的文件。
- https://www.zlib.net
zlib 库项目主页。
- https://www.zlib.net/manual.html
zlib 库用户手册。提供了库的许多功能的解释和用法。
对于 gzip (解)压缩成为瓶颈的情况，python-isal 软件包会使用最兼容的 API 来加快 (解)压缩的速度。