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

Added in version 3.14.

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

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

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

これは オプションのモジュール です。 お使いの 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、hash_log、chain_log、search_log、min_match、target_length、strategy、enable_long_distance_matching、ldm_hash_log、ldm_min_match、ldm_bucket_size_log、ldm_hash_rate_log、および一部の非公開パラメータ。

None

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 フレームのヘッダーに書き込みます。

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

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

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。

Information about the version of the zstd library in use is available through the following constants:

compression.zstd.ZSTD_VERSION

The version string of the zstd library that was used for building the module. This may be different from the zstd library actually used at runtime, which is available as zstd_version.

Added in version 3.16.

compression.zstd.zstd_version

The version string of the zstd library actually loaded by the interpreter.

compression.zstd.ZSTD_VERSION_INFO

A named tuple containing the three components of the zstd library version that was used for building the module: major, minor, and patch. All values are integers. The components can also be accessed by name, so zstd.ZSTD_VERSION_INFO[0] is equivalent to zstd.ZSTD_VERSION_INFO.major and so on. This may be different from the zstd library actually used at runtime, which is available as zstd_version_info.

Added in version 3.16.

compression.zstd.zstd_version_info

A named tuple containing the version of the zstd library actually loaded by the interpreter, with the same fields as ZSTD_VERSION_INFO.

バージョン 3.16 で変更: It is now a named tuple.

使用例

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

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