zlib --- gzip 互換の圧縮

データ圧縮が必要なアプリケーションでは、このモジュールの関数を使い、zlib library による圧縮と展開を行えます。

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

zlib の関数には多くのオプションがあり、決まった順序で使わなければならないことがよくあります。 このドキュメントはすべての組み合わせを網羅するものではありません。 正式な情報は zlib manual を参照してください。

.gz ファイルの読み書きのためには、 gzip モジュールを参照してください。

このモジュールで利用可能な例外と関数を以下に示します:

exception zlib.error

圧縮および展開時のエラーによって送出される例外です。

zlib.adler32(data, value=1, /)

data の Adler-32 チェックサムを計算します (Adler-32 チェックサムは、おおむね CRC32 と同等の信頼性を持ちながら、はるかに高速に計算できます)。結果は、符号のない 32 ビットの整数です。 value が与えられている場合、チェックサム計算の初期値として使われます。与えられていない場合、デフォルト値の 1 が使われます。 value を与えることで、複数の入力を結合したデータ全体にわたり、通しのチェックサムを計算できます。このアルゴリズムは暗号論的には強力ではなく、認証やデジタル署名などに用いるべきではありません。また、チェックサムアルゴリズムとして設計されているため、汎用のハッシュアルゴリズムには向きません。

バージョン 3.0 で変更: 結果は常に符号なしになりました。

zlib.adler32_combine(adler1, adler2, len2, /)

2 つの Adler-32 チェックサムを 1 つに結合します。

シーケンス A の Adler-32 チェックサム adler1 と、長さ len2 のシーケンス B の Adler-32 チェックサム adler2 を受け取り、A と B を連結したデータの Adler-32 チェックサムを返します。

この関数は、並行して計算した Adler-32 チェックサムを結合する場合などに役立ちます。 チェックサムを順次計算する場合は、adler32() の value 引数にそれまでのチェックサムを渡してください。

Added in version 3.15.

zlib.compress(data, /, level=Z_DEFAULT_COMPRESSION, wbits=MAX_WBITS)

data のバイト列を圧縮し、圧縮データを含む bytes オブジェクトを返します。 level は圧縮レベルを制御する 0 から 9 までの整数、または -1 です。 これらの値の詳細は、Z_BEST_SPEED (1)、Z_BEST_COMPRESSION (9)、Z_NO_COMPRESSION (0)、デフォルトの Z_DEFAULT_COMPRESSION (-1) を参照してください。

wbits 引数は、データの圧縮に使う履歴バッファのサイズ (ウィンドウサイズ) と、出力にヘッダーとトレーラーを含めるかどうかを制御します。 次に示す複数の範囲の値を指定でき、デフォルトは 15 (MAX_WBITS) です。

  • +9 から +15: ウィンドウサイズの 2 を底とする対数です。 ウィンドウサイズは 512 から 32768 の範囲になります。 大きい値ほど圧縮率が高くなりますが、より多くのメモリを消費します。 出力には zlib 固有のヘッダーとトレーラーが含まれます。

  • −9 から −15: wbits の絶対値をウィンドウサイズの対数として使い、ヘッダーや末尾のチェックサムを含まない生のストリームを出力します。

  • +25 から +31 = 16 + (9 から 15): 値の下位 4 ビットをウィンドウサイズの対数として使い、基本的な gzip ヘッダーと末尾のチェックサムを出力に含めます。

エラーが発生すると error 例外を送出します。

バージョン 3.6 で変更: level をキーワード引数として使えるようになりました。

バージョン 3.11 で変更: wbits 引数でウィンドウのビット数と圧縮形式を設定できるようになりました。

zlib.compressobj(level=Z_DEFAULT_COMPRESSION, method=DEFLATED, wbits=MAX_WBITS, memLevel=DEF_MEM_LEVEL, strategy=Z_DEFAULT_STRATEGY[, zdict])

一度にメモリ上に置くことができないようなデータストリームを圧縮するための圧縮オブジェクトを返します。

level は圧縮レベルで、0 から 9 までの整数、または -1 です。 これらの値の詳細は、Z_BEST_SPEED (1)、Z_BEST_COMPRESSION (9)、Z_NO_COMPRESSION (0)、デフォルトの Z_DEFAULT_COMPRESSION (-1) を参照してください。

method は圧縮アルゴリズムです。現在、 DEFLATED のみサポートされています。

wbits 引数は、履歴バッファのサイズ (ウィンドウサイズ) と、使用するヘッダーとトレーラーの形式を制御します。 compress() の説明 と同じ意味です。

