# 13.1. `zlib` - 与gzip 兼容的压缩

对于需要数据压缩的应用程序，此模块中的函数允许使用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])

  计算数据的Adler-32校验和。（Adler-32校验和几乎与CRC32一样可靠，但可以计算得更快）。结果是无符号的32位整数。如果存在值，则将其用作校验和的起始值；否则，使用默认值1。传入值允许在多个输入的并置上计算运行的校验和。该算法不是加密强的，并且不应该用于认证或数字签名。由于算法被设计为用作校验和算法，所以它不适合用作一般的哈希算法。

  在3.0版中已更改：始终返回未签名的值。要在所有Python版本和平台上生成相同的数值，请使用`adler32（data） ＆amp； 0xffffffff`

`zlib.``compress`(data[, level])

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

`zlib.``compressobj`(level=-1, method=DEFLATED, wbits=15, memLevel=8, strategy=Z_DEFAULT_STRATEGY[, zdict])

  返回一个压缩对象，用于压缩不能立即适合内存的数据流。

  level是压缩级别 - 从`0`到`9`或`-1`的整数。值`1`是最快的并且产生最小的压缩，而`9`的值最慢并且产生最多。`0`是无压缩。默认值为`-1`（Z_DEFAULT_COMPRESSION）。Z_DEFAULT_COMPRESSION表示速度和压缩之间的默认折中（目前等于6级）。

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

  wbits参数控制压缩数据时使用的历史缓冲区大小（或“窗口大小”），以及输出中是否包括标头和尾部。它可以取几个值的范围：

  - +9到+15：窗口大小的基二对数，因此其范围在512和32768之间。较大的值以更大的内存使用为代价产生更好的压缩。生成的输出将包括zlib特定的头和尾部。
  - -9至-15：使用wbits的绝对值作为窗口大小对数，同时生成没有头或尾校验和的原始输出流。
  - +25到+31 = 16 +（9到15）：使用值的低4位作为窗口大小对数，同时在输出中包括基本的gzip头和尾随校验和。

  memLevel参数控制用于内部压缩状态的内存量。有效值范围从`1`到`9`。更高的值使用更多的内存，但是更快，产生更小的输出。

  策略用于调整压缩算法。可能的值为`Z_DEFAULT_STRATEGY`，`Z_FILTERED`和`Z_HUFFMAN_ONLY`。

  zdict是预定义的压缩字典。这是包含预期在要压缩的数据中频繁出现的子序列的字节序列（例如`bytes`对象）。那些预期最常见的子序列应该出现在字典的结尾。

  在版本3.3中更改：添加了zdict参数和关键字参数支持。

`zlib.``crc32`(data[, value])

  计算数据的CRC（循环冗余校验）校验和。结果是无符号的32位整数。如果存在值，则将其用作校验和的起始值；否则，使用默认值0。传入值允许在多个输入的并置上计算运行的校验和。该算法不是加密强的，并且不应该用于认证或数字签名。由于算法被设计为用作校验和算法，所以它不适合用作一般的哈希算法。

  在3.0版中已更改：始终返回未签名的值。要在所有Python版本和平台上生成相同的数值，请使用`crc32（data） ＆amp； 0xffffffff`。

`zlib.``decompress`(data[, wbits[, bufsize]])

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

  bufsize是用于保存解压缩数据的缓冲区的初始大小。如果需要更多的空间，缓冲区大小将根据需要增加，所以你不必得到这个值完全正确；调整它只会保存对`malloc()`的几个调用。默认大小为16384。

`zlib.``decompressobj`(wbits=15[, zdict])

  返回解压缩对象，用于解压缩不能立即适合内存的数据流。

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

  zdict参数指定预定义的压缩字典。如果提供，这必须是与产生要解压缩的数据的压缩器所使用的字典相同的字典。

  注意

  If zdict is a mutable object (such as a `bytearray`), you must not modify its contents between the call to `decompressobj()` and the first call to the decompressor’s `decompress()` method.

  在版本3.3中已更改：添加了zdict参数。

压缩对象支持以下方法：

`Compress.``compress`(data)

  压缩数据，返回包含数据中至少部分数据的压缩数据的字节对象。此数据应连接到之前对`compress()`方法的任何调用产生的输出。一些输入可以保持在内部缓冲器中以供稍后处理。

`Compress.``flush`([mode])

  将处理所有待处理的输入，并返回包含剩余压缩输出的字节对象。可以从常量`Z_SYNC_FLUSH`，`Z_FULL_FLUSH`或`Z_FINISH`中选择模式，默认为`Z_FINISH` `Z_SYNC_FLUSH`和`Z_FULL_FLUSH`允许通过数据测试进一步压缩，而`Z_FINISH`完成压缩流并防止压缩任何更多数据。在使用模式设置为`Z_FINISH`调用`flush()`之后，无法再次调用`compress()`

`Compress.``copy`()

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

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

`Decompress.``unused_data`

  包含超过压缩数据末尾的任何字节的字节对象。也就是说，这保持`b""`，直到包含压缩数据的最后一个字节可用。如果整个字节表明包含压缩数据，这是`b""`，一个空字节对象。

`Decompress.``unconsumed_tail`

  包含上一个`decompress()`调用未占用的任何数据的字节对象，因为它超出了未压缩数据缓冲区的限制。这个数据还没有被zlib机器看到，因此你必须将它（可能还有更多的数据连接到它）返回到随后的`decompress()`方法调用，以获得正确的输出。

`Decompress.``eof`

  指示是否已达到压缩数据流结束的布尔值。

  这使得可以区分正确形成的压缩流和不完全或截断的压缩流。

  版本3.3中的新功能。

`Decompress.``decompress`(data[, max_length])

  解压缩数据，返回包含对应于string中至少部分数据的未压缩数据的字节对象。此数据应与由`decompress()`方法的任何先前调用产生的输出连接。一些输入数据可以保存在内部缓冲器中以供稍后处理。

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

`Decompress.``flush`([length])

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

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

`Decompress.``copy`()

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

有关正在使用的zlib库版本的信息可通过以下常量获得：

`zlib.``ZLIB_VERSION`

  用于构建模块的zlib库的版本字符串。这可能不同于在运行时实际使用的zlib库，它可作为`ZLIB_RUNTIME_VERSION`提供。

`zlib.``ZLIB_RUNTIME_VERSION`

  由解释器实际加载的zlib库的版本字符串。

  版本3.3中的新功能。

也可以看看

模块`gzip`
  读取和写入gzip -format文件。
http://www.zlib.net
  zlib库主页。
http://www.zlib.net/manual.html
  zlib手册解释了库的许多函数的语义和用法。