12.1. zlib — 与 gzip 兼容的压缩 — Python 文档

12.1. zlib — 压缩兼容压缩包

对于需要数据压缩的应用程序，该模块中的函数允许使用 zlib 库进行压缩和解压缩。 zlib 库在 http://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 校验和。 （Adler-32 校验和几乎与 CRC32 一样可靠，但计算速度要快得多。）如果存在 value，则将其用作校验和的起始值； 否则，使用固定的默认值。 这允许在多个输入的串联上计算运行校验和。 该算法在密码学上不强，不应用于身份验证或数字签名。 由于该算法被设计用作校验和算法，因此不适合用作通用哈希算法。

这个函数总是返回一个整数对象。

笔记

要在所有 Python 版本和平台上生成相同的数值，请使用 adler32(data) & 0xffffffff。 如果您仅使用打包二进制格式的校验和，则没有必要，因为无论符号如何，返回值都是正确的 32 位二进制表示。

2.6 版本变更： 返回值在 [-2**31, 2**31-1] 范围内，与平台无关。 在旧版本中，该值在某些平台上签名，而在其他平台上未签名。

3.0 版本变更： 返回值无符号，范围[0, 2**32-1] 与平台无关。

zlib.compress(string[, level])

压缩 string 中的数据，返回包含压缩数据的字符串。 level 是一个从 0 到 9 的整数，控制压缩级别； 1 最快，产生的压缩最少，9 最慢，产生的压缩最多。 0 是无压缩。 默认值为 6。 如果发生任何错误，则引发 error 异常。

zlib.compressobj([level[, method[, wbits[, memlevel[, strategy]]]]])

返回一个压缩对象，用于压缩一次无法放入内存的数据流。 level是从0到9或-1的整数，控制压缩的级别； 1 最快，产生的压缩最少，9 最慢，产生的压缩最多。 0 是无压缩。 默认值为 -1 (Z_DEFAULT_COMPRESSION)。 Z_DEFAULT_COMPRESSION 表示速度和压缩之间的默认折衷（当前相当于级别 6）。

method 是压缩算法。 目前，唯一支持的值是 DEFLATED。

wbits 参数控制压缩数据时使用的历史缓冲区的大小（或“窗口大小”），以及输出中是否包含头和尾。 它可以采用多个值范围。 默认值为 15。

• +9 到 +15：窗口大小的以 2 为底的对数，因此范围在 512 到 32768 之间。 较大的值会产生更好的压缩，但会占用更多内存。 结果输出将包括特定于 zlib 的标头和尾标。

• -9 到 -15：使用 wbits 的绝对值作为窗口大小的对数，同时生成没有头或尾随校验和的原始输出流。

• +25 到 +31 = 16 +（9 到 15）：使用值的低 4 位作为窗口大小的对数，同时在输出中包含基本的 gzip 标头和尾随校验和。

memlevel 控制用于内部压缩状态的内存量。 有效值范围从 1 到 9。 更高的值使用更多的内存，但速度更快并产生更小的输出。 默认值为 8。

strategy 用于调整压缩算法。 可能的值为 Z_DEFAULT_STRATEGY、Z_FILTERED 和 Z_HUFFMAN_ONLY。 默认值为 Z_DEFAULT_STRATEGY。

zlib.crc32(data[, value])

计算 data 的 CRC（循环冗余校验）校验和。 如果存在 value，则用作校验和的起始值； 否则，使用固定的默认值。 这允许在多个输入的串联上计算运行校验和。 该算法在密码学上不强，不应用于身份验证或数字签名。 由于该算法被设计用作校验和算法，因此不适合用作通用哈希算法。

这个函数总是返回一个整数对象。

笔记

要在所有 Python 版本和平台上生成相同的数值，请使用 crc32(data) & 0xffffffff。 如果您仅使用打包二进制格式的校验和，则没有必要，因为无论符号如何，返回值都是正确的 32 位二进制表示。

2.6 版本变更： 返回值在 [-2**31, 2**31-1] 范围内，与平台无关。 在旧版本中，该值将在某些平台上签名而在其他平台上未签名。

