bz2 —支持 bzip2 压缩

源代码： Lib/bz2.py

---

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

bz2模块包含：

• open()函数和BZ2File类用于读取和写入 zipfile。

• 增量(解压缩)的BZ2Compressor和BZ2Decompressor类。

• compress()和decompress()Function可进行单次(解压缩)压缩。

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

(解压缩)文件

• bz2. open(* filename ， mode ='r'， compresslevel = 9 ， encoding = None ， errors = None ， newline = None *)
  • 以二进制或文本模式打开 bzip2zipfile，返回file object。

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

• mode *参数对于二进制模式可以是'r'，'rb'，'w'，'wb'，'x'，'xb'，'a'或'ab'之一，对于文本模式则可以是'rt'，'wt'，'xt'或'at'。默认值为'rb'。

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

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

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

版本 3.3 中的新Function。

在版本 3.4 中更改：添加了'x'(独占创建)模式。

在版本 3.6 中更改：接受path-like object。

• • class * bz2. BZ2File(* filename ， mode ='r'， buffering = None ， compresslevel = 9 *)
  • 以二进制模式打开 bzip2zipfile。

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

• mode *参数可以是'r'(用于读取)(默认值)，'w'(用于覆盖)，'x'(用于独占创建)或'a'(用于附加)。可以等效地分别将它们指定为'rb'，'wb'，'xb'和'ab'。

如果* filename *是文件对象(而不是实际的文件名)，则模式'w'不会截断该文件，而是等效于'a'。

• buffering *参数被忽略。从 Python 3.0 开始不推荐使用它。

如果* mode 是'w'或'a'，则 compresslevel *可以是1和9之间的整数，指定压缩级别：1产生最小的压缩，9(默认)产生最大的压缩。

如果* mode *为'r'，则 Importing 文件可能是多个压缩流的串联。

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

BZ2File还提供以下方法：

• peek([* n *])
  • 返回缓冲的数据而无需提前文件位置。至少返回一个字节的数据(除非在 EOF 处)。未指定返回的确切字节数。

版本 3.3 中的新Function。

从 3.0 版开始不推荐使用：关键字参数* buffering *不推荐使用，现在被忽略。

在版本 3.1 中进行了更改：添加了对with语句的支持。

在版本 3.3 中更改：添加了fileno()，readable()，seekable()，writable()，read1()和readinto()方法。

在版本 3.3 中更改：添加了对* filename *作为file object而不是实际文件名的支持。

在版本 3.3 中更改：添加了'a'(附加)模式，并支持读取多流文件。

在版本 3.4 中更改：添加了'x'(独占创建)模式。

在版本 3.5 中进行了更改：read()方法现在接受参数None。

在版本 3.6 中更改：接受path-like object。

Incremental (de)compression

• 类别 bz2. BZ2Compressor(* compresslevel = 9 *)
  • 创建一个新的压缩器对象。该对象可用于增量压缩数据。对于单次压缩，请使用compress()函数。

• compresslevel *(如果提供)必须为1和9之间的整数。默认值为9。

• compress(* data *)
  • 向压缩器对象提供数据。如果可能，返回一块压缩数据，否则返回一个空字节串。

完成向压缩器提供数据后，请调用flush()方法以完成压缩过程。

• flush ( )
  • 完成压缩过程。返回保留在内部缓冲区中的压缩数据。

调用此方法后，不得使用压缩机对象。

• 类别 bz2. BZ2Decompressor
  • 创建一个新的解压缩器对象。该对象可用于增量解压缩数据。对于单次压缩，请使用decompress()函数。

• decompress(* data ， max_length = -1 *)
  • 解压缩 data (bytes-like object)，以字节为单位返回未压缩的数据。某些 data *可能会在内部进行缓冲，以用于以后对decompress()的调用。返回的数据应与对decompress()的任何先前调用的输出连接在一起。

如果* max_length 为非负数，则最多返回 max_length 个字节的解压缩数据。如果达到此限制并可以产生进一步的输出，则needs_input属性将设置为False。在这种情况下，对decompress()的下一次调用可以提供 data *作为b''以获得更多的输出。

如果所有 Importing 数据都已解压缩并返回(或者因为这小于* max_length 个字节，或者因为 max_length *为负数)，则needs_input属性将设置为True。

在达到流的末尾后try解压缩数据会引发 EOFError。流结束后找到的所有数据将被忽略并保存在unused_data属性中。

在版本 3.5 中进行了更改：添加了* max_length *参数。

• eof
  • True如果已到达流结束标记。

版本 3.3 中的新Function。

• unused_data
  • 在压缩流结束后找到数据。

如果在到达流的末尾之前访问此属性，则其值为b''。

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

3.5 版中的新Function。

One-shot (de)compression

• 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 中进行了更改：添加了对多流 Importing 的支持。

用法示例

以下是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

使用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()

上面的示例使用了非常“非随机”的数据流(b 个“ z”块的流)。随机数据倾向于压缩较差，而有序的重复数据通常会产生较高的压缩率。

以二进制模式写入和读取 bzip2zipfile：

>>> 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