# 13.3. `bz2` - 支持bzip2压缩

源代码： Lib / bz2.py

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

`bz2`模块包含：

- 用于读取和写入压缩文件的`open()`函数和`BZ2File`类。
- 增量（de）压缩的`BZ2Compressor`和`BZ2Decompressor`类。
- 用于单次（de）压缩的`compress()`和`decompress()`函数。

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

## 13.3.1. （De）压缩文件

`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. 增量（反）压缩

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. 一次性（de）压缩

`bz2.``compress`(data, compresslevel=9)

  压缩数据。

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

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

`bz2.``decompress`(data)

  解压缩数据。

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

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

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