13.1. zlibgzip 互換の圧縮

このモジュールは、データ圧縮を必要とするアプリケーションが zlib ライブラリを使って圧縮および展開を行えるようにします。zlib ライブラリ自身の Webページは http://www.zlib.net です。Python モジュールと zlib ライブラリの 1.1.3 より前のバージョンには互換性のない部分があることが知られています。1.1.3 にはセキュリティホールが存在するため、1.1.4 以降のバージョンを利用することを推奨します。

zlib の関数にはたくさんのオプションがあり、場合によっては特定の順番で使わなければなりません。このドキュメントではそれら順番についてすべてを説明しようとはしていません。詳細は公式サイト http://www.zlib.net/manual.html にある zlib のマニュアルを参照してください。

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

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

exception zlib.error

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

zlib.adler32(data[, value])

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

常に符号なし 32bit ビット整数を返します。

注釈

すべての Python のバージョンとプラットフォームで共通な数値を生成するには、adler32(data) & 0xffffffff を利用してください。もしチェックサムをパックされたバイナリフォーマットのためにしか利用しないのであれば、符号が関係なくなり、32bit のバイナリ値としては戻り値は正しいので、この処理は必要ありません。

zlib.compress(data[, level])

data で与えられたバイト列を圧縮し、圧縮されたデータを含むバイト列オブジェクトを返します。level0 から 9 の整数を取り、圧縮レベルを制御します; 1 は最も高速で最小限の圧縮を行い、9 は最も低速ですが最大限の圧縮を行います。0 は圧縮しません。デフォルト値は 6 です。何らかのエラーが発生した場合は error 例外を送出します。

zlib.compressobj(level=-1, method=DEFLATED, wbits=15, memlevel=8, strategy=Z_DEFAULT_STRATEGY[, zdict])

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

level は圧縮レベルです。0 から 9 の整数を取り、1 は最も高速で最小限の圧縮を行い、9 は最も低速で最大限の圧縮を行います。0 は圧縮しません。デフォルトは 6 です。

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

wbits は、ウィンドウバッファサイズに対する 2 を底とする対数です。この値は 8 から 15 の整数でなければなりません。大きな値ほど圧縮率が向上しますが、メモリ消費量も増加します。

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

strategy は圧縮アルゴリズムの調整に使用されます。指定可能な値は、Z_DEFAULT_STRATEGYZ_FILTERED、および Z_HUFFMAN_ONLY です。

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

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

zlib.crc32(data[, value])

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

常に符号なし 32bit ビット整数を返します。

注釈

すべての Python のバージョンとプラットフォームで共通な数値を生成するには、crc32(data) & 0xffffffff を利用してください。もしチェックサムをパックされたバイナリフォーマットのためにしか利用しないのであれば、符号が関係なくなり、32bit のバイナリ値としては戻り値は正しいので、この処理は必要ありません。

zlib.decompress(data[, wbits[, bufsize]])

data で与えられたバイト列を展開し、展開されたデータを含むバイト列オブジェクトを返します。wbits パラメータはウィンドウバッファの大きさを制御します。詳細は以下を参照してください。bufsize が与えられていれば、出力バッファの初期サイズとして使われます。展開処理に何らかのエラーが生じた場合、error 例外を送出します。

wbits の絶対値は、データを圧縮する際に用いられるヒストリバッファのサイズ (ウィンドウサイズ) に対し、2 を底とする対数をとったものです。最新バージョンの zlib ライブラリを使っている場合、wbits の絶対値は 8 から 15 にしてください。大きな値ほど圧縮率が向上しますが、メモリ消費量も増加します。ストリームを展開する場合、wbits は元のストリームを圧縮するために使用したサイズより小さくしてはいけません。小さすぎる値を使用すると例外を送出します。そのため、デフォルトの値は 15 となっています。wbits の値が負の場合、標準的な gzip ヘッダを出力しません。

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

zlib.decompressobj(wbits=15[, zdict])

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

wbits パラメータはウィンドウバッファのサイズを制御します。

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

注釈

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

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

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

Compress.compress(data)

data を圧縮し、圧縮されたデータを含むバイト列オブジェクトを返します。この文字列は少なくとも data の一部分のデータに対する圧縮データを含みます。このデータは以前に呼んだ compress() が返した出力と結合することができます。入力の一部は以後の処理のために内部バッファに保存されることもあります。

Compress.flush([mode])

未処理の全入力データが処理され、この未処理部分を圧縮したデータを含むバイト列オブジェクトが返されます。mode は定数 Z_SYNC_FLUSHZ_FULL_FLUSH、または Z_FINISH のいずれかをとり、デフォルト値は Z_FINISH です。Z_SYNC_FLUSH および Z_FULL_FLUSH はこれ以後にもデータバイト文字列を圧縮できるモードです。一方、Z_FINISH は圧縮ストリームを閉じ、これ以後のデータの圧縮を停止します。modeZ_FINISH を指定して flush() メソッドを呼び出した後は、compress() メソッドを再び呼ぶべきではありません。唯一の現実的な操作はこのオブジェクトを削除することだけです。

Compress.copy()

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

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

Decompress.unused_data

A bytes object which contains any bytes past the end of the compressed data. That is, this remains b"" until the last byte that contains compression data is available. If the whole bytestring turned out to contain compressed data, this is b"", an empty bytes object.

Decompress.unconsumed_tail

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

Decompress.eof

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

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

バージョン 3.3 で追加.

Decompress.decompress(data[, max_length])

data を展開し、少なくとも string の一部分に対応する展開されたデータを含むバイト列オブジェクトを返します。このデータは以前に decompress() メソッドを呼んだ時に返された出力と結合することができます。入力データの一部分が以後の処理のために内部バッファに保存されることもあります。

オプションパラメータ max_length が与えられると、返される展開データの長さが max_length 以下に制限されます。これは入力した圧縮データのすべてが処理されるとは限らないことを意味し、処理されなかったデータは unconsumed_tail 属性に保存されます。展開処理を継続したいならば、この保存されたバイト文字列を以降の decompress() 呼び出しに渡さなくてはなりません。max_length が与えられなかった場合、すべての入力が展開され、unconsumed_tail 属性は空になります。

Decompress.flush([length])

未処理の入力データをすべて処理し、最終的に圧縮されなかった残りの出力バイト列オブジェクトを返します。flush() を呼んだ後、decompress() を再度呼ぶべきではありません。このときできる唯一の現実的な操作はオブジェクトの削除だけです。

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

Decompress.copy()

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

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

zlib.ZLIB_VERSION

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

zlib.ZLIB_RUNTIME_VERSION

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

バージョン 3.3 で追加.

参考

gzip モジュール

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

http://www.zlib.net

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

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

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