12.1. zlib — gzip 互換の圧縮

このモジュールは、データ圧縮を必要とするアプリケーションが 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 を与えることで、複数の入力を結合したデータ全体にわたり、通しのチェックサムを計算できます。このアルゴリズムは暗号論的には強力ではなく、認証やデジタル署名などに用いるべきではありません。また、チェックサムアルゴリズムとして設計されているため、汎用のハッシュアルゴリズムには向きません。

この関数は常に整数オブジェクトを返します。

注釈

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

バージョン 2.6 で変更: 戻り値の範囲は、プラットフォームに関係なく [-2**31, 2**31-1] になりました。古いバージョンでは、この値は幾つかのプラットフォームでは符号付き、別のプラットフォームでは符号なしになっていました。

バージョン 3.0 で変更: 戻り値の範囲は、プラットフォームに関係なく [0, 2**32-1] の範囲の符号無しです。

zlib.compress(string[, level])

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

zlib.compressobj([level[, method[, wbits[, memlevel[, strategy]]]]])

Returns a compression object, to be used for compressing data streams that won’t fit into memory at once. level is an integer from 0 to 9 or -1, controlling the level of compression; 1 is fastest and produces the least compression, 9 is slowest and produces the most. 0 is no compression. The default value is -1 (Z_DEFAULT_COMPRESSION). Z_DEFAULT_COMPRESSION represents a default compromise between speed and compression (currently equivalent to level 6).

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

The wbits argument controls the size of the history buffer (or the "window size") used when compressing data, and whether a header and trailer is included in the output. It can take several ranges of values. The default is 15.

• +9 to +15: The base-two logarithm of the window size, which therefore ranges between 512 and 32768. Larger values produce better compression at the expense of greater memory usage. The resulting output will include a zlib-specific header and trailer.
• −9 to −15: Uses the absolute value of wbits as the window size logarithm, while producing a raw output stream with no header or trailing checksum.
• +25 to +31 = 16 + (9 to 15): Uses the low 4 bits of the value as the window size logarithm, while including a basic gzip header and trailing checksum in the output.

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

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

zlib.crc32(data[, value])

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

この関数は常に整数オブジェクトを返します。

注釈

全ての Python のバージョン、全てのプラットフォームに渡って同じ数値を生成しようとするならば、 crc32(data) & 0xffffffff を使って下さい。チェックサムをバイナリ形式そのままでだけ扱うならばこのような細工は必要ありません。返値は符号に関係なく正しい32ビットのバイナリ表現だからです。

バージョン 2.6 で変更: 戻り値の範囲は、プラットフォームに関係なく [-2**31, 2**31-1] になりました。古いバージョンでは、この値は幾つかのプラットフォームでは符号付き、別のプラットフォームでは符号なしになっていました。

バージョン 3.0 で変更: 戻り値の範囲は、プラットフォームに関係なく [0, 2**32-1] の範囲の符号無しです。

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

Decompresses the data in string, returning a string containing the uncompressed data. The wbits parameter depends on the format of string, and is discussed further below. If bufsize is given, it is used as the initial size of the output buffer. Raises the error exception if any error occurs.

The wbits parameter controls the size of the history buffer (or "window size"), and what header and trailer format is expected. It is similar to the parameter for compressobj(), but accepts more ranges of values:

• +8 to +15: The base-two logarithm of the window size. The input must include a zlib header and trailer.
• 0: Automatically determine the window size from the zlib header. Only supported since zlib 1.2.3.5.
• −8 to −15: Uses the absolute value of wbits as the window size logarithm. The input must be a raw stream with no header or trailer.
• +24 to +31 = 16 + (8 to 15): Uses the low 4 bits of the value as the window size logarithm. The input must include a gzip header and trailer.
• +40 to +47 = 32 + (8 to 15): Uses the low 4 bits of the value as the window size logarithm, and automatically accepts either the zlib or gzip format.

When decompressing a stream, the window size must not be smaller than the size originally used to compress the stream; using a too-small value may result in an error exception. The default wbits value is 15, which corresponds to the largest window size and requires a zlib header and trailer to be included.

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

zlib.decompressobj([wbits])

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

The wbits parameter controls the size of the history buffer (or the "window size"), and what header and trailer format is expected. It has the same meaning as described for decompress().

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

Compress.compress(string)

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

Compress.flush([mode])

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

Compress.copy()

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

バージョン 2.5 で追加.

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

Decompress.unused_data

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

圧縮データ文字列がどこで終了しているかを決定する唯一の方法は、実際にそれを展開することです。つまり、大きなファイルの一部分に圧縮データが含まれているときに、その末端を調べるためには、データをファイルから読み出し、空でない文字列を後ろに続けて、 unused_data が空文字列でなくなるまで、展開オブジェクトの decompress() メソッドに入力しつづけるしかありません。

Decompress.unconsumed_tail

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

Decompress.decompress(string[, max_length])

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

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

Decompress.flush([length])

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

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

Decompress.copy()

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

バージョン 2.5 で追加.

参考

gzip モジュール

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

http://www.zlib.net

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

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

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