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

      注釈:

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

   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()" 呼び出しの出力に連結する必要があります。

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

      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_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 で、隣接するバイトの差異を扱います。

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_CRC64

   64 ビットの巡回冗長検査です。 "FORMAT_XZ" のデフォルトです。

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" オプションに使える圧縮モードです (カスタム
   フィルタチェインの指定 を参照)。

lzma.MF_HC3
lzma.MF_HC4
lzma.MF_BT2
lzma.MF_BT3
lzma.MF_BT4

   フィルタ指定子の "mf" オプションに使えるマッチファインダです (カス
   タムフィルタチェインの指定 を参照)。


使用例
======

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

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