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

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

データ圧縮が必要なアプリケーションでは、このモジュールの関数を使い、
zlib library による圧縮と展開を行えます。

これは *オプションモジュール* です。 使用している CPython に含まれてい
ない場合は、配布元 (Python を提供した組織など) のドキュメントを確認し
てください。 配布する立場の場合は オプションのモジュールの要件 を参照
してください。

zlib の関数には多くのオプションがあり、決まった順序で使わなければなら
ないことがよくあります。 このドキュメントはすべての組み合わせを網羅す
るものではありません。 正式な情報は zlib manual を参照してください。

".gz" ファイルの読み書きのためには、 "gzip" モジュールを参照してくださ
い。

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

exception zlib.error

   圧縮および展開時のエラーによって送出される例外です。

zlib.adler32(data, value=1, /)

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

   バージョン 3.0 で変更: 結果は常に符号なしになりました。

zlib.adler32_combine(adler1, adler2, len2, /)

   2 つの Adler-32 チェックサムを 1 つに結合します。

   シーケンス "A" の Adler-32 チェックサム *adler1* と、長さ *len2* の
   シーケンス "B" の Adler-32 チェックサム *adler2* を受け取り、"A" と
   "B" を連結したデータの Adler-32 チェックサムを返します。

   この関数は、並行して計算した Adler-32 チェックサムを結合する場合な
   どに役立ちます。 チェックサムを順次計算する場合は、"adler32()" の
   "value" 引数にそれまでのチェックサムを渡してください。

   Added in version 3.15.

zlib.compress(data, /, level=Z_DEFAULT_COMPRESSION, wbits=MAX_WBITS)

   *data* のバイト列を圧縮し、圧縮データを含む bytes オブジェクトを返
   します。 *level* は圧縮レベルを制御する "0" から "9" までの整数、ま
   たは "-1" です。 これらの値の詳細は、"Z_BEST_SPEED" ("1")、
   "Z_BEST_COMPRESSION" ("9")、"Z_NO_COMPRESSION" ("0")、デフォルトの
   "Z_DEFAULT_COMPRESSION" ("-1") を参照してください。

   *wbits* 引数は、データの圧縮に使う履歴バッファのサイズ (ウィンドウ
   サイズ) と、出力にヘッダーとトレーラーを含めるかどうかを制御します
   。 次に示す複数の範囲の値を指定でき、デフォルトは "15"
   ("MAX_WBITS") です。

   * +9 から +15: ウィンドウサイズの 2 を底とする対数です。 ウィンドウ
     サイズは 512 から 32768 の範囲になります。 大きい値ほど圧縮率が高
     くなりますが、より多くのメモリを消費します。 出力には zlib 固有の
     ヘッダーとトレーラーが含まれます。

   * −9 から −15: *wbits* の絶対値をウィンドウサイズの対数として使い、
     ヘッダーや末尾のチェックサムを含まない生のストリームを出力します
     。

   * +25 から +31 = 16 + (9 から 15): 値の下位 4 ビットをウィンドウサ
     イズの対数として使い、基本的な **gzip** ヘッダーと末尾のチェック
     サムを出力に含めます。

   エラーが発生すると "error" 例外を送出します。

   バージョン 3.6 で変更: *level* をキーワード引数として使えるようにな
   りました。

   バージョン 3.11 で変更: *wbits* 引数でウィンドウのビット数と圧縮形
   式を設定できるようになりました。

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

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

   *level* は圧縮レベルで、"0" から "9" までの整数、または "-1" です。
   これらの値の詳細は、"Z_BEST_SPEED" ("1")、"Z_BEST_COMPRESSION"
   ("9")、"Z_NO_COMPRESSION" ("0")、デフォルトの
   "Z_DEFAULT_COMPRESSION" ("-1") を参照してください。

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

   *wbits* 引数は、履歴バッファのサイズ (ウィンドウサイズ) と、使用す
   るヘッダーとトレーラーの形式を制御します。 compress() の説明 と同じ
   意味です。

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

   *strategy* は圧縮アルゴリズムの調整に使います。 指定できる値は
   "Z_DEFAULT_STRATEGY"、"Z_FILTERED"、"Z_HUFFMAN_ONLY"、"Z_RLE"、
   "Z_FIXED" です。

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

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

zlib.crc32(data, value=0, /)

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

   バージョン 3.0 で変更: 結果は常に符号なしになりました。