memLevel 引数は内部圧縮状態用に使用されるメモリ量を制御します。有効な値は 1 から 9 です。大きい値ほど多くのメモリを消費しますが、より速く、より小さな出力を作成します。

strategy は圧縮アルゴリズムの調整に使います。 指定できる値は Z_DEFAULT_STRATEGY、Z_FILTERED、Z_HUFFMAN_ONLY、Z_RLE、Z_FIXED です。

zdict は定義済み圧縮辞書です。これは圧縮されるデータ内で繰り返し現れると予想されるサブシーケンスを含む (bytes オブジェクトのような) バイト列のシーケンスです。最も一般的と思われるサブシーケンスは辞書の末尾に来なければなりません。

バージョン 3.3 で変更: zdict パラメータとキーワード引数のサポートが追加されました。

zlib.crc32(data, value=0, /)

data の CRC (Cyclic Redundancy Check, 巡回冗長検査) チェックサムを計算します。結果は、符号のない 32 ビットの整数です。 value が与えられている場合、チェックサム計算の初期値として使われます。与えられていない場合、デフォルト値の 0 が使われます。 value を与えることで、複数の入力を結合したデータ全体にわたり、通しのチェックサムを計算できます。このアルゴリズムは暗号論的には強力ではなく、認証やデジタル署名などに用いるべきではありません。また、チェックサムアルゴリズムとして設計されているため、汎用のハッシュアルゴリズムには向きません。

バージョン 3.0 で変更: 結果は常に符号なしになりました。

zlib.crc32_combine(crc1, crc2, len2, /)

2 つの CRC-32 チェックサムを 1 つに結合します。

シーケンス A の CRC-32 チェックサム crc1 と、長さ len2 のシーケンス B の CRC-32 チェックサム crc2 を受け取り、A と B を連結したデータの CRC-32 チェックサムを返します。

この関数は、並行して計算した CRC-32 チェックサムを結合する場合などに役立ちます。 チェックサムを順次計算する場合は、crc32() の value 引数にそれまでのチェックサムを渡してください。

Added in version 3.15.

zlib.decompress(data, /, wbits=MAX_WBITS, bufsize=DEF_BUF_SIZE)

data のバイト列を展開し、展開済みのデータを含む bytes オブジェクトを返します。 wbits 引数の値は data の形式に依存します。 詳細は後述します。 bufsize を指定すると、出力バッファの初期サイズとして使われます。 エラーが発生すると error 例外を送出します。

wbits 引数は、履歴バッファのサイズ (ウィンドウサイズ) と、入力に想定するヘッダーとトレーラーの形式を制御します。 compressobj() の引数と似ていますが、より多くの範囲の値を受け付けます。

  • +8 から +15: ウィンドウサイズの 2 を底とする対数です。 入力には zlib のヘッダーとトレーラーが含まれていなければなりません。

  • 0: zlib ヘッダーからウィンドウサイズを自動的に判定します。 zlib 1.2.3.5 以降でのみサポートされています。

  • −8 から −15: wbits の絶対値をウィンドウサイズの対数として使います。 入力はヘッダーやトレーラーを含まない生のストリームでなければなりません。

  • +24 から +31 = 16 + (8 から 15): 値の下位 4 ビットをウィンドウサイズの対数として使います。 入力には gzip のヘッダーとトレーラーが含まれていなければなりません。

  • +40 から +47 = 32 + (8 から 15): 値の下位 4 ビットをウィンドウサイズの対数として使い、zlib 形式と gzip 形式の両方を自動的に受け付けます。

ストリームを展開する際、ウィンドウサイズは圧縮時に使われたサイズ以上でなければなりません。 小さすぎる値を使うと error 例外が発生する場合があります。 wbits のデフォルト値は最大のウィンドウサイズに対応し、入力には zlib のヘッダーとトレーラーが必要です。

bufsize は展開されたデータを保持するためのバッファサイズの初期値です。バッファの空きは必要に応じて必要なだけ増加するので、必ずしも正確な値を指定する必要はありません。この値のチューニングでできることは、malloc() が呼ばれる回数を数回減らすことぐらいです。

バージョン 3.6 で変更: wbits と bufsize をキーワード引数として使えるようになりました。

zlib.decompressobj(wbits=MAX_WBITS, zdict=b'')

一度にメモリ上に置くことができないようなデータストリームを展開するための展開オブジェクトを返します。