3.0 版本变更： 返回值无符号，范围[0, 2**32-1] 与平台无关。

zlib.decompress(string[, wbits[, bufsize]])

解压 string 中的数据，返回一个包含未压缩数据的字符串。 wbits 参数取决于 string 的格式，将在下面进一步讨论。 如果给定 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 值为 15，它对应于最大的窗口大小，并且需要包含 zlib 头和尾。

bufsize 是用于保存解压缩数据的缓冲区的初始大小。 如果需要更多空间，缓冲区大小将根据需要增加，因此您不必完全正确地获取此值； 调整它只会节省对 malloc() 的几次调用。 默认大小为 16384。

zlib.decompressobj([wbits])

返回一个解压缩对象，用于解压缩一次无法放入内存的数据流。

wbits 参数控制历史缓冲区的大小（或“窗口大小”），以及预期的头部和尾部格式。 它与 decompress() 中描述的 具有相同的含义。

压缩对象支持以下方法：

Compress.compress(string)

压缩 string，返回一个字符串，其中包含 string 中至少部分数据的压缩数据。 此数据应连接到任何先前调用 compress() 方法产生的输出。 一些输入可能会保存在内部缓冲区中以供以后处理。

Compress.flush([mode])

处理所有待处理的输入，并返回一个包含剩余压缩输出的字符串。 模式可以从常量Z_SYNC_FLUSH、Z_FULL_FLUSH或Z_FINISH中选择，默认为Z_FINISH。 Z_SYNC_FLUSH 和 Z_FULL_FLUSH 允许进一步压缩数据字符串，而 Z_FINISH 完成压缩流并防止压缩更多数据。 在将mode设置为Z_FINISH的情况下调用flush()后，无法再次调用compress()方法； 唯一现实的操作是删除对象。

Compress.copy()

返回压缩对象的副本。 这可用于有效压缩共享公共初始前缀的一组数据。

2.5 版中的新功能。

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

Decompress.unused_data

包含压缩数据末尾之后的任何字节的字符串。 也就是说，这将保持 "" 直到包含压缩数据的最后一个字节可用。 如果整个字符串最终包含压缩数据，则这是 ""，即空字符串。

确定一串压缩数据在哪里结束的唯一方法是实际解压缩它。 这意味着当压缩数据包含在较大文件的一部分时，您只能通过读取数据并将其后跟一些非空字符串输入到解压对象的 decompress() 方法中来找到它的结尾，直到unused_data 属性不再是空字符串。

Decompress.unconsumed_tail

一个字符串，其中包含上次 decompress() 调用未使用的任何数据，因为它超出了未压缩数据缓冲区的限制。 这个数据还没有被 zlib 机器看到，所以你必须将它（可能还有更多的数据连接到它）反馈给后续的 decompress() 方法调用以获得正确的输出。

Decompress.decompress(string[, max_length])

解压string，返回一个字符串，其中包含与string中至少部分数据对应的未压缩数据。 此数据应连接到任何先前调用 decompress() 方法产生的输出。 一些输入数据可能会保存在内部缓冲区中以供以后处理。

如果可选参数 max_length 非零，则返回值将不超过 max_length。 这可能意味着并非所有压缩输入都可以处理； 并且未消耗的数据将存储在属性 unconsumed_tail 中。 如果要继续解压缩，则必须将此字符串传递给对 decompress() 的后续调用。 如果未提供 max_length 则整个输入被解压缩，并且 unconsumed_tail 是一个空字符串。

Decompress.flush([length])

处理所有待处理的输入，并返回一个包含剩余未压缩输出的字符串。 调用flush()后，无法再次调用decompress()方法； 唯一现实的操作是删除对象。

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

Decompress.copy()

返回解压对象的副本。 这可用于在数据流中途保存解压缩器的状态，以加快在未来点对流的随机搜索。

2.5 版中的新功能。

也可以看看

模块 gzip

读写 gzip 格式的文件。

http://www.zlib.net

zlib 库主页。

http://www.zlib.net/manual.html

zlib 手册解释了库的许多函数的语义和用法。