13.2. "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* を受け入れるようになりま
   した。

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* のファイルモードが認識可能な場合、*mode* は
   デフォルトで *fileobj* のモードと同じになります。そうでない場合、デ
   フォルトのモードは "'rb'" です。

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

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

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

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

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

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

   peek(n)

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

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

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