lzma --- LZMA アルゴリズムを使用した圧縮¶
Added in version 3.3.
ソースコード: Lib/lzma.py
このモジュールは LZMA 圧縮アルゴリズムを使用したデータ圧縮および展開のためのクラスや便利な関数を提供しています。また、xz ユーティリティを使用した .xz およびレガシーな .lzma ファイル形式へのファイルインターフェイスの他、RAW 圧縮ストリームもサポートしています。
このモジュールが提供するインターフェイスは bz2 モジュールと非常によく似ています。
LZMAFile と bz2.BZ2File はスレッドセーフでは ない 点に注意してください。
そのため、単一の LZMAFile インスタンスを複数スレッドから使用する場合は、ロックで保護する必要があります。
- 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: The.xzコンテナフォーマット。デフォルトのフォーマットです。
FORMAT_ALONE: レガシーな.lzmaコンテナフォーマット。このフォーマットは
.xzより制限があります -- インテグリティチェックや複数フィルタをサポートしていません。
FORMAT_RAW: 特定のコンテナフォーマットを使わない、生のデータストリーム。このフォーマット指定子はインテグリティチェックをサポートしておらず、(圧縮および展開双方のために) 常にカスタムフィルタチェインを指定する必要があります。さらに、この方法で圧縮されたデータは
FORMAT_AUTOを使っても展開できません (LZMADecompressorを参照)。
引数 check には圧縮データに組み込むインテグリティチェックのタイプを指定します。このチェックは展開時に使用され、データが破損していないことを保証します。以下の値が指定できます:
CHECK_NONE: インテグリティチェックなし。FORMAT_ALONEおよびFORMAT_RAWのデフォルト (かつ唯一指定可能な値) です。CHECK_CRC32: 32-bit 巡回冗長検査。CHECK_CRC64: 64-bit 巡回冗長検査。FORMAT_XZのデフォルトです。CHECK_SHA256: 256-bit セキュアハッシュアルゴリズム (SHA)。
指定したチェック方法がサポートされていない場合、
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と共に使用)
デルタフィルター:
FILTER_DELTA
ブランチコールジャンプ (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 以下でなければなりません。mf: 使用するマッチファインダ --MF_HC3、MF_HC4、MF_BT2、MF_BT3、またはMF_BT4。depth: マッチファインダが使用する検索の最大深度。0 (デフォルト) では他のフィルタオプションをベースに自動選択します。
デルタフィルターは、バイト間の差異を保存し、特定の状況で、コンプレッサーに対してさらに反復的な入力を生成します。
デルタフィルターは、1 つのオプション dist のみをサポートします。
これは差し引くバイトどうしの距離を示します。
デフォルトは 1 で、隣接するバイトの差異を扱います。
The BCJ filters are intended to be applied to machine code. They convert
relative branches, calls and jumps in the code to use absolute addressing, with
the aim of increasing the redundancy that can be exploited by the compressor.
These filters support one option, start_offset. This specifies the address
that should be mapped to the beginning of the input data. The default is 0.
使用例¶
圧縮ファイルからの読み込み:
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()
# Concatenate all the partial results:
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")