13.3. bz2 — 支持 bzip2 压缩 — Python 文档

13.3. bz2 - 支持 bzip2 压缩

源代码： :source:`Lib/bz2.py`

---

该模块提供了一个使用 bzip2 压缩算法压缩和解压缩数据的综合接口。

bz2 模块包含：

• open() 函数和 BZ2File 类用于读取和写入压缩文件。
• 用于增量（解）压缩的 BZ2Compressor 和 BZ2Decompressor 类。
• compress() 和 decompress() 函数用于一次性（解）压缩。

该模块中的所有类都可以安全地从多个线程访问。

13.3.1. (解)压缩文件

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

以二进制或文本模式打开 bzip2 压缩文件，返回 文件对象 。

与 BZ2File 的构造函数一样，filename 参数可以是实际的文件名（str 或 bytes 对象），也可以是现有的要读取或写入的文件对象。

mode 参数可以是 'r'、'rb'、'w'、'wb'、'x'、'xb'、'a' 或 'ab' 用于二进制模式，或 'rt'、'wt'、'xt' 或 ] 用于文本模式。 默认值为 'rb'。

compresslevel 参数是一个从 1 到 9 的整数，对于 BZ2File 构造函数。

对于二进制模式，此函数等效于 BZ2File 构造函数：BZ2File(filename, mode, compresslevel=compresslevel)。 在这种情况下，不得提供 encoding、errors 和 newline 参数。

对于文本模式，会创建一个 BZ2File 对象，并将其包装在具有指定编码、错误处理行为和行尾的 io.TextIOWrapper 实例中。

3.3 版中的新功能。

3.4版本变更：增加了'x'（独创）模式。

3.6 版更改： 接受 类路径对象 。

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 参数被忽略。 它的使用已被弃用。

如果 mode 是 'w' 或 'a'，compresslevel 可以是 1 和 9 之间的数字，指定压缩级别：1 产生的压缩最少，9（默认）产生最多的压缩。

如果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 版更改： 支持 文件名 是 文件对象 而不是实际文件名。

3.3 版本变更： 添加了 'a'（追加）模式，并支持读取多流文件。

3.4版本变更：增加了'x'（独创）模式。

3.5 版更改： read() 方法现在接受 None 的参数。

3.6 版更改： 接受 类路径对象 。

13.3.2. 增量（解）压缩

class bz2.BZ2Compressor(compresslevel=9)

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

compresslevel，如果给定，必须是 1 和 9 之间的数字。 默认值为 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

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

3.5 版中的新功能。

13.3.3. 一次性（解）压缩

bz2.compress(data, compresslevel=9)

压缩数据。

compresslevel，如果给定，必须是 1 和 9 之间的数字。 默认值为 9。

对于增量压缩，请改用 BZ2Compressor。

bz2.decompress(data)

解压数据。

如果 data 是多个压缩流的串联，则解压所有流。

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

3.3 版更改： 添加了对多流输入的支持。