wbits 引数は、履歴バッファのサイズ (ウィンドウサイズ) と、入力に想定するヘッダーとトレーラーの形式を制御します。 decompress() の説明 と同じ意味です。

zdict パラメータには定義済み圧縮辞書を指定します。このパラメータを指定する場合、展開するデータを圧縮した際に使用した辞書と同じものでなければなりません。

注釈

zdict が (bytearray のような) 変更可能オブジェクトの場合、decompressobj() の呼び出しとデコンプレッサの decompress() メソッドの最初の呼び出しの間に辞書の内容を変更してはいけません。

バージョン 3.3 で変更: パラメータに zdict を追加しました。

圧縮オブジェクトは以下のメソッドをサポートしています:

Compress.compress(data, /)

data を圧縮し、その少なくとも一部に対応する圧縮データを含むバイト列オブジェクトを返します。 返されたデータは、以前の compress() メソッドの呼び出しで得た出力に連結する必要があります。 入力の一部は、後で処理するために内部バッファに保持されることがあります。

Compress.flush(mode=Z_FINISH, /)

All pending input is processed, and a bytes object containing the remaining compressed output is returned. mode can be selected from the constants Z_NO_FLUSH, Z_PARTIAL_FLUSH, Z_SYNC_FLUSH, Z_FULL_FLUSH, Z_BLOCK, or Z_FINISH, defaulting to Z_FINISH. Except Z_FINISH, all constants allow compressing further bytestrings of data, while Z_FINISH finishes the compressed stream and prevents compressing any more data. After calling flush() with mode set to Z_FINISH, the compress() method cannot be called again; the only realistic action is to delete the object.

Compress.copy()

圧縮オブジェクトのコピーを返します。これを使うと先頭部分が共通している複数のデータを効率的に圧縮することができます。

バージョン 3.8 で変更: 圧縮オブジェクトで copy.copy() と copy.deepcopy() をサポートしました。

展開オブジェクトは以下のメソッドと属性をサポートしています:

Decompress.unused_data

圧縮データの末尾より後のバイト列が入ったバイト列オブジェクトです。すなわち、この値は圧縮データの入っているバイト列の最後の文字が利用可能になるまでは b"" のままとなります。入力バイト文字列すべてが圧縮データを含んでいた場合、この属性は b"" 、すなわち空バイト列になります。

Decompress.unconsumed_tail

展開されたデータを収めるバッファの長さ制限を超えたために、直近の decompress() 呼び出しで処理しきれなかったデータを含むバイト列オブジェクトです。このデータはまだ zlib 側からは見えていないので、正しい展開出力を得るには以降の decompress() メソッド呼び出しに (場合によっては後続のデータが追加された) データを差し戻さなければなりません。

Decompress.eof

圧縮データストリームの終了に達したかどうかを示すブール値です。

これは、正常な形式の圧縮ストリームと、不完全あるいは切り詰められたストリームとを区別することを可能にします。

Added in version 3.3.

Decompress.decompress(data, /, max_length=0)

data を展開し、少なくとも string の一部に対応する展開済みデータを含む bytes オブジェクトを返します。 このデータは、以前の decompress() 呼び出しで得た出力に連結する必要があります。 入力データの一部は、後で処理するために内部バッファに保持される場合があります。

省略可能な max_length 引数が 0 でない場合、返されるデータの長さは max_length 以下になります。 このため、圧縮された入力をすべて処理できない場合があり、未処理のデータは unconsumed_tail 属性に格納されます。 展開を続けるには、このバイト列を後続の decompress() 呼び出しに渡す必要があります。 max_length が 0 の場合は入力全体が展開され、unconsumed_tail は空になります。 例えば、次のように内容をすべて読み込めます。

process_output(d.decompress(data, max_length))
while chunk := d.decompress(d.unconsumed_tail, max_length):
    process_output(chunk)

バージョン 3.6 で変更: max_length をキーワード引数として使えるようになりました。

Decompress.flush(length=DEF_BUF_SIZE, /)

未処理の入力をすべて処理し、残りの展開済みデータを含むバイト列オブジェクトを返します。 flush() を呼び出した後は decompress() を再度呼び出すことはできません。 その後にできる現実的な操作は、オブジェクトを削除することだけです。

オプション引数 length には出力バッファの初期サイズを指定します。

Decompress.copy()

展開オブジェクトのコピーを返します。これを使うとデータストリームの途中にある展開オブジェクトの状態を保存でき、未来のある時点で行なわれるストリームのランダムなシークをスピードアップするのに利用できます。

バージョン 3.8 で変更: 展開オブジェクトで copy.copy() と copy.deepcopy() をサポートしました。

