bz2 --- bzip2 圧縮のサポート

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


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

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

このモジュールのクラスはすべて、複数のスレッドから安全にアクセスできます。

ファイルの圧縮/解凍

bz2.open(filename, mode='r', 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) と等価です。この時、引数 encodingerrors、および newline を指定してはいけません。

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

バージョン 3.3 で追加.

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

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

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

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

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

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

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

引数 buffering は無視されます。この引数の使用は非推奨です。

If mode is 'w' or 'a', compresslevel can be an integer between 1 and 9 specifying the level of compression: 1 produces the least compression, and 9 (default) produces the most compression.

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

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

BZ2File は以下のメソッドも提供しています:

peek([n])

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

注釈

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

バージョン 3.3 で追加.

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

バージョン 3.3 で変更: fileno()readable()seekable()writable()read1()readinto() メソッドが追加されました。

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

バージョン 3.3 で変更: 'a' (追記) モードが追加され、複数のストリームの読み込みがサポートされました。

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

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

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

逐次圧縮および展開

class bz2.BZ2Compressor(compresslevel=9)

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

compresslevel, if given, must be an integer between 1 and 9. The default is 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_inputFalse に設定されます。この場合、 decompress() を次に呼び出すと、datab'' として提供し、出力をさらに取得することができます。

入力データの全てが圧縮され返された (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)

Compress data, a bytes-like object.

compresslevel, if given, must be an integer between 1 and 9. The default is 9.

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

bz2.decompress(data)

Decompress data, a bytes-like object.

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

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

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

使い方の例

Below are some examples of typical usage of the bz2 module.

Using compress() and decompress() to demonstrate round-trip compression:

>>> 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

Using BZ2Compressor for incremental compression:

>>> 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()

The example above uses a very "nonrandom" stream of data (a stream of b"z" chunks). Random data tends to compress poorly, while ordered, repetitive data usually yields a high compression ratio.

Writing and reading a bzip2-compressed file in binary mode:

>>> 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