バージョン 2.3 で追加.
このモジュールでは bz2 圧縮ライブラリのためのわかりやすいインタフェースを提供します。モジュールでは完全なファイルインタフェース、データを一括して圧縮/解凍する関数、データを逐次的に圧縮/解凍するための型を実装しています。
その他のアーカイブフォーマットに関しては、 gzip, zipfile, tarfile モジュールを参照してください。
bz2 モジュールが提供している機能を以下にまとめます。
BZ2File クラスは圧縮ファイルの操作機能を提供しています。
bz2 ファイルを開きます。 mode は 'r' (デフォルト)または 'w' で、それぞれ読み込みと書き込みに対応します。書き込み用に開いた場合、ファイルが存在しないなら新しく作成し、そうでない場合ファイルを切り詰ます。 buffering パラメタを与えた場合、 0 はバッファリングなしを表し、それよりも大きい値はバッファサイズになります。デフォルトでは 0 です。圧縮レベル (compresslevel) を与える場合、値は 1 から 9 までの整数値でなければなりません。デフォルトの値は 9 です。ファイルを読み込む際に、広範囲の改行文字バリエーション(universal newline)をサポートさせたい場合は 'U' を mode に追加します。このモードで開かれた入力ファイルの行末はどれも、Pythonからは '\n' として見えます。また、開かれているファイルオブジェクトは newlines 属性を持ち、 None (まだ改行文字を読み込んでいない時), '\r', '\n', '\r\n' またはそれまでに読み込んだ全ての改行文字バリエーションを含むタプルになります。広範囲の改行文字サポートが利用できるのは読み込みだけです。 BZ2File が生成するインスタンスは通常のファイルインスタンスと同様のイテレーション操作をサポートしています。
バージョン 2.7 で変更: with 構文のサポートが追加されました。
ファイルを閉じます。オブジェクトのデータ属性 closed を真にします。閉じたファイルはそれ以後入出力操作の対象にできません。 close() 自体の呼び出しはエラーを引き起こすことなく何度も実行できます。
最大で size バイトの解凍されたデータを読み出し、文字列として返します。 size 引数を負の値にした場合や省略した場合、EOF まで読み出します。
ファイルから次の 1 行を読み出し、改行文字も含めて文字列を返します。負でない size 値は、返される文字列の最大バイト長を制限します (その場合不完全な行を返すこともあります)。 EOF の時には空文字列を返します。
ファイルから読み取った各行の文字列からなるリストを返します。オプション引数 size を与えた場合、文字列リストの合計バイト数の大まかな上限の指定になります。
前のバージョンとの互換性のために用意されています。 BZ2File オブジェクトはかつて xreadlines モジュールで提供されていたパフォーマンス最適化を含んでいます。
バージョン 2.3 で撤廃: このメソッドは file オブジェクトの同名のメソッドとの互換性の ために用意されていますが、現在は推奨されないメソッドです。代りに for line in file を使ってください。
ファイルの読み書き位置を移動します。引数 offset はバイト数で指定したオフセット値です。オプション引数 whence はデフォルトで os.SEEK_SET もしくは 0 (ファイルの先頭からのオフセットで、offset >= 0 になるはず) です。他にとり得る値は 1 (現在のファイル位置からの相対位置で、正負どちらの値もとり得る)、および 2 (ファイルの終末端からの相対位置で、通常は負の値になるが、多くのプラットフォームではファイルの終末端を越えて seek できる) です。
bz2 ファイルの seek はエミュレーションであり、パラメタの設定によっては処理が非常に低速になるかもしれないので注意してください。
現在のファイル位置を整数(long 整数になるかもしれません)で返します。
ファイルに文字列 data を書き込みます。バッファリングのため、ディスク上のファイルに書き込まれたデータを反映させるには close() が必要になるかもしれないので注意してください。
複数の文字列からなるシーケンスをファイルに書き込みます。それぞれの文字列を書き込む際に改行文字を追加することはありません。シーケンスはイテレーション処理で文字列を取り出せる任意のオブジェクトにできます。この操作はそれぞれの文字列を write() を呼んで書き込むのと同じ操作です。
逐次的な圧縮および解凍は BZ2Compressor および BZ2Decompressor クラスを用いて行います。
新しい圧縮オブジェクトを作成します。このオブジェクトはデータを逐次的に圧縮できます。一括してデータを圧縮したいのなら、代わりに compress() 関数を使ってください。 compresslevel パラメタを与える場合、この値は 1 と 9 の間の整数でなければなりません。デフォルトの値は 9 です。
圧縮オブジェクトに追加のデータを入力します。圧縮データのチャンクを生成できた場合にはチャンクを返します。圧縮データの入力を終えた後は圧縮処理を終えるために flush() を呼んでください。内部バッファに残っている未処理のデータを返します。
圧縮処理を終え、内部バッファに残されているデータを返します。このメソッドの呼び出し以降は同じ圧縮オブジェクトを使ってはなりません。
新しい解凍オブジェクトを生成します。このオブジェクトは逐次的にデータを解凍できます。一括してデータを解凍したいのなら、代わりに decompress() 関数を使ってください。
一括での圧縮および解凍を行うための関数、 compress() および decompress() が提供されています。
data を一括して圧縮します。データを逐次的に圧縮したいなら、代わりに BZ2Compressor を使ってください。もし compresslevel パラメタを与えるなら、この値は 1 から 9 の間の値をとらなくてはなりません。デフォルトの値は 9 です。
data を一括して解凍します。データを逐次的に解凍したいなら、代わりに BZ2Decompressor を使ってください。