gzip --- gzip ファイルのサポート

ソースコード: Lib/gzip.py

このモジュールは、GNU の gzip や gunzip のようにファイルを圧縮、展開するシンプルなインターフェイスを提供しています。

データ圧縮は zlib モジュールで提供されています。

gzip は GzipFile クラスと、簡易関数 open()、compress()、および decompress() を提供しています。GzipFile クラスは通常の ファイルオブジェクト と同様に gzip 形式のファイルを読み書きし、データを自動的に圧縮または展開します。

compress や pack 等によって作成され、gzip や gunzip が展開できる他のファイル形式についてはこのモジュールは対応していないので注意してください。

このモジュールは以下の項目を定義しています:

gzip.open(filename, mode='rb', compresslevel=9, encoding=None, errors=None, newline=None)

gzip 圧縮ファイルをバイナリまたはテキストモードで開き、ファイルオブジェクト を返します。

引数 filename には実際のファイル名 (str または bytes オブジェクト) か、既存のファイルオブジェクトを指定します。

引数 mode には、バイナリモード用に 'r'、'rb'、'a'、'ab'、'w'、'wb'、'x'、または 'xb'、テキストモード用に 'rt'、'at'、'wt'、または 'xt' を指定できます。デフォルトは 'rb' です。

引数 compresslevel は GzipFile コンストラクタと同様に 0 から 9 の整数を取ります。

バイナリモードでは、この関数は GzipFile コンストラクタ GzipFile(filename, mode, compresslevel) と等価です。この時、引数 encoding、errors、および newline を指定してはいけません。

テキストモードでは、GzipFile オブジェクトが作成され、指定されたエンコーディング、エラーハンドラの挙動、および改行文字で io.TextIOWrapper インスタンスにラップされます。

バージョン 3.3 で変更: filename にファイルオブジェクト指定のサポート、テキストモードのサポート、および引数に encoding、errors、および newline を追加しました。

バージョン 3.4 で変更: Added support for the 'x', 'xb' and 'xt' modes.

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

exception gzip.BadGzipFile

不正な gzip ファイルに対して送出される例外です。 OSError を継承します。 不正な gzip ファイルに対しては EOFError や zlib.error が送出される場合もあります。

Added in version 3.8.

class gzip.GzipFile(filename=None, mode=None, compresslevel=9, fileobj=None, mtime=None)

GzipFile クラスのコンストラクタです。 GzipFile オブジェクトは truncate() メソッドを除くほとんどの ファイルオブジェクト のメソッドをシミュレートします。 fileobj と filename の少なくとも一方には、有効な値を指定しなければなりません。

クラスの新しいインスタンスは、 fileobj に基づいて作成されます。 fileobj は通常のファイル、 io.BytesIO オブジェクト、 そしてその他ファイルをシミュレートできるオブジェクトでかまいません。 値はデフォルトでは None で、その場合ファイルオブジェクトを生成するために filename を開きます。

fileobj が None でない場合、filename 引数は gzip ファイルヘッダにインクルードされることのみに使用されます。gzip ファイルヘッダは圧縮されていないファイルの元の名前をインクルードするかもしれません。認識可能な場合、規定値は fileobj のファイル名です。そうでない場合、規定値は空の文字列で、元のファイル名はヘッダにはインクルードされません。

mode 引数には、読み取りか書き込みかに応じて 'r'、'rb'、'a'、'ab'、'w'、'wb'、'x'、'xb' のいずれかを指定できます。 デフォルトは、fileobj のモードが分かる場合はそのモード、そうでなければ 'rb' です。 今後の Python のリリースでは fileobj のモードを使わなくなります。 書き込みの場合は、常に mode を指定することを推奨します。

ファイルは常にバイナリモードで開かれることに注意してください。圧縮ファイルをテキストモードで開く場合、open() (または GzipFile を io.TextIOWrapper でラップしたオブジェクト) を使ってください。

引数 compresslevel は 0 から 9 の整数を取り、圧縮レベルを制御します; 1 は最も高速で最小限の圧縮を行い、9 は最も低速ですが最大限の圧縮を行います。0 は圧縮しません。デフォルトは 9 です。

The optional mtime argument is the timestamp requested by gzip. The time is in Unix format, i.e., seconds since 00:00:00 UTC, January 1, 1970. If mtime is omitted or None, the current time is used. Use mtime = 0 to generate a compressed stream that does not depend on creation time.

展開時に設定される mtime 属性については、以下を参照してください。

圧縮したデータの後ろにさらに何か追加したい場合もあるので、GzipFile オブジェクトの close() メソッド呼び出しは fileobj を閉じません。 このため、書き込みのためにオープンした io.BytesIO オブジェクトを fileobj として渡し、(GzipFile を close() した後に) io.BytesIO オブジェクトの getvalue() メソッドを使って書き込んだデータの入っているメモリバッファを取得することができます。