zlib.crc32_combine(crc1, crc2, len2, /)

   2 つの CRC-32 チェックサムを 1 つに結合します。

   シーケンス "A" の CRC-32 チェックサム *crc1* と、長さ *len2* のシー
   ケンス "B" の CRC-32 チェックサム *crc2* を受け取り、"A" と "B" を
   連結したデータの CRC-32 チェックサムを返します。

   この関数は、並行して計算した CRC-32 チェックサムを結合する場合など
   に役立ちます。 チェックサムを順次計算する場合は、"crc32()" の
   "value" 引数にそれまでのチェックサムを渡してください。

   Added in version 3.15.

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

   *data* のバイト列を展開し、展開済みのデータを含む bytes オブジェク
   トを返します。 *wbits* 引数の値は *data* の形式に依存します。 詳細
   は後述します。 *bufsize* を指定すると、出力バッファの初期サイズとし
   て使われます。 エラーが発生すると "error" 例外を送出します。

   *wbits* 引数は、履歴バッファのサイズ (ウィンドウサイズ) と、入力に
   想定するヘッダーとトレーラーの形式を制御します。 "compressobj()" の
   引数と似ていますが、より多くの範囲の値を受け付けます。

   * +8 から +15: ウィンドウサイズの 2 を底とする対数です。 入力には
     zlib のヘッダーとトレーラーが含まれていなければなりません。

   * 0: zlib ヘッダーからウィンドウサイズを自動的に判定します。 zlib
     1.2.3.5 以降でのみサポートされています。

   * −8 から −15: *wbits* の絶対値をウィンドウサイズの対数として使いま
     す。 入力はヘッダーやトレーラーを含まない生のストリームでなければ
     なりません。

   * +24 から +31 = 16 + (8 から 15): 値の下位 4 ビットをウィンドウサ
     イズの対数として使います。 入力には gzip のヘッダーとトレーラーが
     含まれていなければなりません。

   * +40 から +47 = 32 + (8 から 15): 値の下位 4 ビットをウィンドウサ
     イズの対数として使い、zlib 形式と gzip 形式の両方を自動的に受け付
     けます。

   ストリームを展開する際、ウィンドウサイズは圧縮時に使われたサイズ以
   上でなければなりません。 小さすぎる値を使うと "error" 例外が発生す
   る場合があります。 *wbits* のデフォルト値は最大のウィンドウサイズに
   対応し、入力には zlib のヘッダーとトレーラーが必要です。

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

   バージョン 3.6 で変更: *wbits* と *bufsize* をキーワード引数として
   使えるようになりました。

zlib.decompressobj(wbits=MAX_WBITS, zdict=b'')

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

   *wbits* 引数は、履歴バッファのサイズ (ウィンドウサイズ) と、入力に
   想定するヘッダーとトレーラーの形式を制御します。 decompress() の説
   明 と同じ意味です。

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

   注釈:

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

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

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

Compress.compress(data, /)

   *data* を圧縮し、その少なくとも一部に対応する圧縮データを含むバイト
   列オブジェクトを返します。 返されたデータは、以前の "compress()" メ
   ソッドの呼び出しで得た出力に連結する必要があります。 入力の一部は、
   後で処理するために内部バッファに保持されることがあります。

Compress.flush(mode=Z_FINISH, /)

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

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

バージョン 3.8 で変更: 圧縮オブジェクトで "copy.copy()" と
"copy.deepcopy()" をサポートしました。

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

Decompress.unused_data

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

Decompress.unconsumed_tail

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

Decompress.eof

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

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

   Added in version 3.3.

Decompress.decompress(data, /, max_length=0)

   *data* を展開し、少なくとも *string* の一部に対応する展開済みデータ
   を含む bytes オブジェクトを返します。 このデータは、以前の
   "decompress()" 呼び出しで得た出力に連結する必要があります。 入力デ
   ータの一部は、後で処理するために内部バッファに保持される場合があり
   ます。

   省略可能な *max_length* 引数が 0 でない場合、返されるデータの長さは
   *max_length* 以下になります。 このため、圧縮された入力をすべて処理
   できない場合があり、未処理のデータは "unconsumed_tail" 属性に格納さ
   れます。 展開を続けるには、このバイト列を後続の "decompress()" 呼び
   出しに渡す必要があります。 *max_length* が 0 の場合は入力全体が展開
   され、"unconsumed_tail" は空になります。 例えば、次のように内容をす
   べて読み込めます。

      process_output(d.decompress(data, max_length))
      while chunk := d.decompress(d.unconsumed_tail, max_length):
          process_output(chunk)

   バージョン 3.6 で変更: *max_length* をキーワード引数として使えるよ
   うになりました。

Decompress.flush(length=DEF_BUF_SIZE, /)

   未処理の入力をすべて処理し、残りの展開済みデータを含むバイト列オブ
   ジェクトを返します。 "flush()" を呼び出した後は "decompress()" を再
   度呼び出すことはできません。 その後にできる現実的な操作は、オブジェ
   クトを削除することだけです。

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

Decompress.copy()

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

