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

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


.. versionadded:: 2.3

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

.. For other archive formats, see the :mod:`gzip`, :mod:`zipfile`, and
   :mod:`tarfile` modules.

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

bz2 モジュールで提供されている機能を以下にまとめます:

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

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

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

* :class:`BZ2File` クラスはファイルオブジェクトで言うところの先読みアルゴリズムを用いた行単位のイテレーション機能を提供します。

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

* :func:`compress` および :func:`decompress` では一括圧縮（解凍）を関数サポートしています。

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


ファイルの圧縮（解凍）
----------------------

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


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

   bz2 ファイルを開きます。ファイルのモードは ``'r'`` (デフォルト)または ``'w'`` で、それぞれ読み出しと書き込みに対応します。
   書き出し用に開いた場合、ファイルが存在しないなら新しく作成し、そうでない場合ファイルを切り詰ます。 *buffering* パラメタを与えた場合、 ``0``
   はバッファリングなしを表し、それよりも大きい値はバッファサイズになります。デフォルトでは ``0`` です。圧縮レベル *compresslevel*
   を与える場合、値は ``1`` から ``9`` までの整数値でなければなりません。デフォルトの値は ``9`` です。
   ファイルへの入力に広範囲の改行文字バリエーションをサポートさせたい場合は ``'U'`` をファイルモードに追加します。
   入力ファイルの行末はどれも、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`` and ``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` を代りに使ってください。

