# `bz2` --- Support for bzip2 compression

ソースコード: Lib/bz2.py

このモジュールは、bzip2 アルゴリズムを用いて圧縮・展開を行う包括的なインターフェイスを提供します。

`bz2` モジュールには以下のクラスや関数があります:

- 圧縮ファイルを読み書きするための `open()` 関数と `BZ2File` クラス。

- インクリメンタルにデータを圧縮・展開するための `BZ2Compressor` および `BZ2Decompressor` クラス。

- 一度に圧縮・展開を行う `compress()` および `decompress()` 関数。

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

bz2.open(filename, mode='rb', compresslevel=9, encoding=None, errors=None, newline=None)

  bzip2 圧縮されたファイルを、バイナリモードかテキストモードでオープンし、ファイルオブジェクト を返します。

  `BZ2File` のコンストラクタと同様に、引数 filename には実際のファイル名 (`str` または `bytes` オブジェクト) か、読み書きする既存のファイルオブジェクトを指定します。

  引数 mode には、バイナリモード用に `'r'`、`'rb'`、`'w'`、`'wb'`、`'x'`、`'xb'`、`'a'`、あるいは `'ab'`、テキストモード用に `'rt'`、`'wt'`、`'xt'`、あるいは `'at'` を指定できます。デフォルトは `'rb'` です。

  引数 compresslevel には `BZ2File` コンストラクタと同様に 1 から 9 の整数を指定します。

  バイナリモードでは、この関数は `BZ2File` コンストラクタ `BZ2File(filename, mode, compresslevel=compresslevel)` と等価です。この時、引数 encoding、errors、および newline を指定してはいけません。

  テキストモードでは、`BZ2File` オブジェクトが作成され、指定されたエンコーディング、エラーハンドラの挙動、および改行文字で `io.TextIOWrapper` にラップされます。

  バージョン 3.3 で追加.

  バージョン 3.4 で変更: `'x'` (排他的作成) モードが追加されました。

  バージョン 3.6 で変更: path-like object を受け入れるようになりました。

class bz2.BZ2File(filename, mode='r', *, compresslevel=9)

  bzip2 圧縮ファイルをバイナリモードでオープンします。

  filename が `str` あるいは `bytes` オブジェクトの場合、それを名前とするファイルを直接開きます。そうでない場合、filename は圧縮データを読み書きする ファイルオブジェクト でなくてはなりません。

  引数 mode は読み込みモードの `'r'` (デフォルト)、上書きモードの `'w'`、排他的作成モードの `'x'`、あるいは追記モードの `'a'` のいずれかを指定できます。これらはそれぞれ `'rb'`、`'wb'`、`'xb'` および `'ab'` と等価です。

  filename が (実際のファイル名でなく) ファイルオブジェクトの場合、`'w'` はファイルを上書きせず、`'a'` と等価になります。

  mode が `'w'` あるいは `'a'` の場合、compresslevel に圧縮レベルを `1` から `9` の整数で指定できます。 圧縮率は `1` が最低で、`9` (デフォルト値) が最高です。

  mode の値が `'r'` の場合、入力ファイルは複数の圧縮ストリームでも構いません。

  `BZ2File` には、 `io.BufferedIOBase` で規定されているメソッドや属性のうち、 `detach()` と `truncate()` を除くすべてが備わっています。イテレーションと `with` 文をサポートしています。

  `BZ2File` also provides the following methods:

  peek([n])

    ファイル上の現在位置を変更せずにバッファのデータを返します。このメソッドは少なくとも 1 バイトのデータを返します (EOF の場合を除く)。返される正確なバイト数は規定されていません。

    注釈

    `peek()` の呼び出しでは `BZ2File` のファイル位置は変わりませんが、下層のファイルオブジェクトの位置が変わる惧れがあります(e.g. `BZ2File` を filename にファイルオブジェクトを渡して作成した場合)。

    バージョン 3.3 で追加.

  fileno()

    Return the file descriptor for the underlying file.

    バージョン 3.3 で追加.

  readable()

    Return whether the file was opened for reading.

    バージョン 3.3 で追加.

  seekable()

    Return whether the file supports seeking.

    バージョン 3.3 で追加.

  writable()

    Return whether the file was opened for writing.

    バージョン 3.3 で追加.

  read1(size=-1)

    Read up to size uncompressed bytes, while trying to avoid making multiple reads from the underlying stream. Reads up to a buffer's worth of data if size is negative.

    Returns `b''` if the file is at EOF.

    バージョン 3.3 で追加.

  readinto(b)

    Read bytes into b.

    Returns the number of bytes read (0 for EOF).

    バージョン 3.3 で追加.

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

  バージョン 3.3 で変更: filename が実際のファイル名でなく ファイルオブジェクト だった場合のサポートが追加されました。

  `'a'` (追記) モードが追加され、複数のストリームの読み込みがサポートされました。

  バージョン 3.4 で変更: `'x'` (排他的作成) モードが追加されました。

  バージョン 3.5 で変更: `read()` メソッドが `None` を引数として受け取るようになりました。

  バージョン 3.6 で変更: path-like object を受け入れるようになりました。

  バージョン 3.9 で変更: buffering パラメータは削除されました。 Python 3.0 からは無視され非推奨となっています。開かれたファイルオブジェクトを渡し、ファイルの開きかたを制御します。

  compresslevel パラメータはキーワード専用になりました。

  バージョン 3.10 で変更: このクラスは、複数の同時読み出しや書き込みにおいては、既存の `gzip` や `lzma` などの同等のクラスのように、スレッド安全ではありません。

