"compression.zstd" --- Zstandard 形式に対応した圧縮
***************************************************

Added in version 3.14.

**ソースコード:** Lib/compression/zstd/__init__.py

======================================================================

このモジュールは、Zstandard (または *zstd*) 圧縮アルゴリズムを使ってデ
ータを圧縮・展開するクラスと関数を提供します。 zstd マニュアル では、
Zstandard を「zlib と同等以上の圧縮率で、リアルタイム圧縮を対象とした
高速な可逆圧縮アルゴリズム」と説明しています。 **zstd** ユーティリティ
で作成した ".zst" ファイルの内容や、生の zstd 圧縮ストリームの読み書き
をサポートするファイルインターフェースも含まれています。

"compression.zstd" モジュールには次のものが含まれています:

* 圧縮ファイルを読み書きする "open()" 関数と "ZstdFile" クラス。

* インクリメンタルに圧縮・展開を行う "ZstdCompressor" クラスと
  "ZstdDecompressor" クラス。

* 一度に圧縮・展開を行う "compress()" および "decompress()" 関数。

* Zstandard 辞書を学習・管理する "train_dict()" 関数、
  "finalize_dict()" 関数、"ZstdDict" クラス。

* 圧縮・展開の高度なパラメータを設定する "CompressionParameter" クラス
  、"DecompressionParameter" クラス、"Strategy" クラス。

これは *オプションのモジュール* です。 お使いの CPython に含まれていな
い場合は、配布元 (Python を提供した組織や人) のドキュメントを確認して
ください。 配布する側の方は、オプションのモジュールの要件 を参照してく
ださい。


例外
====

exception compression.zstd.ZstdError

   圧縮・展開中、または圧縮・展開オブジェクトの状態の初期化中にエラー
   が発生すると送出される例外です。


圧縮ファイルへの読み書き
========================

compression.zstd.open(file, /, mode='rb', *, level=None, options=None, zstd_dict=None, encoding=None, errors=None, newline=None)

   Zstandard で圧縮されたファイルをバイナリモードまたはテキストモード
   で開き、*ファイルオブジェクト* を返します。

   *file* 引数には、ファイル名 ("str"、"bytes"、または *パス状オブジェ
   クト*) を指定でき、その場合はその名前のファイルを開きます。 また、
   読み書きする既存のファイルオブジェクトも指定できます。

   "mode" 引数には、読み込み用 (デフォルト) の "'rb'"、上書き用の
   "'wb'"、追記用の "'ab'"、排他的な作成用の "'xb'" のいずれかを指定で
   きます。 それぞれ "'r'"、"'w'"、"'a'"、"'x'" と指定しても同じです。
   それぞれ "'rt'"、"'wt'"、"'at'"、"'xt'" を指定してテキストモードで
   開くこともできます。

   読み込み時には、展開の高度なパラメータを指定する辞書を *options* 引
   数に渡せます。 サポートされるパラメータの詳細は
   "DecompressionParameter" を参照してください。 *zstd_dict* 引数は、
   展開時に使う "ZstdDict" インスタンスです。 読み込み時に *level* 引
   数が "None" でない場合は "TypeError" を送出します。

   書き込み時には、圧縮の高度なパラメータを指定する辞書を *options* 引
   数に渡せます。 サポートされるパラメータの詳細は
   "CompressionParameter" を参照してください。 *level* 引数は、圧縮デ
   ータを書き込む際の圧縮レベルです。 *level* と *options* のうち、
   "None" 以外にできるのは一方だけです。 *zstd_dict* 引数は、圧縮時に
   使う "ZstdDict" インスタンスです。

   バイナリモードでは、この関数は "ZstdFile" コンストラクタ
   "ZstdFile(file, mode, ...)" と等価です。 この場合、*encoding*、
   *errors*、*newline* パラメータを指定してはいけません。

   テキストモードでは、"ZstdFile" オブジェクトを作成し、指定されたエン
   コーディング、エラー処理、改行文字で "io.TextIOWrapper" インスタン
   スにラップします。

