"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.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" 属性を使ってください。

   バージョン 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 です
。


コマンドラインオプション
------------------------

file

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

--fast

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

--best

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

-d, --decompress

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

-h, --help

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