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.
- zlib.compress(data, /, level=-1, wbits=MAX_WBITS)¶
Compresses the bytes in data, returning a bytes object containing compressed data. level is an integer from
0to9or-1controlling 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).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.
Raises the
errorexception if any error occurs.バージョン 3.6 で変更: level can now be used as a keyword parameter.
バージョン 3.11 で変更: The wbits parameter is now available to set window bits and compression type.
- 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 parameter controls the size of the history buffer (or the "window size"), and what header and trailer format will be used. It has the same meaning as described for compress().
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 が与えられている場合、チェックサム計算の初期値として使われます。与えられていない場合、デフォルト値の 0 が使われます。 value を与えることで、複数の入力を結合したデータ全体にわたり、通しのチェックサムを計算できます。このアルゴリズムは暗号論的には強力ではなく、認証やデジタル署名などに用いるべきではありません。また、チェックサムアルゴリズムとして設計されているため、汎用のハッシュアルゴリズムには向きません。
バージョン 3.0 で変更: The result is always unsigned.
- 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
errorexception 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
errorexception. 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¶
圧縮データストリームの終了に達したかどうかを示すブール値です。
これは、正常な形式の圧縮ストリームと、不完全あるいは切り詰められたストリームとを区別することを可能にします。
Added in version 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 ライブラリのバージョン文字列です。
Added in version 3.3.
参考
gzipモジュールgzip 形式ファイルへの読み書きを行うモジュール。
- http://www.zlib.net
zlib ライブラリホームページ。
- http://www.zlib.net/manual.html
zlib ライブラリの多くの関数の意味と使い方を解説したマニュアル。