class compression.zstd.ZstdFile(file, /, mode='rb', *, level=None, options=None, zstd_dict=None)

   Zstandard で圧縮されたファイルをバイナリモードで開きます。

   "ZstdFile" は、すでに開かれた *ファイルオブジェクト* をラップするこ
   とも、名前で指定したファイルを直接操作することもできます。 *file*
   引数には、ラップするファイルオブジェクトか、開くファイルの名前
   ("str"、"bytes"、または *パス状オブジェクト*) を指定します。 既存の
   ファイルオブジェクトをラップした場合、"ZstdFile" を閉じても、ラップ
   されたファイルは閉じられません。

   *mode* 引数には、読み込み用 (デフォルト) の "'rb'"、上書き用の
   "'wb'"、排他的な作成用の "'xb'"、追記用の "'ab'" のいずれかを指定で
   きます。 それぞれ "'r'"、"'w'"、"'x'"、"'a'" と指定しても同じです。

   *file* が実際のファイル名ではなくファイルオブジェクトの場合、モード
   "'w'" はファイルを切り詰めず、"'a'" と等価になります。

   読み込み時には、展開の高度なパラメータを指定する辞書を *options* 引
   数に渡せます。 サポートされるパラメータの詳細は
   "DecompressionParameter" を参照してください。 *zstd_dict* 引数は、
   展開時に使う "ZstdDict" インスタンスです。 読み込み時に *level* 引
   数が "None" でない場合は "TypeError" を送出します。

   書き込み時には、圧縮の高度なパラメータを指定する辞書を *options* 引
   数に渡せます。 サポートされるパラメータの詳細は
   "CompressionParameter" を参照してください。 *level* 引数は、圧縮デ
   ータを書き込む際の圧縮レベルです。 *level* と *options* は、一方し
   か渡せません。 *zstd_dict* 引数は、圧縮時に使う "ZstdDict" インスタ
   ンスです。

   "ZstdFile" は、"detach()" と "truncate()" を除き、
   "io.BufferedIOBase" で規定されたすべてのメンバーをサポートします。
   反復処理と "with" 文もサポートします。

   以下のメソッドと属性も提供されています:

   peek(size=-1)

      ファイル上の現在位置を変更せずにバッファのデータを返します。EOF
      に達しない限り、少なくとも 1 バイトが返されます。返される正確な
      バイト数は規定されていません (引数 *size* は無視されます)。

      注釈:

        "peek()" を呼び出しても "ZstdFile" のファイル位置は変わりませ
        んが、基となるファイルオブジェクトの位置は変わる場合があります
        (例えば、*file* にファイルオブジェクトを渡して "ZstdFile" を構
        築した場合)。

   mode

      "'rb'" は読み込み用、 "'wb'" は書き込み用です。

   name

      Zstandard ファイルの名前です。 基となる *ファイルオブジェクト*
      の "name" 属性と等価です。


メモリ上での圧縮と展開
======================

compression.zstd.compress(data, level=None, options=None, zstd_dict=None)

   *data* (*バイト列状オブジェクト*) を圧縮し、圧縮データを "bytes" オ
   ブジェクトとして返します。

   *level* 引数は、圧縮レベルを制御する整数です。 *level* は、
   *options* に "CompressionParameter.compression_level" を設定する代
   わりに使えます。 *level* に渡せる値を取得するには、
   "compression_level" の "bounds()" を使ってください。 高度な圧縮オプ
   ションが必要な場合は *level* 引数を省略し、*options* 辞書に
   "CompressionParameter.compression_level" パラメータを設定してくださ
   い。

   *options* 引数は、高度な圧縮パラメータを含む Python の辞書です。 圧
   縮パラメータの有効なキーと値は、"CompressionParameter" のドキュメン
   トに記載されています。

   *zstd_dict* 引数は、圧縮効率を改善するための学習済みデータを含む
   "ZstdDict" インスタンスです。 Zstandard 辞書を生成するには
   "train_dict()" 関数を使えます。

compression.zstd.decompress(data, zstd_dict=None, options=None)

   *data* (*バイト列状オブジェクト*) を展開し、展開したデータを
   "bytes" オブジェクトとして返します。

   *options* 引数は、高度な展開パラメータを含む Python の辞書です。 パ
   ラメータの有効なキーと値は、"DecompressionParameter" のドキュメント
   に記載されています。

   *zstd_dict* 引数は、圧縮時に使った学習済みデータを含む "ZstdDict"
   インスタンスです。 圧縮時に使ったものと同じ Zstandard 辞書でなけれ
   ばなりません。

   *data* が複数の独立した圧縮フレームを連結したものである場合、すべて
   のフレームを展開し、その結果を連結して返します。

