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

   バージョン 3.0 で変更: 常に符号のない値を返します。すべてのバージョ
   ンとプラットフォームの Python に渡って同一の数値を生成するには、
   "adler32(data) & 0xffffffff" を使用します。

zlib.compress(data, level=-1)

   Compresses the bytes in *data*, returning a bytes object containing
   compressed data. *level* is an integer from "0" to "9" or "-1"
   controlling the level of compression; "1" (Z_BEST_SPEED) is fastest
   and produces the least compression, "9" (Z_BEST_COMPRESSION) is
   slowest and produces the most.  "0" (Z_NO_COMPRESSION) 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). Raises the
   "error" exception if any error occurs.

   バージョン 3.6 で変更: *level* can now be used as a keyword
   parameter.

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

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

   *level* is the compression level -- an integer from "0" to "9" or
   "-1". A value of "1" (Z_BEST_SPEED) is fastest and produces the
   least compression, while a value of "9" (Z_BEST_COMPRESSION) is
   slowest and produces the most. "0" (Z_NO_COMPRESSION) 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* is the compression algorithm. Currently, the only
   supported value is "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, defaulting to "15" (MAX_WBITS):

   * +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" です。大きい値ほど多くのメモリを消費しますが
   、より速く、より小さな出力を作成します。

   *strategy* is used to tune the compression algorithm. Possible
   values are "Z_DEFAULT_STRATEGY", "Z_FILTERED", "Z_HUFFMAN_ONLY",
   "Z_RLE" (zlib 1.2.0.1) and "Z_FIXED" (zlib 1.2.2.2).

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

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

zlib.crc32(data[, value])

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

   バージョン 3.0 で変更: 常に符号のない値を返します。すべてのバージョ
   ンとプラットフォームの Python に渡って同一の数値を生成するには、
   "crc32(data) & 0xffffffff" を使用します。

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

   Decompresses the bytes in *data*, returning a bytes object
   containing the uncompressed data.  The *wbits* parameter depends on
   the format of *data*, 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 corresponds to the largest window size and requires a zlib
   header and trailer to be included.

   *bufsize* is the initial size of the buffer used to hold
   decompressed data.  If more space is required, the buffer size will
   be increased as needed, so you don't have to get this value exactly
   right; tuning it will only save a few calls to "malloc()".

   バージョン 3.6 で変更: *wbits* and *bufsize* can be used as keyword
   arguments.

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

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

   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().

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

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

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

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

Compress.compress(data)

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

Compress.flush([mode])

   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" (zlib 1.2.3.4), 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()

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

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

Decompress.unused_data

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

Decompress.unconsumed_tail

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

Decompress.eof

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

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

   バージョン 3.3 で追加.

Decompress.decompress(data, max_length=0)

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

   If the optional parameter *max_length* is non-zero then the return
   value will be no longer than *max_length*. This may mean that not
   all of the compressed input can be processed; and unconsumed data
   will be stored in the attribute "unconsumed_tail". This bytestring
   must be passed to a subsequent call to "decompress()" if
   decompression is to continue.  If *max_length* is zero then the
   whole input is decompressed, and "unconsumed_tail" is empty.

   バージョン 3.6 で変更: *max_length* can be used as a keyword
   argument.

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