Python/docs/3.9/library/bz2

bz2 — 支持 bzip2 压缩

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

---

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

bz2 模块包含：

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

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

(解)压缩文件

bz2.open(filename, mode='rb', 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', *, compresslevel=9)

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

如果 filename 是 str 或 bytes 对象，则直接打开命名文件。 否则，filename 应该是一个 file object，它将用于读取或写入压缩数据。

mode 参数可以是用于读取的 'r'（默认）、用于覆盖的 'w'、用于独占创建的 'x' 或 'a'用于附加。 这些可以分别等效地表示为 'rb'、'wb'、'xb' 和 'ab'。

如果 filename 是文件对象（而不是实际文件名），则 'w' 模式不会截断文件，而是等效于 'a'。

如果 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 版更改： 接受 类路径对象 。

3.9 版更改： 删除了 缓冲 参数。 自 Python 3.0 以来，它被忽略和弃用。 传递一个打开的文件对象来控制文件的打开方式。

compresslevel 参数变为仅限关键字。

增量（解）压缩

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 版中的新功能。

一次性（解）压缩

bz2.compress(data, compresslevel=9)

压缩 data，一个 bytes-like object。

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

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

bz2.decompress(data)

解压 data，一个 bytes-like object。

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

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

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

使用示例

以下是 bz2 模块典型用法的一些示例。

使用 compress() 和 decompress() 来演示往返压缩：

>>> import bz2
>>> data = b"""\
... Donec rhoncus quis sapien sit amet molestie. Fusce scelerisque vel augue
... nec ullamcorper. Nam rutrum pretium placerat. Aliquam vel tristique lorem,
... sit amet cursus ante. In interdum laoreet mi, sit amet ultrices purus
... pulvinar a. Nam gravida euismod magna, non varius justo tincidunt feugiat.
... Aliquam pharetra lacus non risus vehicula rutrum. Maecenas aliquam leo
... felis. Pellentesque semper nunc sit amet nibh ullamcorper, ac elementum
... dolor luctus. Curabitur lacinia mi ornare consectetur vestibulum."""
>>> c = bz2.compress(data)
>>> len(data) / len(c)  # Data compression ratio
1.513595166163142
>>> d = bz2.decompress(c)
>>> data == d  # Check equality to original object after round-trip
True

Copy

使用 BZ2Compressor 进行增量压缩：

>>> import bz2
>>> def gen_data(chunks=10, chunksize=1000):
...     """Yield incremental blocks of chunksize bytes."""
...     for _ in range(chunks):
...         yield b"z" * chunksize
...
>>> comp = bz2.BZ2Compressor()
>>> out = b""
>>> for chunk in gen_data():
...     # Provide data to the compressor object
...     out = out + comp.compress(chunk)
...
>>> # Finish the compression process.  Call this once you have
>>> # finished providing data to the compressor.
>>> out = out + comp.flush()

Copy

上面的示例使用了一个非常“非随机”的数据流（b”z” 块的流）。 随机数据往往压缩得不好，而有序、重复的数据通常会产生很高的压缩率。

以二进制模式写入和读取 bzip2 压缩文件：

>>> import bz2
>>> data = b"""\
... Donec rhoncus quis sapien sit amet molestie. Fusce scelerisque vel augue
... nec ullamcorper. Nam rutrum pretium placerat. Aliquam vel tristique lorem,
... sit amet cursus ante. In interdum laoreet mi, sit amet ultrices purus
... pulvinar a. Nam gravida euismod magna, non varius justo tincidunt feugiat.
... Aliquam pharetra lacus non risus vehicula rutrum. Maecenas aliquam leo
... felis. Pellentesque semper nunc sit amet nibh ullamcorper, ac elementum
... dolor luctus. Curabitur lacinia mi ornare consectetur vestibulum."""
>>> with bz2.open("myfile.bz2", "wb") as f:
...     # Write compressed data to file
...     unused = f.write(data)
>>> with bz2.open("myfile.bz2", "rb") as f:
...     # Decompress data from file
...     content = f.read()
>>> content == data  # Check equality to original object after round-trip
True

Copy