class compression.zstd.ZstdCompressor(level=None, options=None, zstd_dict=None)

   データをインクリメンタルに圧縮する圧縮オブジェクトを作成します。

   単一のデータチャンクをより手軽に圧縮する方法については、モジュール
   レベルの "compress()" 関数を参照してください。

   *level* 引数は、圧縮レベルを制御する整数です。 *level* は、
   *options* に "CompressionParameter.compression_level" を設定する代
   わりに使えます。 *level* に渡せる値を取得するには、
   "compression_level" の "bounds()" を使ってください。 高度な圧縮オプ
   ションが必要な場合は *level* 引数を省略し、*options* 辞書に
   "CompressionParameter.compression_level" パラメータを設定してくださ
   い。

   *options* 引数は、高度な圧縮パラメータを含む Python の辞書です。 圧
   縮パラメータの有効なキーと値は、"CompressionParameter" のドキュメン
   トに記載されています。

   *zstd_dict* 引数は省略可能で、圧縮効率を改善するための学習済みデー
   タを含む "ZstdDict" インスタンスを指定します。 Zstandard 辞書を生成
   するには "train_dict()" 関数を使えます。

   compress(data, mode=ZstdCompressor.CONTINUE)

      *data* (*バイト列状オブジェクト*) を圧縮し、可能であれば圧縮デー
      タを含む "bytes" オブジェクトを返し、それ以外の場合は空の
      "bytes" オブジェクトを返します。 *data* の一部は内部にバッファリ
      ングされ、後続の "compress()" や "flush()" の呼び出しで使われる
      場合があります。 返されたデータは、それ以前の "compress()" の呼
      び出しによる出力と連結してください。

      *mode* 引数は "ZstdCompressor" の属性である "CONTINUE"、
      "FLUSH_BLOCK"、"FLUSH_FRAME" のいずれかです。

      すべてのデータを圧縮オブジェクトに渡したら、"flush()" メソッドを
      呼び出して圧縮処理を完了してください。 *mode* を "FLUSH_FRAME"
      にして "compress()" を呼び出した場合は、"flush()" を呼び出さない
      でください。 呼び出すと、新しい空のフレームが書き出されます。

   flush(mode=ZstdCompressor.FLUSH_FRAME)

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

      *mode* 引数は "ZstdCompressor" の属性である "FLUSH_BLOCK"、
      "FLUSH_FRAME" のいずれかです。

   set_pledged_input_size(size)

      次のフレームに渡す非圧縮データの量 *size* を指定します。
      "CompressionParameter.content_size_flag" が "False" または "0"
      でない限り、*size* は次のフレームのヘッダーに書き込まれます。 サ
      イズが "0" の場合、そのフレームは空であることを意味します。
      *size* が "None" の場合、フレームヘッダーからフレームサイズが省
      略されます。 非圧縮データのサイズを含むフレームは、特に圧縮レベ
      ルが高い場合、展開に必要なメモリが少なくなります。

      "last_mode" が "FLUSH_FRAME" でない場合、圧縮オブジェクトがフレ
      ームの開始位置にないため、"ValueError" を送出します。 宣言したサ
      イズが "compress()" に渡したデータの実際のサイズと一致しない場合
      、その後の "compress()" や "flush()" の呼び出しで "ZstdError" が
      送出され、最後のデータチャンクが失われる可能性があります。

      "mode" を "FLUSH_FRAME" にして "flush()" または "compress()" を
      呼び出した後は、"set_pledged_input_size()" を再度呼び出さない限
      り、次のフレームのヘッダーにフレームサイズは含まれません。

   CONTINUE

      圧縮するデータをさらに集めます。 すぐに出力が生成される場合も、
      されない場合もあります。 このモードはブロックとフレームあたりの
      データ量を最大化することで圧縮率を最適化します。

   FLUSH_BLOCK

      ブロックを完了し、データストリームに書き込みます。 それまでに返
      されたデータはすぐに展開できます。 その後の "compress()" の呼び
      出しで生成するブロックからも過去のデータを参照でき、圧縮率が向上
      します。

   FLUSH_FRAME

      フレームを完了して書き出します。 その後 "compress()" に渡すデー
      タは新しいフレームに書き込まれ、過去のデータを参照することは *で
      きません*。

   last_mode

      "compress()" または "flush()" に最後に渡されたモードです。 値は
      "CONTINUE"、"FLUSH_BLOCK"、"FLUSH_FRAME" のいずれかです。 初期値
      は "FLUSH_FRAME" で、圧縮オブジェクトが新しいフレームの開始位置
      にあることを表します。

