13.3. bz2 - 支持bzip2压缩

源代码： Lib / bz2.py

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

bz2模块包含：

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

13.3.1. (De)compression of files

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

在二进制或文本模式下打开bzip2压缩文件，返回file object。

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

The mode argument can be any of 'r', 'rb', 'w', 'wb', 'x', 'xb', 'a' or 'ab' for binary mode, or 'rt', 'wt', 'xt', or 'at' for text mode. 默认值为'rb'。

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

对于二进制模式，此函数等效于BZ2File构造函数：BZ2File（filename， mode， compresslevel = compresslevel） 。在这种情况下，不能提供编码，错误和新行参数。

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

版本3.3中的新功能。

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

class bz2.BZ2File(filename, mode='r', buffering=None, compresslevel=9)

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

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

The mode argument can be either 'r' for reading (default), 'w' for overwriting, 'x' for exclusive creation, or 'a' for appending. 这些可以等效地分别给出为'rb'，'wb'，'xb'和'ab' 。

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

将忽略缓冲参数。其使用已被弃用。

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.

如果模式是'r'，则输入文件可以是多个压缩流的串联。

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

BZ2File还提供以下方法：

peek([n])

返回缓冲数据，而不提前文件位置。将返回至少一个字节的数据（除非在EOF）。返回的确切字节数未指定。

注意

调用peek()不会更改BZ2File的文件位置，它可能会更改底层文件对象的位置。如果BZ2File是通过传递filename的文件对象构建的）。

版本3.3中的新功能。

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

Changed in version 3.3: The fileno(), readable(), seekable(), writable(), read1() and readinto() methods were added.

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

在版本3.3中已更改：添加了'a'（append）模式，以及支持读取多流文件。

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

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

13.3.2. Incremental (de)compression

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)

解压缩数据（a bytes-like object），以字节形式返回未压缩数据。一些数据可以在内部缓冲，以便稍后调用decompress()。返回的数据应与之前对decompress()的任何调用的输出连接。

如果max_length为非负数，则返回至多max_length字节的解压缩数据。如果达到此限制并且可以产生进一步输出，则needs_input属性将设置为False。在这种情况下，对decompress()的下一个调用可以提供数据作为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. One-shot (de)compression

bz2.compress(data, compresslevel=9)

压缩数据。

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

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

bz2.decompress(data)

解压缩数据。

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

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

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