## 逐次圧縮および展開

class bz2.BZ2Compressor(compresslevel=9)

  新しくコンプレッサオブジェクトを作成します。このオブジェクトはデータの逐次的な圧縮に使用できます。一度に圧縮したい場合は、`compress()` 関数を使ってください。

  引数 compresslevel を指定する場合は、`1` から `9` までの整数を与えてください。 デフォルト値は `9` です。

  compress(data)

    データをコンプレッサオブジェクトに渡します。戻り値は圧縮されたデータですが、圧縮データを返すことができない場合は空のバイト文字列を返します。

    コンプレッサオブジェクトにデータをすべて渡し終えたら、`flush()` メソッドを呼び出し、圧縮プロセスを完了させてください。

  flush()

    圧縮プロセスを完了させ、内部バッファに残っている圧縮済みデータを返します。

    このメソッドを呼び出すと、それ以後コンプレッサオブジェクトは使用できなくなります。

class bz2.BZ2Decompressor

  新しくデコンプレッサオブジェクトを作成します。このオブジェクトは逐次的なデータ展開に使用できます。一度に展開したい場合は、`decompress()` 関数を使ってください。

  注釈

  このクラスは、`decompress()` や `BZ2File` とは異なり、複数の圧縮レベルが混在しているデータを透過的に扱うことができません。 `BZ2Decompressor` クラスを用いて、複数のストリームからなるデータを展開する場合は、それぞれのストリームについてデコンプレッサオブジェクトを用意してください。

  decompress(data, max_length=-1)

    data (bytes-like object) を展開し、未圧縮のデータを bytes で返します。 data の一部は、後で `decompress()` の呼び出しに使用するため内部でバッファされている場合があります。 返されたデータは、以前の `decompress()` の呼び出しの出力に連結する必要があります。

    max_length が非負の場合、最大 max_length バイトの展開データを返します。この制限に達して、出力がさらに生成できる場合、 `needs_input` が `False` に設定されます。この場合、 `decompress()` を次に呼び出すと、data を `b''` として提供し、出力をさらに取得することができます。

    入力データの全てが圧縮され返された (max_length バイトより少ないためか max_length が負のため) 場合、 `needs_input` 属性は `True` になります。

    ストリームの終端に到達した後にデータを展開しようとすると `EOFError` が送出されます。 ストリームの終端の後ろの全てのデータは無視され、その部分は `unused_data` 属性に保存されます。

    バージョン 3.5 で変更: `max_length` パラメータが追加されました。

  eof

    ストリーム終端記号に到達した場合 `True` を返します。

    バージョン 3.3 で追加.

  unused_data

    圧縮ストリームの末尾以降に存在したデータを表します。

    ストリームの末尾に達する前には、この属性には `b''` という値が収められています。

  needs_input

    `decompress()` メソッドが、新しい非圧縮入力を必要とせずにさらに展開データを提供できる場合、 `False` です。

    バージョン 3.5 で追加.