class compression.zstd.ZstdDecompressor(zstd_dict=None, options=None)

   データをインクリメンタルに展開するために使用できる展開オブジェクト
   を作成します。

   圧縮ストリーム全体を一度に展開する、より手軽な方法については、モジ
   ュールレベルの "decompress()" 関数を参照してください。

   *options* 引数は、高度な展開パラメータを含む Python の辞書です。 パ
   ラメータの有効なキーと値は、"DecompressionParameter" のドキュメント
   に記載されています。

   *zstd_dict* 引数は、圧縮時に使った学習済みデータを含む "ZstdDict"
   インスタンスです。 圧縮時に使ったものと同じ Zstandard 辞書でなけれ
   ばなりません。

   注釈:

     このクラスは、"decompress()" 関数や "ZstdFile" クラスとは異なり、
     複数の圧縮フレームを含む入力を自動的には処理しません。 複数フレー
     ムの入力を展開するには、"decompress()"、*ファイルオブジェクト* を
     扱う場合は "ZstdFile"、または複数の "ZstdDecompressor" インスタン
     スを使ってください。

   decompress(data, max_length=-1)

      *data* (*バイト列状オブジェクト*) を展開し、展開したデータをバイ
      ト列として返します。 *data* の一部は内部にバッファリングされ、後
      続の "decompress()" の呼び出しで使われる場合があります。 返され
      たデータは、それ以前の "decompress()" の呼び出しによる出力と連結
      してください。

      *max_length* が非負の場合、このメソッドは展開したデータを最大
      *max_length* バイト返します。 この上限に達し、さらに出力を生成で
      きる場合 (または EOF に達した場合)、"needs_input" 属性は "False"
      に設定されます。 この場合、次の "decompress()" の呼び出しでは
      *data* に "b''" を渡して、さらに出力を取得できます。 そのため、
      内容全体は次のように読み取れます。

         process_output(d.decompress(data, max_length))
         while not d.eof and not d.needs_input:
             process_output(d.decompress(b"", max_length))

      入力データの全てが展開され返された (*max_length* バイトより少な
      いためか *max_length* が負のため) 場合、 "needs_input" 属性は
      "True" になります。

      フレームの終端に達した後でデータを展開しようとすると、"EOFError"
      を送出します。 フレームの終端より後にあるデータは無視され、
      "unused_data" 属性に保存されます。

   eof

      ストリーム終端記号に到達した場合 "True" を返します。

   unused_data

      圧縮ストリームの末尾以降に存在したデータを表します。

      ストリームの終端に達するまでは "b''" です。

   needs_input

      "decompress()" メソッドが新たな圧縮入力を必要とせずに、さらに展
      開データを提供できる場合は "False" です。


Zstandard 辞書
==============

compression.zstd.train_dict(samples, dict_size)

   Zstandard 辞書を学習し、"ZstdDict" インスタンスを返します。
   Zstandard 辞書を使うと、繰り返しが少ないため従来は圧縮が難しかった
   小さなデータを、より効率よく圧縮できます。 複数の似たデータ群 (似た
   ファイルなど) を圧縮する場合、Zstandard 辞書によって圧縮率と速度を
   大きく改善できます。

   *samples* 引数 ("bytes" オブジェクトのイテラブル) は、Zstandard 辞
   書の学習に使うサンプルの集まりです。

   整数の *dict_size* 引数は、Zstandard 辞書の最大サイズをバイト単位で
   指定します。 Zstandard のドキュメントでは最大でも 100 KB 以下にする
   ことを勧めていますが、データによってはさらに小さな最大値で十分な場
   合があります。 一般に、辞書が大きいと圧縮は遅くなるものの圧縮率が向
   上します。 辞書が小さいと圧縮は速くなるものの圧縮率が低下します。

compression.zstd.finalize_dict(zstd_dict, /, samples, dict_size, level)

   「生の内容」の Zstandard 辞書を通常の Zstandard 辞書に変換する高度
   な関数です。 「生の内容」の辞書は、通常の Zstandard 辞書の構造に従
   う必要のないバイト列です。

   *zstd_dict* 引数は、"dict_content" に生の辞書の内容を格納した
   "ZstdDict" インスタンスです。

   *samples* 引数 ("bytes" オブジェクトのイテラブル) は、Zstandard 辞
   書を生成するためのサンプルデータを含みます。

   整数の *dict_size* 引数は、Zstandard 辞書の最大サイズをバイト単位で
   指定します。 辞書の最大サイズについての推奨は "train_dict()" を参照
   してください。

   *level* 引数 (整数) は、この辞書を使う圧縮オブジェクトに渡す予定の
   圧縮レベルです。 辞書の情報は圧縮レベルごとに異なるため、適切な圧縮
   レベルに調整すると圧縮効率を改善できます。

