"lzma" --- LZMA アルゴリズムを使用した圧縮
******************************************

バージョン 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* は無視されます)。

      注釈:

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

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

   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" を参照してください。


その他
======

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


使用例
======

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

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