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 一样可靠，但计算速度快得多。）结果是一个无符号的 32 位整数。如果存在 value，则将其用作校验和的起始值；否则，使用默认值 1。传入 value 允许计算多个输入的连接的运行校验和。该算法不具有加密强度，不应用于身份验证或数字签名。由于该算法设计用于校验和算法，因此不适合用作通用哈希算法。
3.0 版本发生变更: 结果始终是无符号的。
- 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 参数控制压缩数据时使用的历史缓冲区大小（或“窗口大小”），以及输出中是否包含头部和尾部。它可以取几个范围的值，默认为
15(MAX_WBITS)+9 到 +15：窗口大小的以 2 为底的对数，因此范围在 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（循环冗余校验）校验和。结果是一个无符号的 32 位整数。如果存在 value，则将其用作校验和的起始值；否则，使用默认值 0。传入 value 允许计算多个输入的连接的运行校验和。该算法不具有加密强度，不应用于身份验证或数字签名。由于该算法设计用于校验和算法，因此不适合用作通用哈希算法。
3.0 版本发生变更: 结果始终是无符号的。
- zlib.decompress(data, /, wbits=MAX_WBITS, bufsize=DEF_BUF_SIZE)¶
解压缩 data 中的字节，返回一个包含解压缩数据的字节对象。wbits 参数取决于 data 的格式，下面将进一步讨论。如果给定 bufsize，则将其用作输出缓冲区的初始大小。如果发生任何错误，则引发
error异常。wbits 参数控制历史缓冲区（或“窗口大小”）的大小，以及预期的头部和尾部格式。它与
compressobj()的参数类似，但接受更多范围的值+8 到 +15：窗口大小的以 2 为底的对数。输入必须包含 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，返回一个字节对象，其中包含 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完成压缩流并阻止压缩更多数据。在调用flush()并将 mode 设置为Z_FINISH后，不能再次调用compress()方法；唯一实际的操作是删除对象。
- Compress.copy()¶
返回压缩对象的副本。这可用于高效压缩一组共享共同初始前缀的数据。
3.8 版本发生变更: 为压缩对象添加了 copy.copy() 和 copy.deepcopy() 支持。
解压缩对象支持以下方法和属性
- Decompress.unused_data¶
一个字节对象，包含超出压缩数据末尾的任何字节。也就是说，这在包含压缩数据的最后一个字节可用之前一直是
b""。如果整个字节字符串最终包含压缩数据，则为空字节对象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()¶
返回解压缩对象的副本。这可用于在数据流中途保存解压缩器的状态，以便在将来加快对流的随机查找。
3.8 版本发生变更: 为解压缩对象添加了 copy.copy() 和 copy.deepcopy() 支持。
以下常量可用于配置压缩和解压缩行为
- zlib.DEFLATED¶
deflate 压缩方法。
- zlib.MAX_WBITS¶
最大窗口大小，表示为 2 的幂。例如，如果
MAX_WBITS为15，则窗口大小为32 KiB。
- zlib.DEF_MEM_LEVEL¶
压缩对象的默认内存级别。
- zlib.DEF_BUF_SIZE¶
解压缩操作的默认缓冲区大小。
- zlib.Z_NO_COMPRESSION¶
压缩级别
0。在 3.6 版本加入。
- zlib.Z_BEST_SPEED¶
压缩级别
1。
- zlib.Z_BEST_COMPRESSION¶
压缩级别
9。
- zlib.Z_DEFAULT_COMPRESSION¶
默认压缩级别 (
-1)。
- zlib.Z_DEFAULT_STRATEGY¶
默认压缩策略，用于普通数据。
- zlib.Z_FILTERED¶
用于过滤器（或预测器）生成的数据的压缩策略。
- zlib.Z_HUFFMAN_ONLY¶
仅强制哈夫曼编码的压缩策略。
- zlib.Z_RLE¶
将匹配距离限制为 1 的压缩策略（行程长度编码）。
此常量仅在 Python 用 zlib 1.2.0.1 或更高版本编译时可用。
在 3.6 版本加入。
- zlib.Z_FIXED¶
阻止使用动态哈夫曼编码的压缩策略。
此常量仅在 Python 用 zlib 1.2.2.2 或更高版本编译时可用。
在 3.6 版本加入。
- zlib.Z_NO_FLUSH¶
刷新模式
0。没有特殊的刷新行为。在 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。deflate 块已完成并输出。此常量仅在 Python 用 zlib 1.2.2.2 或更高版本编译时可用。
在 3.6 版本加入。
- zlib.Z_TREES¶
刷新模式
6，用于 inflate 操作。指示 inflate 在到达下一个 deflate 块边界时返回。此常量仅在 Python 用 zlib 1.2.3.4 或更高版本编译时可用。
在 3.6 版本加入。
有关正在使用的 zlib 库版本的信息可通过以下常量获取
- zlib.ZLIB_VERSION¶
用于构建模块的 zlib 库的版本字符串。这可能与实际运行时使用的 zlib 库不同，后者可用作
ZLIB_RUNTIME_VERSION。
- zlib.ZLIB_RUNTIME_VERSION¶
解释器实际加载的 zlib 库的版本字符串。
在 3.3 版本加入。
- zlib.ZLIBNG_VERSION¶
如果使用了 zlib-ng，则为用于构建模块的 zlib-ng 库的版本字符串。当存在时，
ZLIB_VERSION和ZLIB_RUNTIME_VERSION常量反映 zlib-ng 提供的 zlib API 的版本。如果未使用 zlib-ng 构建模块，则此常量将不存在。
在 3.14 版本加入。
参见
- 模块
gzip 读取和写入 gzip 格式文件。
- https://www.zlib.net
zlib 库主页。
- https://www.zlib.net/manual.html
zlib 手册解释了该库众多函数的语义和用法。
如果 gzip（解）压缩是瓶颈，python-isal 包以大致兼容的 API 加速（解）压缩。