class compression.zstd.ZstdDict(dict_content, /, *, is_raw=False)

   Zstandard 辞書のラッパです。 辞書を使うと、多数の小さなデータチャン
   クの圧縮を改善できます。 サンプルデータから新しい辞書を学習する必要
   がある場合は、"train_dict()" を使ってください。

   *dict_content* 引数 (*バイト列状オブジェクト*) は、学習済みの辞書情
   報です。

   真偽値の *is_raw* 引数は、*dict_content* の意味を制御する高度なパラ
   メータです。 "True" の場合、*dict_content* は形式の制約がない「生の
   内容」の辞書です。 "False" の場合、*dict_content* は "train_dict()"
   などの Zstandard の関数や外部の **zstd** CLI で作成された通常の
   Zstandard 辞書です。

   "ZstdDict" を関数に渡す際、"as_digested_dict" または
   "as_undigested_dict" 属性を "zstd_dict" 引数として渡すと、辞書の読
   み込み方法を制御できます。 例えば、"compress(data,
   zstd_dict=zd.as_digested_dict)" とします。 辞書の前処理 (digest) は
   、Zstandard 辞書の読み込み時に行われるコストの高い処理です。 圧縮や
   展開を複数回呼び出す場合、前処理済みの辞書を渡すと、辞書の読み込み
   にかかるオーバーヘッドを減らせます。


      圧縮時の違い
      ^^^^^^^^^^^^

      +------------+----------------+------------+
      |            | 前処理済みの辞 | 前処理して |
      |            | 書             | いない辞書 |
      |============|================|============|
      | 辞書のパラ | "window_log"、 | None       |
      | メータによ | "hash_log"、   |            |
      | って上書き | "chain_log"、  |            |
      | される可能 | "search_log"、 |            |
      | 性がある圧 | "min_match" 、 |            |
      | 縮オブジェ | "target_lengt  |            |
      | クト の高  | h"、"strategy" |            |
      | 度なパラメ | 、"enable_lon  |            |
      | ータ       | g_distance_ma  |            |
      |            | tching"、      |            |
      |            | "ldm_hash_log" |            |
      |            | 、"ldm_min_ma  |            |
      |            | tch"、"ldm_bu  |            |
      |            | cket_size_log" |            |
      |            | 、 "ldm_hash_  |            |
      |            | rate_log"、お  |            |
      |            | よび一部の非公 |            |
      |            | 開パラメータ。 |            |
      +------------+----------------+------------+
      | "ZstdDict" | はい。 同じ圧  | いいえ。   |
      | が辞書を内 | 縮レベルで前処 | 前処理して |
      | 部でキャッ | 理済みの辞書を | いない辞書 |
      | シュするか | 再び読み込む場 | を複数回読 |
      |            | 合に高速 にな  | み込む場合 |
      |            | ります。       | は、圧縮オ |
      |            |                | ブジ ェク  |
      |            |                | トの再利用 |
      |            |                | を検討して |
      |            |                | ください。 |
      +------------+----------------+------------+

   属性を使わずに "ZstdDict" を渡した場合、圧縮時にはデフォルトで前処
   理していない辞書が渡されます。 展開時には、必要に応じて前処理済みの
   辞書が生成され、デフォルトで渡されます。

      dict_content

         Zstandard 辞書の内容を表す "bytes" オブジェクトです。
         "__init__" メソッドの *dict_content* 引数と同じものです。
         "zstd" CLI プログラムなど、他のプログラムで使うこともできます
         。

      dict_id

         Zstandard 辞書の識別子を表す非負の整数値です。

         0 以外の場合、Zstandard の関数で作成され、Zstandard 形式に従
         う通常の辞書であることを意味します。

         "0" は、上級ユーザー向けの、形式の制約がない「生の内容」の辞
         書を意味します。

         注釈:

           "ZstdDict.dict_id" における "0" の意味は、
           "get_frame_info()" 関数が返すオブジェクトの "dictionary_id"
           属性における意味とは異なります。

      as_digested_dict

         前処理済みの辞書として読み込みます。

      as_undigested_dict

         前処理していない辞書として読み込みます。