GzipFile は、イテレーションと with 文を含む io.BufferedIOBase インターフェイスをサポートしています。truncate() メソッドのみ実装されていません。

GzipFile は以下のメソッドと属性も提供しています:

peek(n)

ファイル位置を進めずに、展開後のデータを n バイト読み込みます。 返されるバイト数は要求した数より多くなることも少なくなることもあります。

注釈

peek() の呼び出しでは GzipFile のファイル位置は変わりませんが、下層のファイルオブジェクトの位置が変わる惧れがあります。(e.g. GzipFile が fileobj 引数で作成された場合)

Added in version 3.2.

mode

'rb' は読み込み用、 'wb' は書き込み用です。

バージョン 3.13 で変更: 以前のバージョンでは整数の 1 または 2 でした。

mtime

展開時、この属性には最後に読み取ったヘッダーのタイムスタンプが設定されます。 Unix エポック (1970 年 1 月 1 日 00:00:00 UTC) からの秒数を表す整数です。 ヘッダーを読み取る前の初期値は None です。

name

ディスク上の gzip ファイルへのパスを表す str または bytes です。 元の入力パスに os.fspath() を適用した結果と等しく、それ以外の正規化、解決、展開は行いません。

バージョン 3.1 で変更: with 文がサポートされました。mtime コンストラクタ引数と mtime 属性が追加されました。

バージョン 3.2 で変更: ゼロパディングされたファイルやシーク出来ないファイルがサポートされました。

バージョン 3.3 で変更: io.BufferedIOBase.read1() メソッドを実装しました。

バージョン 3.4 で変更: 'x' ならびに 'xb' モードがサポートされました。

バージョン 3.5 で変更: 任意の バイトライクオブジェクト の書き込みがサポートされました。 read() メソッドが None を引数として受け取るようになりました。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

バージョン 3.9 で非推奨: mode 引数を指定せずに GzipFile を書き込み用に開くことは非推奨になりました。

バージョン 3.12 で変更: filename 属性が削除されました。 代わりに name 属性を使ってください。

gzip.compress(data, compresslevel=9, *, mtime=None)

Compress the data, returning a bytes object containing the compressed data. compresslevel and mtime have the same meaning as in the GzipFile constructor above.

Added in version 3.2.

バージョン 3.8 で変更: 再現可能な出力を得るための mtime 引数が追加されました。

バージョン 3.11 で変更: ストリームとして処理する代わりにすべてのデータを一度に圧縮することで、高速化しました。 mtime が 0 の呼び出しは、速度を上げるために zlib.compress() に委譲されます。 この場合、内部で使う zlib 実装が設定する値により、出力の gzip ヘッダーの "OS" バイトが、255 ("unknown") 以外になることがあります。

バージョン 3.13 で変更: この関数を使った場合、3.10 以前と同様に、gzip ヘッダーの OS バイトが 255 に設定されることを保証するようになりました。

gzip.decompress(data)

data を展開し、展開したデータを含む bytes オブジェクトを返します。 この関数は、複数のメンバーからなる gzip データ (複数の gzip ブロックを連結したもの) を展開できます。 データにメンバーが 1 つしか含まれないことが確実な場合は、wbits を 31 に設定した zlib.decompress() 関数の方が高速です。

Added in version 3.2.

バージョン 3.11 で変更: ストリームとして処理する代わりに、メモリ内でメンバーを一度に展開することで高速化しました。

使い方の例

圧縮されたファイルを読み込む例:

import gzip
with gzip.open('/home/joe/file.txt.gz', 'rb') as f:
    file_content = f.read()

GZIP 圧縮されたファイルを作成する例:

import gzip
content = b"Lots of content here"
with gzip.open('/home/joe/file.txt.gz', 'wb') as f:
    f.write(content)

既存のファイルを GZIP 圧縮する例:

import gzip
import shutil
with open('/home/joe/file.txt', 'rb') as f_in:
    with gzip.open('/home/joe/file.txt.gz', 'wb') as f_out:
        shutil.copyfileobj(f_in, f_out)

バイナリ文字列を GZIP 圧縮する例:

import gzip
s_in = b"Lots of content here"
s_out = gzip.compress(s_in)

参考

zlib モジュール

gzip ファイル形式のサポートを行うために必要な基本ライブラリモジュール。

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

Command-line interface

gzip モジュールは、 ファイルを圧縮、展開するための簡単なコマンドラインインターフェースを提供しています。

Once executed the gzip module keeps the input file(s).

バージョン 3.8 で変更: 使用方法を表示する新しいコマンドラインインターフェースが追加されました。 CLI 実行時のデフォルトの圧縮レベルは 6 です。

Command-line options

file

file を指定しない場合は、sys.stdin から読み取ります。

--fast

最速の圧縮方法 (低い圧縮率) を指定します。

--best

最も遅い圧縮方法 (最も高い圧縮率) を指定します。

-d, --decompress

指定したファイルを展開します。

-h, --help

ヘルプメッセージを出力します