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 模块。

此模块中可用的异常和函数有

异常 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])

处理所有挂起的输入，并返回一个包含剩余压缩输出的字节对象。可以从常量 Z_NO_FLUSH、Z_PARTIAL_FLUSH、Z_SYNC_FLUSH、Z_FULL_FLUSH、Z_BLOCK（zlib 1.2.3.4）或 Z_FINISH 中选择 _mode_，默认为 Z_FINISH。除 Z_FINISH 外，所有常量都允许压缩更多字节字符串的数据，而 Z_FINISH 完成压缩流并阻止压缩任何更多数据。在将 _mode_ 设置为 Z_FINISH 调用 flush() 之后，将无法再次调用 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 库版本的信息可以通过以下常量获得

zlib.ZLIB_VERSION

用于构建模块的 zlib 库的版本字符串。这可能与运行时实际使用的 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 手册解释了该库的许多函数的语义和用法。