高度なパラメータの制御
======================

class compression.zstd.CompressionParameter

   データの圧縮時に使える高度な圧縮パラメータのキーを含む "IntEnum" で
   す。

   各属性で "bounds()" メソッドを使うと、そのパラメータの有効な値を取
   得できます。

   パラメータは省略可能です。 省略したパラメータの値は自動的に選択され
   ます。

   "compression_level" の下限と上限を取得する例。

      lower, upper = CompressionParameter.compression_level.bounds()

   "window_log" を最大サイズに設定する例。

      _lower, upper = CompressionParameter.window_log.bounds()
      options = {CompressionParameter.window_log: upper}
      compress(b'venezuelan beaver cheese', options=options)

   bounds()

      圧縮パラメータの整数の範囲を、タプル "(lower, upper)" として返し
      ます。 このメソッドは、範囲を取得したい属性に対して呼び出してく
      ださい。 例えば、"compression_level" の有効な値を取得するには、
      "CompressionParameter.compression_level.bounds()" の結果を調べま
      す。

      下限と上限は、どちらも範囲に含まれます。

   compression_level

      データの圧縮速度や圧縮率に影響する他の圧縮パラメータを設定する、
      高水準の手段です。

      通常の圧縮レベルは "0" より大きい値です。 "20" より大きい値は「
      ultra」圧縮とみなされ、他のレベルより多くのメモリを必要とします
      。 負の値を使うと、圧縮率を下げる代わりに圧縮を高速化できます。

      レベルを 0 に設定すると "COMPRESSION_LEVEL_DEFAULT" が使われます
      。

   window_log

      圧縮時に使用できる後方参照の最大距離を 2 のべき乗で表したもので
      す。 距離は "1 << window_log" バイトになります。 このパラメータ
      は圧縮時のメモリ使用量に大きく影響します。 値が大きいほど多くの
      メモリを必要としますが、圧縮率が向上します。

      値を 0 にすると、自動的に値が選択されます。

   hash_log

      最初の探索テーブルのサイズを 2 のべき乗で表したものです。 メモリ
      使用量は "1 << (hash_log+2)" バイトになります。 テーブルが大きい
      ほど、ストラテジーが "dfast" 以下の場合は圧縮率が向上し、"dfast"
      より大きい場合は圧縮速度が向上します。

      値を 0 にすると、自動的に値が選択されます。

   chain_log

      複数回の探索に使うテーブルのサイズを 2 のべき乗で表したものです
      。 メモリ使用量は "1 << (chain_log+2)" バイトになります。 テーブ
      ルが大きいほど圧縮率が向上しますが、圧縮は遅くなります。 このパ
      ラメータは "fast" ストラテジーでは効果がありません。 "dfast" ス
      トラテジーでは、二つ目の探索テーブルを定義するため有効です。

      値を 0 にすると、自動的に値が選択されます。

   search_log

      探索を試みる回数を 2 のべき乗で表したものです。 回数が多いほど圧
      縮率が向上しますが、圧縮は遅くなります。 このパラメータは "fast"
      と "dfast" ストラテジーでは役に立ちません。

      値を 0 にすると、自動的に値が選択されます。

   min_match

      検索する一致部分の最小サイズです。 値が大きいほど圧縮と展開が速
      くなりますが、圧縮率は低下します。 ただし、Zstandard はこれより
      小さい一致部分も見つけることがあります。 このパラメータは、指定
      したサイズ以上の一致を探すよう検索アルゴリズムを調整するだけです
      。 "btopt" より小さいすべてのストラテジーでは実効的な最小値は
      "4" です。 "fast" より大きいすべてのストラテジーでは実効的な最大
      値は "6" です。

      値を 0 にすると、自動的に値が選択されます。

   target_length

      このフィールドの効果は、選択した "Strategy" によって異なります。

      "btopt"、"btultra"、"btultra2" ストラテジーでは、この値は、探索
      を打ち切るのに「十分によい」とみなす一致部分の長さです。 値が大
      きいほど圧縮率が向上しますが、圧縮は遅くなります。

      "fast" ストラテジーでは、一致を調べるサンプリングの間隔です。 値
      が大きいほど圧縮は速くなりますが、圧縮率は低下します。

      値を 0 にすると、自動的に値が選択されます。

   strategy

      選択したストラテジーの値が大きいほど、zstd は複雑な圧縮手法を使
      うため、圧縮率は向上しますが圧縮は遅くなります。

      参考: "Strategy"

   enable_long_distance_matching

      長距離マッチングを使うと、遠く離れた位置にある長い一致部分を見つ
      け、大きな入力の圧縮を改善できます。 メモリ使用量とウィンドウサ
      イズは増加します。

      "True" または "1" は長距離マッチングを有効にし、"False" または
      "0" は無効にします。

      Enabling this parameter increases default "window_log" to 128
      MiB except when expressly set to a different value. This setting
      is enabled by default if "window_log" >= 128 MiB and the
      compression strategy >= "btopt" (compression level 16+).

   ldm_hash_log

      長距離マッチング用のテーブルのサイズを 2 のべき乗で表したもので
      す。 値が大きいほどメモリ使用量と圧縮率が増加しますが、圧縮速度
      は低下します。

      値を 0 にすると、自動的に値が選択されます。

   ldm_min_match

      長距離マッチングでの一致部分の最小サイズです。 値が大きい場合や
      小さすぎる場合は、圧縮率が低下することがよくあります。

      値を 0 にすると、自動的に値が選択されます。

   ldm_bucket_size_log

      長距離マッチング用のハッシュテーブルで衝突を解決するための、各バ
      ケットのサイズの対数です。 値が大きいほど衝突の解決が改善します
      が、圧縮速度は低下します。

      値を 0 にすると、自動的に値が選択されます。

   ldm_hash_rate_log

      長距離マッチング用のハッシュテーブルに対して、エントリーを挿入・
      検索する頻度です。 値が大きいほど圧縮速度が向上します。 デフォル
      ト値から大きく外れると、圧縮率が低下する可能性が高くなります。

      値を 0 にすると、自動的に値が選択されます。

   content_size_flag

      圧縮するデータのサイズが圧縮前に分かっている場合、そのサイズを
      Zstandard フレームのヘッダーに書き込みます。

      このフラグは、次の場合にのみ効果があります:

      * 一度に圧縮するために "compress()" を呼び出す場合

      * "ZstdCompressor.FLUSH_FRAME" モードで
        "ZstdCompressor.compress()" を一度だけ呼び出し、そのフレームに
        圧縮するすべてのデータを渡す場合。

      * 現在のフレームに対して "ZstdCompressor.compress()" を呼び出す
        前に、圧縮オブジェクトに渡す正確なデータ量で
        "ZstdCompressor.set_pledged_input_size()" を呼び出す場合。 新
        しいフレームごとに "ZstdCompressor.set_pledged_input_size()"
        を呼び出さなければなりません。

      それ以外の圧縮の呼び出しでは、サイズ情報がフレームヘッダーに書き
      込まれない場合があります。

      "True" または "1" は内容サイズのフラグを有効にし、"False" または
      "0" は無効にします。

   checksum_flag

      非圧縮の内容から XXHash64 で計算した 4 バイトのチェックサムを、
      各フレームの末尾に書き込みます。 Zstandard の展開コードはこのチ
      ェックサムを検証します。 一致しない場合は "ZstdError" 例外を送出
      します。

      "True" または "1" はチェックサムの生成を有効にし、"False" または
      "0" は無効にします。

   dict_id_flag

      "ZstdDict" を使って圧縮する際、辞書の ID をフレームヘッダーに書
      き込みます。

      "True" または "1" は辞書 ID の保存を有効にし、"False" または "0"
      は無効にします。

   nb_workers

      並列に圧縮するために起動するスレッド数を選択します。
      "nb_workers" が 0 より大きい場合、マルチスレッド圧縮が有効になり
      ます。 値 "1" は「1 スレッドのマルチスレッドモード」を意味します
      。 ワーカーが多いほど速度が向上しますが、メモリ使用量も増加し、
      圧縮率はわずかに低下します。

      値を 0 にすると、マルチスレッド処理が無効になります。

   job_size

      圧縮ジョブのサイズ (バイト単位) です。 この値は、"nb_workers" が
      1 以上の場合にのみ適用されます。 各圧縮ジョブは並列に実行される
      ため、この値はアクティブなスレッド数に間接的に影響する場合があり
      ます。

      値を 0 にすると、自動的に値が選択されます。

   overlap_log

      新しいジョブで圧縮時の後方参照ウィンドウに使うために、前のジョブ
      (スレッド) から再読み込みするデータ量を設定します。 この値は、
      "nb_workers" が 1 以上の場合にのみ使われます。 指定できる値は 0
      から 9 です。

         * 0 は重複量を動的に設定することを意味します

         * 1 は重複なしを意味します

         * 9 は前のジョブのウィンドウサイズ全体を使うことを意味します

      値を一つ減らすと重複サイズは半分になり、一つ増やすと倍になります
      。 「8」は "window_size/2"、「7」は "window_size/4" の重複を意味
      します。

