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 ライブラリの多くの関数の意味と使い方を解説したマニュアル。