## 一括圧縮/解凍

bz2.compress(data, compresslevel=9)

  バイト類オブジェクト の data を圧縮します。

  引数 compresslevel を指定する場合は、`1` から `9` までの整数を与えてください。 デフォルト値は `9` です。

  逐次的にデータを圧縮したい場合は、`BZ2Compressor` を使ってください。

bz2.decompress(data)

  バイト類オブジェクト の data を展開します。

  data が複数の圧縮ストリームから成る場合、そのすべてを展開します。

  逐次的に展開を行う場合は、`BZ2Decompressor` を使ってください。

  バージョン 3.3 で変更: 複数ストリームの入力をサポートしました。

## 使い方の例

以下は、典型的な `bz2` モジュールの利用方法です。

`compress()` と `decompress()` を使い、圧縮して展開する実演をしています:

    >>> import bz2
    >>> data = b"""\
    ... Donec rhoncus quis sapien sit amet molestie. Fusce scelerisque vel augue
    ... nec ullamcorper. Nam rutrum pretium placerat. Aliquam vel tristique lorem,
    ... sit amet cursus ante. In interdum laoreet mi, sit amet ultrices purus
    ... pulvinar a. Nam gravida euismod magna, non varius justo tincidunt feugiat.
    ... Aliquam pharetra lacus non risus vehicula rutrum. Maecenas aliquam leo
    ... felis. Pellentesque semper nunc sit amet nibh ullamcorper, ac elementum
    ... dolor luctus. Curabitur lacinia mi ornare consectetur vestibulum."""
    >>> c = bz2.compress(data)
    >>> len(data) / len(c)  # Data compression ratio
    1.513595166163142
    >>> d = bz2.decompress(c)
    >>> data == d  # Check equality to original object after round-trip
    True

`BZ2Compressor` を使い、逐次圧縮をしています:

    >>> import bz2
    >>> def gen_data(chunks=10, chunksize=1000):
    ...     """Yield incremental blocks of chunksize bytes."""
    ...     for _ in range(chunks):
    ...         yield b"z" * chunksize
    ...
    >>> comp = bz2.BZ2Compressor()
    >>> out = b""
    >>> for chunk in gen_data():
    ...     # Provide data to the compressor object
    ...     out = out + comp.compress(chunk)
    ...
    >>> # Finish the compression process.  Call this once you have
    >>> # finished providing data to the compressor.
    >>> out = out + comp.flush()

上の例は、非常に "ランダムでない" データストリーム (チャンク `b"z"` のストリーム) です。 ランダムなデータは圧縮率が低い傾向にある一方、揃っていて、繰り返しのあるデータは通常は高い圧縮率を叩き出します。

bzip2 圧縮されたファイルをバイナリモードで読み書きしています:

    >>> import bz2
    >>> data = b"""\
    ... Donec rhoncus quis sapien sit amet molestie. Fusce scelerisque vel augue
    ... nec ullamcorper. Nam rutrum pretium placerat. Aliquam vel tristique lorem,
    ... sit amet cursus ante. In interdum laoreet mi, sit amet ultrices purus
    ... pulvinar a. Nam gravida euismod magna, non varius justo tincidunt feugiat.
    ... Aliquam pharetra lacus non risus vehicula rutrum. Maecenas aliquam leo
    ... felis. Pellentesque semper nunc sit amet nibh ullamcorper, ac elementum
    ... dolor luctus. Curabitur lacinia mi ornare consectetur vestibulum."""
    >>> with bz2.open("myfile.bz2", "wb") as f:
    ...     # Write compressed data to file
    ...     unused = f.write(data)
    >>> with bz2.open("myfile.bz2", "rb") as f:
    ...     # Decompress data from file
    ...     content = f.read()
    >>> content == data  # Check equality to original object after round-trip
    True