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])¶ 计算 data 的Adler-32校验和。 (Adler-32校验和几乎与CRC32一样可靠,但可以计算得快得多。)结果是一个无符号的32位整数。如果存在 value,它将用作校验和的起始值;否则,使用默认值1。传入 value 允许在多个输入的并置上计算运行的校验和。该算法不是加密强的,并且不应该用于认证或数字签名。由于算法被设计为用作校验和算法,所以它不适合用作一般的哈希算法。
在 3.0 版更改: 始终返回未签名的值。要在所有Python版本和平台上生成相同的数值,请使用
adler32(data) & 0xffffffff
。
-
zlib.
compress
(data, level=-1)¶ 压缩 data 中的字节,返回包含压缩数据的字节对象。 level 是控制压缩水平的从
0
到9
或-1
的整数;1
是最快的并且产生最小的压缩,9
是最慢的并且产生最多。0
是无压缩。默认值为-1
(Z_DEFAULT_COMPRESSION)。 Z_DEFAULT_COMPRESSION表示速度和压缩之间的默认折中(当前等于级别6)。如果发生任何错误,则提高error
异常。在 3.6 版更改: level 现在可以用作关键字参数。
-
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)。method 是压缩算法。目前,唯一支持的值是
DEFLATED
。wbits 参数控制压缩数据时使用的历史缓冲区大小(或“窗口大小”),以及输出中是否包含标头和尾部。它可以取几个值的范围:
+9到+15:窗口大小的基二对数,因此范围在512和32768之间。较大的值产生更好的压缩,但是以更大的内存使用为代价。生成的输出将包括zlib特定的头和尾部。
-9至-15:使用 wbits 的绝对值作为窗口大小对数,同时生成没有头或尾校验和的原始输出流。
+25到+31 = 16 +(9到15):使用值的低4位作为窗口大小对数,同时在输出中包括基本 gzip 头和尾随校验和。
memLevel 参数控制用于内部压缩状态的内存量。有效值范围从
1
到9
。更高的值使用更多的内存,但是更快,产生更小的输出。strategy 用于调整压缩算法。可能的值为
Z_DEFAULT_STRATEGY
,Z_FILTERED
和Z_HUFFMAN_ONLY
。zdict 是预定义的压缩字典。这是包含期望在要压缩的数据中频繁出现的子序列的字节序列(例如
bytes
对象)。那些预期最常见的子序列应该出现在字典的结尾。在 3.3 版更改: 添加了 zdict 参数和关键字参数支持。
-
zlib.
crc32
(data[, value])¶ 计算 data 的CRC(循环冗余校验)校验和。结果是无符号的32位整数。如果存在 value,它将用作校验和的起始值;否则,使用默认值0。传入 value 允许在多个输入的并置上计算运行的校验和。该算法不是加密强的,并且不应该用于认证或数字签名。由于算法被设计为用作校验和算法,所以它不适合用作一般的哈希算法。
在 3.0 版更改: 始终返回未签名的值。要在所有Python版本和平台上生成相同的数值,请使用
crc32(data) & 0xffffffff
。
-
zlib.
decompress
(data, wbits=MAX_WBITS, bufsize=DEF_BUF_SIZE)¶ 解压缩 data 中的字节,返回包含未压缩数据的字节对象。 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=15[, zdict])¶ 返回解压缩对象,用于解压缩不能立即适合内存的数据流。
wbits 参数控制历史缓冲区的大小(或“窗口大小”),以及预期的报头和尾部格式。它与 描述为decompress() 具有相同的含义。
zdict 参数指定预定义的压缩字典。如果提供,这必须是与产生要解压缩的数据的压缩器所使用的字典相同的字典。
注解
如果 zdict 是可变对象(例如
bytearray
),则不能在对decompressobj()
的调用和对解压缩器的decompress()
方法的第一次调用之间修改其内容。在 3.3 版更改: 添加了 zdict 参数。
压缩对象支持以下方法:
-
Compress.
compress
(data)¶ 压缩 data,返回包含 data 中至少部分数据的压缩数据的字节对象。此数据应连接到由任何先前对
compress()
方法的调用产生的输出。一些输入可以保持在内部缓冲器中以供稍后处理。
-
Compress.
flush
([mode])¶ 将处理所有待处理的输入,并返回包含剩余压缩输出的字节对象。 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
()¶ 返回压缩对象的副本。这可以用于有效地压缩共享公共初始前缀的一组数据。
解压缩对象支持以下方法和属性:
-
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
()¶ 返回解压缩对象的副本。这可以用于在数据流的中途保存解压缩器的状态,以便在未来点加速随机搜索到流中。
有关正在使用的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手册解释了库的许多函数的语义和用法。