lzma --- LZMA アルゴリズムを使用した圧縮¶
Added in version 3.3.
ソースコード: Lib/lzma.py
このモジュールは LZMA 圧縮アルゴリズムを使用したデータ圧縮および展開のためのクラスや便利な関数を提供しています。また、xz ユーティリティを使用した .xz およびレガシーな .lzma ファイル形式へのファイルインターフェイスの他、RAW 圧縮ストリームもサポートしています。
このモジュールが提供するインターフェイスは bz2 モジュールと非常によく似ています。
LZMAFile と bz2.BZ2File はスレッドセーフでは ない 点に注意してください。
そのため、単一の LZMAFile インスタンスを複数スレッドから使用する場合は、ロックで保護する必要があります。
これは optional module です。 使用している CPython に含まれていない場合は、配布元 (Python を提供した組織や個人) のドキュメントを探してください。 自分が配布元である場合は、オプションのモジュールの要件 を参照してください。
- exception lzma.LZMAError¶
圧縮や展開の処理中、またはコンプレッサやデコンプレッサの状態を初期化している間にエラーが起きると、この例外が送出されます。
圧縮ファイルへの読み書き¶
- lzma.open(filename, mode='rb', *, format=None, check=-1, preset=None, filters=None, encoding=None, errors=None, newline=None)¶
LZMA 圧縮ファイルをバイナリまたはテキストモードでオープンし、ファイルオブジェクト を返します。
filename 引数には、ファイルをオープンする際には実際のファイル名 (
str、bytes、または path-like オブジェクトとして指定します)か、読み込みまたは書き込むためであれば、すでに存在するファイルオブジェクトを指定できます。引数 mode は、バイナリモードでは
"r"、"rb"、"w"、"wb"、"x"、"xb"、"a"、あるいは"ab"の、テキストモードでは"rt"、"wt"、"xt"、あるいは"at"のいずれかになります。デフォルトは"rb"です。読み込み用にファイルをオープンした場合、引数 format および filters は
LZMADecompressorと同じ意味になります。この時、引数 check および preset は使用しないでください。書き出し用にオープンした場合、引数 format、check、preset、および filters は
LZMACompressorと同じ意味になります。バイナリモードでは、この関数は
LZMAFileコンストラクタと等価になります (LZMAFile(filename, mode, ...))。 この場合、引数 encoding、errors、および newline を指定してはいけません。テキストモードでは、
LZMAFileオブジェクトが生成され、指定したエンコーディング、エラーハンドラの挙動、および改行コードでio.TextIOWrapperにラップされます。バージョン 3.4 で変更:
"x","xb","xt"モードのサポートが追加されました。バージョン 3.6 で変更: path-like object を受け入れるようになりました。
- class lzma.LZMAFile(filename=None, mode='r', *, format=None, check=-1, preset=None, filters=None)¶
LZMA 圧縮ファイルをバイナリモードで開きます。
LZMAFileはすでにオープンしている file object をラップ、または名前付きファイルを直接操作できます。引数 filename にはラップするファイルオブジェクトかオープンするファイル名 (strオブジェクトま、bytesオブジェクト、または path-like オブジェクト) を指定します。既存のファイルオブジェクトをラップした場合、LZMAFileをクローズしてもラップしたファイルはクローズされません。引数 mode は読み込みモードの
"r"(デフォルト)、上書きモードの"w"、排他的生成モードの"x"、あるいは追記モードの"a"のいずれかを指定できます。これらはそれぞれ"rb"、"wb"、"xb"、および"ab"と等価です。filename が (実際のファイル名でなく) ファイルオブジェクトの場合、
"w"モードはファイルを切り詰めず、"a"と等価になります。読み込みモードでファイルをオープンした時、入力ファイルは複数に分割された圧縮ストリームを連結したものでもかまいません。これらは透過的に単一論理ストリームとしてデコードされます。
読み込み用にファイルをオープンした場合、引数 format および filters は
LZMADecompressorと同じ意味になります。この時、引数 check および preset は使用しないでください。書き出し用にオープンした場合、引数 format、check、preset、および filters は
LZMACompressorと同じ意味になります。LZMAFileには、io.BufferedIOBaseで規定されているメソッドや属性のうち、detach()とtruncate()を除くすべてが備わっています。イテレーションとwith文をサポートしています。以下のメソッドと属性も提供されています:
- peek(size=-1)¶
ファイル上の現在位置を変更せずにバッファのデータを返します。EOF に達しない限り、少なくとも 1 バイトが返されます。返される正確なバイト数は規定されていません (引数 size は無視されます)。
- mode¶
'rb'は読み込み用、'wb'は書き込み用です。Added in version 3.13.
- name¶
lzma ファイルの名前。基礎である file object の
name属性と同様です。Added in version 3.13.
バージョン 3.4 で変更:
'x','xb'モードがサポートが追加されました。バージョン 3.5 で変更:
read()メソッドがNoneを引数として受け取るようになりました。バージョン 3.6 で変更: path-like object を受け入れるようになりました。
メモリ上での圧縮と展開¶
- class lzma.LZMACompressor(format=FORMAT_XZ, check=-1, preset=None, filters=None)¶
データをインクリメンタルに圧縮する圧縮オブジェクトを作成します。
ひとまとまりのデータを圧縮する、より便利な方法については
compress()を参照してください。format 引数は、使用するコンテナ形式を指定します。 指定できる値は
FORMAT_XZ(デフォルト)、FORMAT_ALONE、FORMAT_RAWです。check 引数は、圧縮データに含めるインテグリティチェックの種類を指定します。 このチェックは展開時に、データが破損していないことを確認するために使います。 指定できる値は
CHECK_NONE、CHECK_CRC32、CHECK_CRC64(FORMAT_XZのデフォルト)、CHECK_SHA256です。指定したチェック方法がサポートされていない場合、
LZMAErrorが送出されます。圧縮設定はプリセット圧縮レベル (引数 preset で指定) またはカスタムフィルタチェイン (引数 filters で指定) のどちらかを指定します。
引数 preset を指定する場合、
0から9までの整数値でなければならず、オプションで定数PRESET_EXTREMEを論理和指定できます。preset も filters も指定されなかった場合、デフォルトの挙動としてPRESET_DEFAULT(プリセットレベル6) が使用されます。高いプリセット値を指定すると圧縮率が上がりますが、圧縮にかかる時間が長くなります。注釈
CPU の使用量が多いのに加えて、高いプリセットで圧縮を行うには、メモリをずっと多く必要とします (さらに、生成される出力も展開により多くのメモリを必要とします)。例えば、プリセットが
9の場合、LZMACompressorオブジェクトのオーバーヘッドは 800 MiB にまで高くなる場合があります。このため、通常はデフォルトのプリセットを使用するのがよいでしょう。引数 filters を指定する場合、フィルタチェイン指定子でなければなりません。詳しくは カスタムフィルタチェインの指定 を参照してください。
- compress(data)¶
data (
bytesオブジェクト) を圧縮し、入力の少なくとも一部を圧縮したデータを含むbytesオブジェクトを返します。 data の一部は、後でcompress()およびflush()の呼び出しに使用するため内部でバッファされている場合があります。 返されたデータは、以前のcompress()呼び出しの出力に連結する必要があります。
- class lzma.LZMADecompressor(format=FORMAT_AUTO, memlimit=None, filters=None)¶
データをインクリメンタルに展開するために使用できる展開オブジェクトを作成します。
圧縮されたストリーム全体を一度に展開にする、より便利な方法については、
decompress()を参照してください。引数 format には使用するコンテナフォーマットを指定します。デフォルトは
FORMAT_AUTOで、.xzおよび.lzmaファイルを展開できます。その他に指定できる値は、FORMAT_XZ、FORMAT_ALONE、およびFORMAT_RAWです。引数 memlimit にはデコンプレッサが使用できるメモリ量をバイトで指定します。この引数を指定した場合、そのメモリ量で展開ができないと
LZMAErrorを送出します。引数 filters には、展開するストリームの作成時に使ったフィルタチェインを指定します。 format が
FORMAT_RAWの場合は必須ですが、他の形式では指定しないでください。 フィルタチェインの詳細は カスタムフィルタチェインの指定 を参照してください。注釈
このクラスは
decompress()およびLZMAFileと異なり、複数の圧縮ストリームを含む入力を透過的に扱いません。LZMADecompressorで複数ストリーム入力を展開するには、各ストリームごとに新しいデコンプレッサを作成しなければなりません。- 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パラメータが追加されました。
- check¶
入力ストリームに使用されるインテグリティチェックの ID です。これは何のインテグリティチェックが使用されているか決定するために十分な入力がデコードされるまでは
CHECK_UNKNOWNになることがあります。
- eof¶
ストリーム終端記号に到達した場合
Trueを返します。
- unused_data¶
圧縮ストリームの末尾以降に存在したデータを表します。
ストリームの末尾に達する前は、これは
b""になります。
- needs_input¶
decompress()メソッドが、新しい非圧縮入力を必要とせずにさらに展開データを提供できる場合、Falseです。Added in version 3.5.
- lzma.compress(data, format=FORMAT_XZ, check=-1, preset=None, filters=None)¶
data (
bytesオブジェクト) を圧縮し、圧縮データをbytesオブジェクトとして返します。引数 format、check、preset、および filters についての説明は上記の
LZMACompressorを参照してください。
- lzma.decompress(data, format=FORMAT_AUTO, memlimit=None, filters=None)¶
data (
bytesオブジェクト) を展開し、展開データをbytesオブジェクトとして返します。data が複数の明確な圧縮ストリームの連結だった場合、すべてのストリームを展開し、結果の連結を返します。
引数 format、memlimit、および filters の説明は、上記
LZMADecompressorを参照してください。
その他¶
- lzma.is_check_supported(check)¶
指定したインテグリティチェックがシステムでサポートされていれば
Trueを返します。CHECK_NONEおよびCHECK_CRC32は常にサポートされています。CHECK_CRC64およびCHECK_SHA256は liblzma が機能制限セットでコンパイルされている場合利用できないことがあります。
カスタムフィルタチェインの指定¶
フィルタチェイン指定子は、辞書のシーケンスで、各辞書は ID と単一フィルタのオプションからなります。各辞書はキー "id" を持たなければならず、フィルタ依存のオプションを指定する追加キーを持つ場合もあります。有効なフィルタ ID は以下のとおりです:
圧縮フィルタ:
FILTER_LZMA1(FORMAT_ALONEと共に使用)FILTER_LZMA2(FORMAT_XZおよびFORMAT_RAWと共に使用)
デルタフィルター:
ブランチコールジャンプ (BCJ) フィルター:
FILTER_X86FILTER_IA64FILTER_ARMFILTER_ARMTHUMBFILTER_POWERPCFILTER_SPARC
一つのフィルタチェインは 4 個までのフィルタを定義することができ、空にはできません。チェインの最後は圧縮フィルタでなくてはならず、その他のフィルタはデルタまたは BCJ フィルタでなければなりません。
圧縮フィルタは以下のオプション (追加エントリとしてフィルタを表す辞書に指定) をサポートしています:
preset: 明示されていないオプションのデフォルト値のソースとして使用する圧縮プリセット。dict_size: 辞書のサイズのバイト数。これは、 4 KiB から 1.5 GiB の間にしてください (両端を含みます)。lc: リテラルコンテキストビットの数。lp: リテラル位置ビットの数。lc + lpで最大 4 までです。pb: 位置ビットの数。最大で 4 までです。mode:MODE_FASTまたはMODE_NORMAL。nice_len: マッチに "良い" とみなす長さ。273 以下でなければなりません。depth: マッチファインダが使用する検索の最大深度。0 (デフォルト) では他のフィルタオプションをベースに自動選択します。
デルタフィルターは、バイト間の差異を保存し、特定の状況で、コンプレッサーに対してさらに反復的な入力を生成します。
デルタフィルターは、1 つのオプション dist のみをサポートします。
これは差し引くバイトどうしの距離を示します。
デフォルトは 1 で、隣接するバイトの差異を扱います。
BCJ フィルターはマシンコードに適用するためのものです。
コード内の相対的な分岐、呼び出し、ジャンプを絶対アドレス指定に変換し、コンプレッサが利用できる冗長性を増やします。
これらのフィルターは start_offset というオプションを 1 つサポートします。
入力データの先頭に対応するアドレスを指定するもので、デフォルトは 0 です。
定数¶
以下のモジュールレベルの定数は、上記のクラスや関数の format、check、preset、filters 引数で使うために提供されています。
コンテナ形式:
- lzma.FORMAT_XZ¶
.xzコンテナ形式。
- lzma.FORMAT_ALONE¶
従来の
.lzmaコンテナ形式です。.xzより制限が多く、インテグリティチェックや複数のフィルタをサポートしません。
- lzma.FORMAT_RAW¶
コンテナ形式を使わない生のデータストリームです。 この形式指定子はインテグリティチェックをサポートせず、圧縮でも展開でも必ずカスタムフィルタチェインを指定する必要があります。 また、この方法で圧縮したデータは
FORMAT_AUTOでは展開できません。
- lzma.FORMAT_AUTO¶
展開時にのみ使います。 コンテナ形式を自動検出するので、
.xzと.lzmaの両方のファイルを展開できます。
インテグリティチェック:
- lzma.CHECK_NONE¶
インテグリティチェックを行いません。
FORMAT_ALONEとFORMAT_RAWではデフォルトであり、指定できる唯一の値です。
- lzma.CHECK_CRC32¶
32 ビットの巡回冗長検査。
- lzma.CHECK_SHA256¶
256 ビットの Secure Hash Algorithm。
- lzma.CHECK_UNKNOWN¶
ストリームが使用するインテグリティチェックをまだ判定できていません。 十分な入力をデコードするまで、
LZMADecompressor.check属性はこの値になる場合があります。
- lzma.CHECK_ID_MAX¶
サポートされているインテグリティチェック ID の最大値。
圧縮プリセット:
- lzma.PRESET_DEFAULT¶
デフォルトの圧縮プリセットで、プリセットレベル
6と等価です。
- lzma.PRESET_EXTREME¶
プリセットレベル (
0から9) とビット単位 OR で組み合わせられるフラグです。 速度は落ちますが、そのプリセットのより入念に圧縮する方式を選べます。
フィルタの ID とオプション:
- lzma.FILTER_LZMA1¶
- lzma.FILTER_LZMA2¶
LZMA1 と LZMA2 の圧縮フィルタです。
FILTER_LZMA1はFORMAT_ALONEと、FILTER_LZMA2はFORMAT_XZおよびFORMAT_RAWとともに使います。
- lzma.FILTER_DELTA¶
デルタフィルタ。
- lzma.MODE_FAST¶
- lzma.MODE_NORMAL¶
フィルタ指定子の
modeオプションに使える圧縮モードです (カスタムフィルタチェインの指定 を参照)。
使用例¶
圧縮ファイルからの読み込み:
import lzma
with lzma.open("file.xz") as f:
file_content = f.read()
圧縮ファイルの作成:
import lzma
data = b"Insert Data Here"
with lzma.open("file.xz", "w") as f:
f.write(data)
メモリ上でデータを圧縮:
import lzma
data_in = b"Insert Data Here"
data_out = lzma.compress(data_in)
逐次圧縮:
import lzma
lzc = lzma.LZMACompressor()
out1 = lzc.compress(b"Some data\n")
out2 = lzc.compress(b"Another piece of data\n")
out3 = lzc.compress(b"Even more data\n")
out4 = lzc.flush()
# すべての部分的な結果を連結する:
result = b"".join([out1, out2, out3, out4])
すでにオープンしているファイルへの圧縮データの書き出し:
import lzma
with open("file.xz", "wb") as f:
f.write(b"This data will not be compressed\n")
with lzma.open(f, "w") as lzf:
lzf.write(b"This *will* be compressed\n")
f.write(b"Not compressed\n")
カスタムフィルタチェインを使った圧縮ファイルの作成:
import lzma
my_filters = [
{"id": lzma.FILTER_DELTA, "dist": 5},
{"id": lzma.FILTER_LZMA2, "preset": 7 | lzma.PRESET_EXTREME},
]
with lzma.open("file.xz", "w", filters=my_filters) as f:
f.write(b"blah blah blah")