"zlib" --- **gzip** 互換の圧縮
******************************

======================================================================

このモジュールは、データ圧縮を必要とするアプリケーションが zlib ライブ
ラリを使って圧縮および展開を行えるようにします。zlib ライブラリ自身の
Webページは https://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 で変更: The result is always unsigned. To generate
   the same numeric value when using Python 2 or earlier, use
   "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* は圧縮レベルです。"0" から "9" 、または "-1" の整数を取り、
   "1" (Z_BEST_SPEED) は最も高速で最小限の圧縮を行い、"9"
   (Z_BEST_COMPRESSION) は最も低速で最大限の圧縮を行います。"0"
   (Z_NO_COMPRESSION) は圧縮しません。デフォルトは "-1" です
   (Z_DEFAULT_COMPRESSION)。Z_DEFAULT_COMPRESSION は、速度と圧縮の間の
   デフォルトの妥協点 (現在、レベル 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, 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* は圧縮アルゴリズムの調整に使用されます。指定可能な値は、
   "Z_DEFAULT_STRATEGY", "Z_FILTERED", "Z_HUFFMAN_ONLY", "Z_RLE" (zlib
   1.2.0.1) および "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 で変更: The result is always unsigned. To generate
   the same numeric value when using Python 2 or earlier, use
   "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* は展開されたデータを保持するためのバッファサイズの初期値
   です。バッファの空きは必要に応じて必要なだけ増加するので、必ずしも
   正確な値を指定する必要はありません。この値のチューニングでできるこ
   とは、"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])

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

Compress.copy()

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

バージョン 3.8 で変更: Added "copy.copy()" and "copy.deepcopy()"
support to compression objects.

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

Decompress.unused_data

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

Decompress.unconsumed_tail

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

Decompress.eof

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

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

   バージョン 3.3 で追加.

Decompress.decompress(data, max_length=0)

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

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

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

Decompress.flush([length])

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

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

Decompress.copy()

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

バージョン 3.8 で変更: Added "copy.copy()" and "copy.deepcopy()"
support to decompression objects.

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