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 参数可以是一个实际的文件名（str 或 bytes 对象），或是已有的可供读取或写入的文件对象。

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, errors 和 newline 参数。

对于文本模式，将会创建一个 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 是一个 str 或 bytes 对象，则打开名称对应的文件目录。 否则的话，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 版更改: 支持了多数据流的输入。