class compression.zstd.DecompressionParameter

   データの展開時に使える高度な展開パラメータのキーを含む "IntEnum" で
   す。 パラメータは省略可能で、省略したパラメータの値は自動的に選択さ
   れます。

   各属性で "bounds()" メソッドを使うと、そのパラメータの有効な値を取
   得できます。

   "window_log_max" を最大サイズに設定する例。

      data = compress(b'Some very long buffer of bytes...')

      _lower, upper = DecompressionParameter.window_log_max.bounds()

      options = {DecompressionParameter.window_log_max: upper}
      decompress(data, options=options)

   bounds()

      展開パラメータの整数の範囲を、タプル "(lower, upper)" として返し
      ます。 このメソッドは、範囲を取得したい属性に対して呼び出してく
      ださい。

      下限と上限は、どちらも範囲に含まれます。

   window_log_max

      展開時に使うウィンドウの最大サイズの、2 を底とする対数です。 展
      開時のメモリ使用量を制限するのに役立ちます。 ウィンドウの最大サ
      イズが大きいほど、展開は速くなります。

      値を 0 にすると、自動的に値が選択されます。

class compression.zstd.Strategy

   圧縮ストラテジーを含む "IntEnum" です。 数値が大きいストラテジーほ
   ど、複雑で遅い圧縮に対応します。

   注釈:

     "Strategy" の属性の値は、zstd のバージョン間で必ずしも一定ではあ
     りません。 依存できるのは属性の順序だけです。 以下に属性を順番に
     示します。

   次のストラテジーを利用できます:

   fast

   dfast

   greedy

   lazy

   lazy2

   btlazy2

   btopt

   btultra

   btultra2


