13.4. `lzma` — LZMA アルゴリズムを使用した圧縮¶

バージョン 3.3 で追加.

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

このモジュールは LZMA 圧縮アルゴリズムを使用したデータ圧縮および展開のためのクラスや便利な関数を提供しています。また、xz ユーティリティを使用した .xz およびレガシーな .lzma ファイル形式へのファイルインターフェイスの他、RAW 圧縮ストリームもサポートしています。

このモジュールが提供するインターフェイスは bz2 モジュールと非常によく似ています。ただし、LZMAFile は (bz2.BZ2File と異なり) スレッドセーフではない点に注意してください。単一の LZMAFile インスタンスを複数スレッドから使用する場合は、ロックで保護する必要があります。

exception lzma.LZMAError¶: この例外は圧縮あるいは展開中にエラーが発生した場合、または圧縮/展開状態の初期化中に送出されます。

13.4.1. 圧縮ファイルへの読み書き¶

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 は無視されます)。

注釈

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

バージョン 3.4 で変更: 'x', 'xb' モードがサポートが追加されました。

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

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

13.4.2. メモリ上での圧縮と展開¶

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() 呼び出しの出力を連結したものです。

flush()¶

圧縮処理を終了し、コンプレッサの内部バッファにあるあらゆるデータを格納する bytes オブジェクトを返します。

コンプレッサはこのメソッドが呼び出された後は使用できません。

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 です。

バージョン 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 を参照してください。

13.4.3. その他¶

lzma.is_check_supported(check)¶

指定したインテグリティチェックがシステムでサポートされていれば真を返します。

CHECK_NONE および CHECK_CRC32 は常にサポートされています。CHECK_CRC64 および CHECK_SHA256 は liblzma が機能制限セットでコンパイルされている場合利用できないことがあります。

13.4.4. カスタムフィルタチェインの指定¶

フィルタチェイン指定子は、辞書のシーケンスで、各辞書は ID と単一フィルタのオプションからなります。各辞書はキー "id" を持たなければならず、フィルタ依存のオプションを指定する追加キーを持つ場合もあります。有効なフィルタ ID は以下のとおりです:

圧縮フィルタ:
- FILTER_LZMA1 (FORMAT_ALONE と共に使用)
- FILTER_LZMA2 (FORMAT_XZ および FORMAT_RAW と共に使用)
デルタフィルター:
- FILTER_DELTA
ブランチコールジャンプ (BCJ) フィルター:
- FILTER_X86
- FILTER_IA64
- FILTER_ARM
- FILTER_ARMTHUMB
- FILTER_POWERPC
- FILTER_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.

13.4.5. 使用例¶

圧縮ファイルからの読み込み:

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

13.4. `lzma` — LZMA アルゴリズムを使用した圧縮¶

13.4.1. 圧縮ファイルへの読み書き¶

13.4.2. メモリ上での圧縮と展開¶

13.4.3. その他¶

13.4.4. カスタムフィルタチェインの指定¶

13.4.5. 使用例¶

目次

前のトピックへ

次のトピックへ

このページ

13.4. lzma — LZMA アルゴリズムを使用した圧縮¶

13.4.1. 圧縮ファイルへの読み書き¶

13.4.2. メモリ上での圧縮と展開¶

13.4.3. その他¶

13.4.4. カスタムフィルタチェインの指定¶

13.4.5. 使用例¶

13.4. `lzma` — LZMA アルゴリズムを使用した圧縮¶