バージョン 3.8 で変更: 展開オブジェクトで "copy.copy()" と
"copy.deepcopy()" をサポートしました。

圧縮と展開の動作を設定するために、次の定数を利用できます。

zlib.DEFLATED

   deflate 圧縮方式。

zlib.MAX_WBITS

   最大ウィンドウサイズを 2 のべき乗の指数で表した値です。 例えば
   "MAX_WBITS" が "15" の場合、ウィンドウサイズは "32 KiB" になります
   。

zlib.DEF_MEM_LEVEL

   圧縮オブジェクトのデフォルトのメモリレベル。

zlib.DEF_BUF_SIZE

   展開処理のデフォルトのバッファサイズ。

zlib.Z_NO_COMPRESSION

   圧縮レベル "0"。 圧縮しません。

   Added in version 3.6.

zlib.Z_BEST_SPEED

   圧縮レベル "1"。 最も高速ですが、圧縮率は最も低くなります。

zlib.Z_BEST_COMPRESSION

   圧縮レベル "9"。 最も低速ですが、圧縮率は最も高くなります。

zlib.Z_DEFAULT_COMPRESSION

   デフォルトの圧縮レベル ("-1")。 速度と圧縮率のバランスを取ります。
   現在は圧縮レベル "6" と同じです。

zlib.Z_DEFAULT_STRATEGY

   通常のデータ向けのデフォルトの圧縮戦略。

zlib.Z_FILTERED

   フィルター (または予測器) が生成したデータ向けの圧縮戦略。

zlib.Z_HUFFMAN_ONLY

   ハフマン符号化のみを使う圧縮戦略。

zlib.Z_RLE

   一致するデータとの距離を 1 に制限する圧縮戦略 (ランレングス符号化)
   。

   この定数は、Python が zlib 1.2.0.1 以降でコンパイルされている場合に
   のみ利用できます。

   Added in version 3.6.

zlib.Z_FIXED

   動的ハフマン符号の使用を禁止する圧縮戦略。

   この定数は、Python が zlib 1.2.2.2 以降でコンパイルされている場合に
   のみ利用できます。

   Added in version 3.6.

zlib.Z_NO_FLUSH

   フラッシュモード "0"。 特別なフラッシュ処理は行いません。

   Added in version 3.6.

zlib.Z_PARTIAL_FLUSH

   フラッシュモード "1"。 できる限り多くの出力をフラッシュします。

zlib.Z_SYNC_FLUSH

   フラッシュモード "2"。 すべての出力をフラッシュし、出力をバイト境界
   に揃えます。

zlib.Z_FULL_FLUSH

   フラッシュモード "3"。 すべての出力をフラッシュし、圧縮状態をリセッ
   トします。

zlib.Z_FINISH

   フラッシュモード "4"。 保留中の入力をすべて処理し、それ以上の入力は
   受け付けません。

zlib.Z_BLOCK

   フラッシュモード "5"。 deflate ブロックを完結させて出力します。

   この定数は、Python が zlib 1.2.2.2 以降でコンパイルされている場合に
   のみ利用できます。

   Added in version 3.6.

zlib.Z_TREES

   inflate 処理用のフラッシュモード "6"。 次の deflate ブロック境界に
   達したら戻るように inflate に指示します。

   この定数は、Python が zlib 1.2.3.4 以降でコンパイルされている場合に
   のみ利用できます。

   Added in version 3.6.

使用している zlib ライブラリのバージョン情報を以下の定数で確認できます
:

zlib.ZLIB_VERSION

   モジュールのビルド時に使用された zlib ライブラリのバージョン文字列
   です。これは "ZLIB_RUNTIME_VERSION" で確認できる、実行時に使用して
   いる実際の zlib ライブラリのバージョンとは異なる場合があります。

zlib.ZLIB_RUNTIME_VERSION

   インタプリタが読み込んだ実際の zlib ライブラリのバージョン文字列で
   す。

   Added in version 3.3.

zlib.ZLIBNG_VERSION

   zlib-ng を使ってこのモジュールをビルドした場合、その zlib-ng ライブ
   ラリのバージョン文字列です。 この定数がある場合、"ZLIB_VERSION" 定
   数と "ZLIB_RUNTIME_VERSION" 定数は zlib-ng が提供する zlib API のバ
   ージョンを表します。

   zlib-ng を使わずにこのモジュールをビルドした場合、この定数は存在し
   ません。

   Added in version 3.14.

参考:

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

  https://www.zlib.net
     zlib ライブラリホームページ。

  https://www.zlib.net/manual.html
     zlib ライブラリの多くの関数の意味と使い方を解説したマニュアル。

  gzip の圧縮や展開がボトルネックとなる場合、python-isal パッケージを
  使うと、ほぼ互換性のある API で圧縮や展開を高速化できます。
