:mod:`bz2` --- :program:`bzip2` 互換の圧縮ライブラリ
====================================================

.. module:: bz2
   :synopsis: bzip2 互換の圧縮／解凍ルーチンへのインタフェース
.. moduleauthor:: Gustavo Niemeyer <niemeyer@conectiva.com>
.. sectionauthor:: Gustavo Niemeyer <niemeyer@conectiva.com>


.. versionadded:: 2.3

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

その他のアーカイブフォーマットに関しては、 :mod:`gzip`, :mod:`zipfile`,
:mod:`tarfile` モジュールを参照してください。

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

* :class:`BZ2File` クラスは、 :meth:`~BZ2File.readline`,
  :meth:`~BZ2File.readlines`, :meth:`~BZ2File.writelines`, :meth:`~BZ2File.seek`
  等を含む、完全なファイルインタフェースを実装します。

* :class:`BZ2File` クラスは :meth:`~BZ2File.seek` をエミュレーションで
  サポートします。

* :class:`BZ2File` クラスは広範囲の改行文字バリエーション(universal newline)
  をサポートします。

* :class:`BZ2File` クラスは、ファイルオブジェクトの先読みアルゴリズムを元にして
  実装されている、最適化された行単位のイテレーション機能を提供します。

* :class:`BZ2Compressor` および :class:`BZ2Decompressor` クラスでは逐次的圧縮
  （解凍）をサポートしています。

* :func:`compress` および :func:`decompress` 関数は、一括圧縮/解凍機能を
  提供しています。

* 個別のロックメカニズムによってスレッド安全性を持っています。


ファイルの圧縮/解凍
----------------------

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


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

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


   .. method:: close()

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


   .. method:: read([size])

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


   .. method:: readline([size])

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


   .. method:: readlines([size])

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


   .. method:: xreadlines()

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

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


   .. method:: seek(offset[, whence])

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

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


   .. method:: tell()

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


   .. method:: write(data)

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


   .. method:: writelines(sequence_of_strings)

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


逐次的な圧縮/解凍
--------------------

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


.. class:: BZ2Compressor([compresslevel])

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


   .. method:: compress(data)

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


   .. method:: flush()

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


.. class:: BZ2Decompressor()

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


   .. method:: decompress(data)

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


一括圧縮/解凍
----------------

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


.. function:: compress(data[, compresslevel])

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


.. function:: decompress(data)

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

