bz2 ---支持 bzip2 压缩

源代码： Lib/bz2.py

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

这个 bz2 模块包含：

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

文件压缩与解压

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

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

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

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

这个 压缩能级 参数是从1到9的整数，至于 BZ2File 构造函数。

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

对于文本模式，A BZ2File 对象被创建并封装在 io.TextIOWrapper 具有指定编码、错误处理行为和行尾的实例。

3.3 新版功能.

在 3.4 版更改: 这个 'x' 添加了（独占创建）模式。

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

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' ， 压缩能级 可以是介于 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 版更改: 为添加了支持 filename 作为一个 file object 而不是实际的文件名。

在 3.3 版更改: 这个 'a' 添加了（append）模式，并支持读取多流文件。

在 3.4 版更改: 这个 'x' 添加了（独占创建）模式。

在 3.5 版更改: 这个 read() 方法现在接受的参数为 None .

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

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

这个 压缩能级 参数仅成为关键字。

增量（去）压缩

class bz2.BZ2Compressor(compresslevel=9)

创建新的压缩器对象。此对象可用于增量压缩数据。对于单次压缩，使用 compress() 而是函数。

压缩能级 如果给定，则必须是介于 1 和 9 . 默认值为 9 .

compress(data)

向压缩器对象提供数据。如果可能，返回压缩数据块，否则返回空字节字符串。

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

flush()

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

调用此方法后，不能使用压缩器对象。

class bz2.BZ2Decompressor

创建新的解压缩程序对象。此对象可用于增量解压缩数据。对于单次压缩，使用 decompress() 而是函数。

注解

此类不能透明地处理包含多个压缩流的输入，与 decompress() 和 BZ2File . 如果需要用 BZ2Decompressor 必须为每个流使用新的解压缩程序。

decompress(data, max_length=- 1)

减压 data （A） 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 ，A bytes-like object .

压缩能级 如果给定，则必须是介于 1 和 9 . 默认值为 9 .

对于增量压缩，使用 BZ2Compressor 相反。

bz2.decompress(data)

减压 data ，A 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

使用 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" 块）。随机数据往往会压缩得很差，而有序的重复数据通常会产生很高的压缩比。

以二进制模式写入和读取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