# 12.3. `bz2` --- bzip2 互換の圧縮ライブラリ

バージョン 2.3 で追加.

このモジュールでは bz2 圧縮ライブラリのためのわかりやすいインタフェースを提供します。モジュールでは完全なファイルインタフェース、データを一括して圧縮/解凍する関数、データを逐次的に圧縮/解凍するための型を実装しています。

bz2 モジュールが提供している機能を以下にまとめます。

- `BZ2File` クラスは、 `readline()`, `readlines()`, `writelines()`, `seek()` 等を含む、完全なファイルインタフェースを実装します。
- `BZ2File` クラスは `seek()` をエミュレーションでサポートします。
- `BZ2File` クラスは広範囲の改行文字バリエーション(universal newline) をサポートします。
- `BZ2File` クラスは、ファイルオブジェクトの先読みアルゴリズムを元にして実装されている、最適化された行単位のイテレーション機能を提供します。
- `BZ2Compressor` および `BZ2Decompressor` クラスでは逐次的圧縮（解凍）をサポートしています。
- `compress()` および `decompress()` 関数は、一括圧縮/解凍機能を提供しています。
- 個別のロックメカニズムによってスレッド安全性を持っています。

注釈

Handling of multi-stream bzip2 files is not supported. Modules such as bz2file let you overcome this.

## 12.3.1. ファイルの圧縮/解凍

`BZ2File` クラスは圧縮ファイルの操作機能を提供しています。

class `bz2.``BZ2File`(filename[, mode[, buffering[, compresslevel]]])

  bz2 ファイルを開きます。 mode は `'r'` (デフォルト)または `'w'` で、それぞれ読み込みと書き込みに対応します。書き込み用に開いた場合、ファイルが存在しないなら新しく作成し、そうでない場合ファイルを切り詰ます。 buffering パラメタを与えた場合、 `0` はバッファリングなしを表し、それよりも大きい値はバッファサイズになります。デフォルトでは `0` です。圧縮レベル (compresslevel) を与える場合、値は `1` から `9` までの整数値でなければなりません。デフォルトの値は `9` です。ファイルを読み込む際に universal newlines モードを使う場合は `'U'` を mode に追加します。このモードで開かれた入力ファイルの行末はどれも、Pythonからは `'\n'` として見えます。また、開かれているファイルオブジェクトは `newlines` 属性を持ち、 `None` (まだ改行文字を読み込んでいない時), `'\r'`, `'\n'`, `'\r\n'` またはそれまでに読み込んだ全ての改行文字バリエーションを含むタプルになります。 universal newlines が利用できるのは読み込みだけです。 `BZ2File` が生成するインスタンスは通常のファイルインスタンスと同様のイテレーション操作をサポートしています。

  `BZ2File` は `with` 構文をサポートしています。

  バージョン 2.7 で変更: `with` 構文のサポートが追加されました。

  注釈

  This class does not support input files containing multiple streams (such as those produced by the pbzip2 tool). When reading such an input file, only the first stream will be accessible. If you require support for multi-stream files, consider using the third-party `bz2file` module (available from PyPI). This module provides a backport of Python 3.3's `BZ2File` class, which does support multi-stream files.

  `close`()

    ファイルを閉じます。オブジェクトのデータ属性 `closed` を真にします。閉じたファイルはそれ以後入出力操作の対象にできません。 `close()` 自体の呼び出しはエラーを引き起こすことなく何度も実行できます。

  `read`([size])

    最大で size バイトの解凍されたデータを読み出し、文字列として返します。 size 引数を負の値にした場合や省略した場合、EOF まで読み出します。

  `readline`([size])

    ファイルから次の 1 行を読み出し、改行文字も含めて文字列を返します。負でない size 値は、返される文字列の最大バイト長を制限します (その場合不完全な行を返すこともあります)。 EOF の時には空文字列を返します。

  `readlines`([size])

    ファイルから読み取った各行の文字列からなるリストを返します。オプション引数 size を与えた場合、文字列リストの合計バイト数の大まかな上限の指定になります。

  `xreadlines`()

    前のバージョンとの互換性のために用意されています。 `BZ2File` オブジェクトはかつて `xreadlines` モジュールで提供されていたパフォーマンス最適化を含んでいます。

    バージョン 2.3 で非推奨: このメソッドは `file` オブジェクトの同名のメソッドとの互換性のために用意されていますが、現在は推奨されないメソッドです。代りに `for line in file` を使ってください。

  `seek`(offset[, whence])

    ファイルの読み書き位置を移動します。引数 offset はバイト数で指定したオフセット値です。オプション引数 whence はデフォルトで `os.SEEK_SET` もしくは `0` (ファイルの先頭からのオフセットで、offset `>= 0` になるはず) です。他にとり得る値は `1` (現在のファイル位置からの相対位置で、正負どちらの値もとり得る)、および `2` (ファイルの終末端からの相対位置で、通常は負の値になるが、多くのプラットフォームではファイルの終末端を越えて seek できる) です。

    bz2 ファイルの seek はエミュレーションであり、パラメタの設定によっては処理が非常に低速になるかもしれないので注意してください。

  `tell`()

    現在のファイル位置を整数（long 整数になるかもしれません）で返します。

  `write`(data)

    ファイルに文字列 data を書き込みます。バッファリングのため、ディスク上のファイルに書き込まれたデータを反映させるには `close()` が必要になるかもしれないので注意してください。

  `writelines`(sequence_of_strings)

    複数の文字列からなるシーケンスをファイルに書き込みます。それぞれの文字列を書き込む際に改行文字を追加することはありません。シーケンスはイテレーション処理で文字列を取り出せる任意のオブジェクトにできます。この操作はそれぞれの文字列を write() を呼んで書き込むのと同じ操作です。

