13.2. gzipgzip ファイルのサポート

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


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

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

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

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

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

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' です。

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

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

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

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

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

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

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

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

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

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

引数 mode は、ファイルを読み込むのか書き出すのかによって、'r''rb''a''ab''w''wb''x'、および 'xb' のいずれかになります。fileobj のファイルモードが認識可能な場合、mode はデフォルトで fileobj のモードと同じになります。そうでない場合、デフォルトのモードは 'rb' です。

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

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

mtime 引数は、圧縮時にストリームの最終更新日時フィールドに書き込まれるオプションの数値のタイムスタンプです。これは、圧縮モードでのみ提供することができます。省略された場合か None である場合、現在時刻が使用されます。詳細については、 mtime 属性を参照してください。

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

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

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

peek(n)

ファイル内の位置を移動せずに展開した n バイトを読み込みます。呼び出し要求を満たすために、圧縮ストリームに対して最大 1 回の単一読み込みが行われます。返されるバイト数はほぼ要求した値になります。

注釈

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

バージョン 3.2 で追加.

mtime

展開時に、最後に読み取られたヘッダーの最終更新日時フィールドの値は、この属性から整数として読み取ることができます。ヘッダーを読み取る前の初期値は None です。

gzip で圧縮されたすべてのストリームは、このタイムスタンプフィールドを含む必要があります。gunzip などの一部のプログラムがこのタイムスタンプを使用します。形式は、 time.time() の返り値や、os.stat() が返すオブジェクトの st_mtime 属性と同一です。

バージョン 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 を受け入れるようになりました。

gzip.compress(data, compresslevel=9)

data を圧縮し、圧縮データを含む bytes オブジェクトを返します。compresslevel の意味は上記 GzipFile コンストラクタと同じです。

バージョン 3.2 で追加.

gzip.decompress(data)

data を展開し、展開データを含む bytes オブジェクトを返します。

バージョン 3.2 で追加.

13.2.1. 使い方の例

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

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 ファイル形式のサポートを行うために必要な基本ライブラリモジュール。