13.3. bz2 — 对 bzip2 压缩算法的支持

源代码: Lib/bz2.py


此模块提供了使用 bzip2 压缩算法压缩和解压数据的一套完整的接口。

bz2 模块包含:

此模块中的所有类都能安全地从多个线程访问。

13.3.1. 文件压缩和解压

bz2.open(filename, mode='r', compresslevel=9, encoding=None, errors=None, newline=None)

以二进制或文本模式打开 bzip2 压缩文件,返回一个 file object

BZ2File 的构造函数类似,filename 参数可以是一个实际的文件名(strbytes 对象),或是已有的可供读取或写入的文件对象。

mode 参数可设为二进制模式的 'r''rb''w''wb''x''xb''a''ab',或者文本模式的 'rt''wt''xt''at'。默认是 'rb'

compresslevel 参数是 1 到 9 的整数,和 BZ2File 的构造函数一样。

对于二进制模式,这个函数等价于 BZ2File 构造器: BZ2File(filename, mode, compresslevel=compresslevel)。 在这种情况下,不可提供 encoding, errorsnewline 参数。

对于文本模式,将会创建一个 BZ2File 对象,并将它包装到一个 io.TextIOWrapper 实例中,此实例带有指定的编码格式、错误处理行为和行结束符。

3.3 新版功能.

在 3.4 版更改: 添加了 'x' (仅创建) 模式。

在 3.6 版更改: 接受一个 path-like object

class bz2.BZ2File(filename, mode='r', buffering=None, compresslevel=9)

用二进制模式打开 bzip2 压缩文件。

如果 filename 是一个 strbytes 对象,则打开名称对应的文件目录。 否则的话,filename 应当是一个 file object,它将被用来读取或写入压缩数据。

mode 参数可以是表示读取的 'r' (默认值),表示覆写的 'w',表示单独创建的 'x',或表示添加的 'a'。 这些模式还可别以 'rb', 'wb', 'xb''ab' 的等价形式给出。

如果 filename 是一个文件对象(而不是实际的文件名),则 'w' 模式并不会截断文件,而是会等价于 'a'

buffering 参数会被忽略。 它已经被弃用。

If mode is 'w' or 'a', compresslevel can be a number between 1 and 9 specifying the level of compression: 1 produces the least compression, and 9 (default) produces the most compression.

如果 mode'r',则输入文件可以为多个压缩流的拼接。

BZ2File 提供了 io.BufferedIOBase 所指定的所有成员,但 detach()truncate() 除外。 并支持迭代和 with 语句。

BZ2File 还提供了以下方法:

peek([n])

返回缓冲的数据而不前移文件位置。 至少将返回一个字节的数据(除非为 EOF)。 实际返回的字节数不确定。

注解

虽然调用 peek() 不会改变 BZ2File 的文件位置,但它可能改变下层文件对象的位置(举例来说如果 BZ2File 是通过传为一个文件对象作为 filename 的话)。

3.3 新版功能.

在 3.1 版更改: 支持了 with 语句。

在 3.3 版更改: 添加了 fileno(), readable(), seekable(), writable(), read1()readinto() 方法。

在 3.3 版更改: 添加了对 filename 使用 file object 而非实际文件名的支持。

在 3.3 版更改: 添加了 'a' (append) 模式,以及对读取多数据流文件的支持。

在 3.4 版更改: 添加了 'x' (仅创建) 模式。

在 3.5 版更改: read() 方法现在接受 None 作为参数。

在 3.6 版更改: 接受一个 path-like object

13.3.2. 增量压缩和解压

class bz2.BZ2Compressor(compresslevel=9)

创建一个新的压缩器对象。 此对象可被用来执行增量数据压缩。 对于一次性压缩,请改用 compress() 函数。

compresslevel, if given, must be a number between 1 and 9. The default is 9.

compress(data)

向压缩器对象提供数据。 在可能的情况下返回一段已压缩数据,否则返回空字节串。

当你已结束向压缩器提供数据时,请调用 flush() 方法来完成压缩进程。

flush()

结束压缩进程,返回内部缓冲中剩余的压缩完成的数据。

调用此方法之后压缩器对象将不可再被使用。

class bz2.BZ2Decompressor

创建一个新的解压缩器对象。 此对象可被用来执行增量数据解压缩。 对于一次性解压缩,请改用 decompress() 函数。

注解

这个类不会透明地处理包含多个已压缩数据流的输入,这不同于 decompress()BZ2File。 如果你需要通过 BZ2Decompressor 来解压缩多个数据流输入,你必须为每个数据流都使用新的解压缩器。

decompress(data, max_length=-1)

解压缩 data (一个 bytes-like object),返回字节串形式的解压缩数据。 某些 data 可以在内部被缓冲,以便用于后续的 decompress() 调用。 返回的数据应当与之前任何 decompress() 调用的输出进行拼接。

如果 max_length 为非负数,将返回至多 max_length 个字节的解压缩数据。 如果达到此限制并且可以产生后续输出,则 needs_input 属性将被设为 False。 在这种情况下,下一次 decompress() 调用提供的 data 可以为 b'' 以获取更多的输出。

如果所有输入数据都已被解压缩并返回(或是因为它少于 max_length 个字节,或是因为 max_length 为负数),则 needs_input 属性将被设为 True

在到达数据流末尾之后再尝试解压缩数据会引发 EOFError。 在数据流末尾之后获取的任何数据都会被忽略并存储至 unused_data 属性。

在 3.5 版更改: 添加了 max_length 形参。

eof

若达到了数据流末尾标识符则为 True

3.3 新版功能.

unused_data

压缩数据流的末尾还有数据。

如果在达到数据流末尾之前访问此属性,其值将为 b''

needs_input

如果在要求新的未解压缩输入之前 decompress() 方法可以提供更多的解压缩数据则为 False

3.5 新版功能.

13.3.3. 一次性压缩或解压

bz2.compress(data, compresslevel=9)

Compress data.

compresslevel, if given, must be a number between 1 and 9. The default is 9.

对于增量压缩,请改用 BZ2Compressor

bz2.decompress(data)

Decompress data.

如果 data 是多个压缩数据流的拼接,则解压缩所有数据流。

对于增量解压缩,请改用 BZ2Decompressor

在 3.3 版更改: 支持了多数据流的输入。