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

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

模块包含：

用于增量压缩和解压的 BZ2Compressor 和类。
用于一次性压缩和解压的 compress() 和函数。

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

(filename, mode=’r’, compresslevel=9, encoding=None, errors=None, newline=None)

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

和的构造函数类似，filename 参数可以是一个实际的文件名（str 或对象），或是已有的可供读取或写入的文件对象。

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

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

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

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

3.3 新版功能.

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

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

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

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

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

mode 参数可以是表示读取的 'r' (默认值)，表示覆写的 'w'，表示单独创建的 'x'，或表示添加的 'a'。这些模式还可别以 'rb', , '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 还提供了以下方法：

peek([n])

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

注解

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

3.3 新版功能.

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

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

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

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

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

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

在 3.6 版更改: 接受一个。

class bz2.BZ2Compressor(compresslevel=9)

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

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

flush()

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

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

class bz2.BZ2Decompressor

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

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

decompress(data, max_length=-1)

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

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

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

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

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

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

3.3 新版功能.
needs_input

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

3.5 新版功能.

bz2.compress(data, compresslevel=9)

Compress data.

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

对于增量压缩，请改用。

bz2.decompress(data)

Decompress data.

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

对于增量解压缩，请改用 BZ2Decompressor。