# 7.15 `zlib` -- gzip 互換の圧縮

このモジュールでは、データ圧縮を必要とするアプリケーションが zlib ライブラリ を使って圧縮および解凍を行えるようにします。 zlib ライブラリ自体の Web ホームページは http://www.gzip.org/zlib/にある。2000 年 9 月の時点での最新バージョンは 1.1.3 です。可能なら これ以降のバージョンを使うのがよいでしょう。 以前のバージョンの zlib ライブラリにはこの Python モジュールと互換性 のない部分があることが知られています。

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

exception `error`
  圧縮および解凍時のエラーによって送出される例外。

`adler32`( | string[, value])

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

`compress`( | string[, level])

  string で与えられた文字列を圧縮し、圧縮されたデータを含む 文字列を返します。 level は `1` から `9` までの 整数をとる値で、圧縮のレベルを制御します。 `1` は最も高速 で最小限の圧縮を行います。`9` はもっとも低速になりますが 最大限の圧縮を行います。デフォルトの値は `6` です。 圧縮時に何らかのエラーが発生した場合、 `error` 例外を 送出します。

`compressobj`( | [level])

  一度にメモリ上に置くことができないようなデータストリームを圧縮 するための圧縮オブジェクトを返します。level は `1` から `9` までの整数で、圧縮レベルを制御します。`1` は もっとも高速で最小限の圧縮を、`9` はもっとも低速になりますが 最大限の圧縮を行います。デフォルトの値は `6` です。

`crc32`( | string[, value])

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

`decompress`( | string[, wbits[, bufsize]])

  string 内のデータを解凍して、解凍されたデータを含む文字列を 返します。wbits パラメタはウィンドウバッファの大きさを制御 します。 bufsize が与えられていれば、出力バッファの書記サイズ として使われます。解凍処理に何らかのエラーが生じた場合、 `error` 例外を送出します。

  wbits の絶対値は、データを圧縮する際に用いられるヒストリ バッファのサイズ (ウィンドウサイズ) に対し、 2 を底とする対数を とったものです。最近のほとんどのバージョンの zlib ライブラリを 使っているなら、wbits の絶対値は 8 から 15 とするべきです。 より大きな値はより良好な圧縮につながりますが、より多くのメモリ を必要とします。デフォルトの値は 15 です。wbits の値が 負の場合、標準的な gzip ヘッダを出力しません。 これは zlib ライブラリの非公開仕様であり、unzip の 圧縮ファイル形式に対する互換性のためのものです。

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

`decompressobj`( | [wbits])

  メモリ上に一度に展開できないようなデータストリームを解凍するために 用いられる解凍オブジェクトを返します。wbits パラメタは ウィンドウバッファのサイズを制御します。

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

`compress`( | string)

  string を圧縮し、圧縮されたデータを含む文字列を返します。この 文字列は少なくとも string に相当します。このデータは以前に呼んだ `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()` メソッドを再び呼ぶべきではありません。唯一の現実的な操作はこの オブジェクトを削除することだけです。

解凍オブジェクトは以下のメソッドと 2 つの属性をサポートします:

`unused_data`
  圧縮データの末尾までのバイト列が入った文字列です。 すなわち、この値は圧縮データの入っているバイト列の最後の文字 までが読み出せるかぎり `""` となります。入力文字列全てが圧縮 データを含んでいた場合、この属性は `""` 、すなわち空文字列に なります。

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

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

`decompress`( | string)

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

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

`flush`( | )

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

参考資料:

`gzip`モジュール:
  Reading and writing gzip-format files.

http://www.gzip.org/zlib/
  The zlib library home page.