## 12.3.2. 逐次的な圧縮/解凍

逐次的な圧縮および解凍は `BZ2Compressor` および `BZ2Decompressor` クラスを用いて行います。

class `bz2.``BZ2Compressor`([compresslevel])

  新しい圧縮オブジェクトを作成します。このオブジェクトはデータを逐次的に圧縮できます。一括してデータを圧縮したいのなら、代わりに `compress()` 関数を使ってください。 compresslevel パラメタを与える場合、この値は `1` と `9` の間の整数でなければなりません。デフォルトの値は `9` です。

  `compress`(data)

    圧縮オブジェクトに追加のデータを入力します。圧縮データのチャンクを生成できた場合にはチャンクを返します。圧縮データの入力を終えた後は圧縮処理を終えるために `flush()` を呼んでください。内部バッファに残っている未処理のデータを返します。

  `flush`()

    圧縮処理を終え、内部バッファに残されているデータを返します。このメソッドの呼び出し以降は同じ圧縮オブジェクトを使ってはなりません。

class `bz2.``BZ2Decompressor`

  新しい解凍オブジェクトを生成します。このオブジェクトは逐次的にデータを解凍できます。一括してデータを解凍したいのなら、代わりに `decompress()` 関数を使ってください。

  `decompress`(data)

    解凍オブジェクトに追加のデータを入力します。可能な限り、解凍データのチャンクを生成できた場合にはチャンクを返します。ストリームの末端に到達した後に解凍処理を行おうとした場合には、例外 `EOFError` を送出します。ストリームの終末端の後ろに何らかのデータがあった場合、解凍処理はこのデータを無視し、オブジェクトの `unused_data` 属性に収めます。

## 12.3.3. 一括圧縮/解凍

一括での圧縮および解凍を行うための関数、 `compress()` および `decompress()` が提供されています。

`bz2.``compress`(data[, compresslevel])

  data を一括して圧縮します。データを逐次的に圧縮したいなら、代わりに `BZ2Compressor` を使ってください。もし compresslevel パラメタを与えるなら、この値は `1` から `9` の間の値をとらなくてはなりません。デフォルトの値は `9` です。

`bz2.``decompress`(data)

  data を一括して解凍します。データを逐次的に解凍したいなら、代わりに `BZ2Decompressor` を使ってください。