その他
======

compression.zstd.get_frame_info(frame_buffer)

   Zstandard フレームのメタデータを含む "FrameInfo" オブジェクトを取得
   します。 フレームには、格納する圧縮データに関するメタデータが含まれ
   ています。

class compression.zstd.FrameInfo

   Zstandard フレームに関するメタデータです。

   decompressed_size

      フレームの内容を展開したサイズです。

   dictionary_id

      フレームの展開に必要な Zstandard 辞書の ID を表す整数です。 "0"
      は、辞書 ID がフレームヘッダーに記録されていないことを意味します
      。 Zstandard 辞書が不要な場合もあれば、必要な辞書の ID が記録さ
      れていない場合もあります。

compression.zstd.COMPRESSION_LEVEL_DEFAULT

   Zstandard のデフォルトの圧縮レベル: "3"。

compression.zstd.zstd_version_info

   実行時に使う zstd ライブラリのバージョン番号を表す整数のタプル
   (major, minor, release) です。


使用例
======

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

   from compression import zstd

   with zstd.open("file.zst") as f:
       file_content = f.read()

圧縮ファイルの作成:

   from compression import zstd

   data = b"Insert Data Here"
   with zstd.open("file.zst", "w") as f:
       f.write(data)

メモリ上でのデータの圧縮:

   from compression import zstd

   data_in = b"Insert Data Here"
   data_out = zstd.compress(data_in)

インクリメンタルな圧縮:

   from compression import zstd

   comp = zstd.ZstdCompressor()
   out1 = comp.compress(b"Some data\n")
   out2 = comp.compress(b"Another piece of data\n")
   out3 = comp.compress(b"Even more data\n")
   out4 = comp.flush()
   # 部分的な結果をすべて連結する:
   result = b"".join([out1, out2, out3, out4])

すでに開かれたファイルへの圧縮データの書き込み:

   from compression import zstd

   with open("myfile", "wb") as f:
       f.write(b"This data will not be compressed\n")
       with zstd.open(f, "w") as zstf:
           zstf.write(b"This *will* be compressed\n")
       f.write(b"Not compressed\n")

圧縮パラメータを使った圧縮ファイルの作成:

   from compression import zstd

   options = {
      zstd.CompressionParameter.checksum_flag: 1
   }
   with zstd.open("file.zst", "w", options=options) as f:
       f.write(b"Mind if I squeeze in?")
