bz2
--- bzip2 圧縮のサポート¶
ソースコード: Lib/bz2.py
このモジュールは、bzip2 アルゴリズムを用いて圧縮・展開を行う包括的なインターフェイスを提供します。
bz2
モジュールには以下のクラスや関数があります:
インクリメンタルにデータを圧縮・展開するための
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
は以下のメソッドも提供しています:-
peek
([n])¶ ファイル上の現在位置を変更せずにバッファのデータを返します。このメソッドは少なくとも 1 バイトのデータを返します (EOF の場合を除く)。返される正確なバイト数は規定されていません。
注釈
peek()
の呼び出しではBZ2File
のファイル位置は変わりませんが、下層のファイルオブジェクトの位置が変わる惧れがあります(e.g.BZ2File
を filename にファイルオブジェクトを渡して作成した場合)。バージョン 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 を受け入れるようになりました。
バージョン 3.9 で変更: buffering パラメータは削除されました。 Python 3.0 からは無視され非推奨となっています。開かれたファイルオブジェクトを渡し、ファイルの開きかたを制御します。
compresslevel パラメータはキーワード専用になりました。
-
逐次圧縮および展開¶
-
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