圧縮と展開の動作を設定するために、次の定数を利用できます。

zlib.DEFLATED

deflate 圧縮方式。

zlib.MAX_WBITS

最大ウィンドウサイズを 2 のべき乗の指数で表した値です。 例えば MAX_WBITS が 15 の場合、ウィンドウサイズは 32 KiB になります。

zlib.DEF_MEM_LEVEL

圧縮オブジェクトのデフォルトのメモリレベル。

zlib.DEF_BUF_SIZE

展開処理のデフォルトのバッファサイズ。

zlib.Z_NO_COMPRESSION

圧縮レベル 0。 圧縮しません。

Added in version 3.6.

zlib.Z_BEST_SPEED

圧縮レベル 1。 最も高速ですが、圧縮率は最も低くなります。

zlib.Z_BEST_COMPRESSION

圧縮レベル 9。 最も低速ですが、圧縮率は最も高くなります。

zlib.Z_DEFAULT_COMPRESSION

デフォルトの圧縮レベル (-1)。 速度と圧縮率のバランスを取ります。 現在は圧縮レベル 6 と同じです。

zlib.Z_DEFAULT_STRATEGY

通常のデータ向けのデフォルトの圧縮戦略。

zlib.Z_FILTERED

フィルター (または予測器) が生成したデータ向けの圧縮戦略。

zlib.Z_HUFFMAN_ONLY

ハフマン符号化のみを使う圧縮戦略。

zlib.Z_RLE

一致するデータとの距離を 1 に制限する圧縮戦略 (ランレングス符号化)。

この定数は、Python が zlib 1.2.0.1 以降でコンパイルされている場合にのみ利用できます。

Added in version 3.6.

zlib.Z_FIXED

動的ハフマン符号の使用を禁止する圧縮戦略。

この定数は、Python が zlib 1.2.2.2 以降でコンパイルされている場合にのみ利用できます。

Added in version 3.6.

zlib.Z_NO_FLUSH

フラッシュモード 0。 特別なフラッシュ処理は行いません。

Added in version 3.6.

zlib.Z_PARTIAL_FLUSH

フラッシュモード 1。 できる限り多くの出力をフラッシュします。

zlib.Z_SYNC_FLUSH

フラッシュモード 2。 すべての出力をフラッシュし、出力をバイト境界に揃えます。

zlib.Z_FULL_FLUSH

フラッシュモード 3。 すべての出力をフラッシュし、圧縮状態をリセットします。

zlib.Z_FINISH

フラッシュモード 4。 保留中の入力をすべて処理し、それ以上の入力は受け付けません。

zlib.Z_BLOCK

フラッシュモード 5。 deflate ブロックを完結させて出力します。

この定数は、Python が zlib 1.2.2.2 以降でコンパイルされている場合にのみ利用できます。

Added in version 3.6.

zlib.Z_TREES

inflate 処理用のフラッシュモード 6。 次の deflate ブロック境界に達したら戻るように inflate に指示します。

この定数は、Python が zlib 1.2.3.4 以降でコンパイルされている場合にのみ利用できます。

Added in version 3.6.

使用している zlib ライブラリのバージョン情報を以下の定数で確認できます:

zlib.ZLIB_VERSION

モジュールのビルド時に使用された zlib ライブラリのバージョン文字列です。これは ZLIB_RUNTIME_VERSION で確認できる、実行時に使用している実際の zlib ライブラリのバージョンとは異なる場合があります。

zlib.ZLIB_RUNTIME_VERSION

インタプリタが読み込んだ実際の zlib ライブラリのバージョン文字列です。

Added in version 3.3.

zlib.ZLIBNG_VERSION

zlib-ng を使ってこのモジュールをビルドした場合、その zlib-ng ライブラリのバージョン文字列です。 この定数がある場合、ZLIB_VERSION 定数と ZLIB_RUNTIME_VERSION 定数は zlib-ng が提供する zlib API のバージョンを表します。

zlib-ng を使わずにこのモジュールをビルドした場合、この定数は存在しません。

Added in version 3.14.

参考

gzip モジュール

gzip 形式ファイルへの読み書きを行うモジュール。

https://www.zlib.net

zlib ライブラリホームページ。

https://www.zlib.net/manual.html

zlib ライブラリの多くの関数の意味と使い方を解説したマニュアル。

gzip の圧縮や展開がボトルネックとなる場合、python-isal パッケージを使うと、ほぼ互換性のある API で圧縮や展開を高速化できます。