gzip --- gzip ファイルのサポート¶
ソースコード: Lib/gzip.py
このモジュールは、GNU の gzip や gunzip のようにファイルを圧縮、展開するシンプルなインターフェイスを提供しています。
これは optional module です。 使用している CPython に含まれていない場合は、配布元 (Python を提供した組織や人) のドキュメントを参照してください。 配布する側の場合は オプションのモジュールの要件 を参照してください。
データ圧縮は zlib モジュールで提供されています。
gzip モジュールは GzipFile クラスと、便利な関数 open()、compress()、decompress() を提供します。
GzipFile クラスは gzip 形式のファイルを読み書きし、データを自動的に圧縮・展開するため、通常の file object と同じように扱えます。
compress や pack 等によって作成され、gzip や gunzip が展開できる他のファイル形式についてはこのモジュールは対応していないので注意してください。
このモジュールは以下の項目を定義しています:
- gzip.open(filename, mode='rb', compresslevel=6, 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 を受け入れるようになりました。
バージョン 3.15 で変更: デフォルトの圧縮レベルが 9 から 6 に下がりました。 これはほとんどの圧縮ツールが使うデフォルトのレベルで、速度と圧縮性能のバランスがより優れています。
- exception gzip.BadGzipFile¶
不正な gzip ファイルに対して送出される例外です。
OSErrorを継承します。 不正な gzip ファイルに対してはEOFErrorやzlib.errorが送出される場合もあります。Added in version 3.8.
- class gzip.GzipFile(filename=None, mode=None, compresslevel=6, 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は圧縮しません。 デフォルトは6です。省略可能な mtime 引数は、gzip が要求するタイムスタンプです。 時刻は Unix 形式、つまり 1970 年 1 月 1 日 00:00:00 UTC からの秒数で指定します。 作成時刻に依存しない圧縮ストリームを生成するには、mtime を
0にしてください。 mtime を省略するかNoneにすると、現在時刻を使います。 ただし、現在時刻が 1970 年 1 月 1 日 00:00:00 UTC から 2106 年 2 月 7 日 06:28:15 UTC までの範囲外の場合や、明示的に渡した mtime 引数が0から2**32-1の範囲外の場合は、代わりに0を使います。展開時に設定される
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.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属性を使ってください。バージョン 3.15 で変更: デフォルトの圧縮レベルが 9 から 6 に下がりました。 これはほとんどの圧縮ツールが使うデフォルトのレベルで、速度と圧縮性能のバランスがより優れています。
- gzip.compress(data, compresslevel=6, *, mtime=0)¶
data を圧縮し、圧縮データを含む
bytesオブジェクトを返します。 compresslevel と mtime は上記のGzipFileコンストラクタと同じ意味ですが、再現可能な出力を得るために mtime のデフォルトは 0 です。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 に設定されることを保証するようになりました。
バージョン 3.14 で変更: 再現可能な出力を得るために、mtime 引数のデフォルトが 0 になりました。 以前のように現在時刻を使うには、mtime に
Noneを渡してください。バージョン 3.15 で変更: デフォルトの圧縮レベルが 9 から 6 に下がりました。 これはほとんどの圧縮ツールが使うデフォルトのレベルで、速度と圧縮性能のバランスがより優れています。
- 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 の圧縮・展開がボトルネックになっている場合は、ほぼ互換性のある API を持つ python-isal パッケージで高速化できます。
コマンドライン・インターフェース¶
gzip モジュールは、ファイルを圧縮・展開するための簡単なコマンドラインインターフェースを提供します。
gzip モジュールは、実行後も入力ファイルを残します。
バージョン 3.8 で変更: 使用方法を表示する新しいコマンドラインインターフェースが追加されました。 CLI 実行時のデフォルトの圧縮レベルは 6 です。
コマンドラインオプション¶
- --fast¶
最速の圧縮方法 (低い圧縮率) を指定します。
- --best¶
最も遅い圧縮方法 (最も高い圧縮率) を指定します。
- -d, --decompress¶
指定したファイルを展開します。
- -h, --help¶
ヘルプメッセージを出力します