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" を使ってください。
