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

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

======================================================================

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

This is an *optional module*. If it is missing from your copy of
CPython, look for documentation from your distributor (that is,
whoever provided Python to you). If you are the distributor, see オプ
ションのモジュールの要件.

データ圧縮は "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

   An exception raised for invalid gzip files.  It inherits from
   "OSError". "EOFError" and "zlib.error" can also be raised for
   invalid gzip files.

   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* のファイル名です。そう
   でない場合、規定値は空の文字列で、元のファイル名はヘッダにはインク
   ルードされません。

   The *mode* argument can be any of "'r'", "'rb'", "'a'", "'ab'",
   "'w'", "'wb'", "'x'", or "'xb'", depending on whether the file will
   be read or written.  The default is the mode of *fileobj* if
   discernible; otherwise, the default is "'rb'".  In future Python
   releases the mode of *fileobj* will not be used.  It is better to
   always specify *mode* for writing.

   ファイルは常にバイナリモードで開かれることに注意してください。圧縮
   ファイルをテキストモードで開く場合、"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.

   See below for the "mtime" attribute that is set when decompressing.

   圧縮したデータの後ろにさらに何か追加したい場合もあるので、
   "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 で変更: In previous versions it was an integer
      "1" or "2".

   mtime

      When decompressing, this attribute is set to the last timestamp
      in the most recently read header.  It is an integer, holding the
      number of seconds since the Unix epoch (00:00:00 UTC, January 1,
      1970). The initial value before reading any headers is "None".

   name

      The path to the gzip file on disk, as a "str" or "bytes".
      Equivalent to the output of "os.fspath()" on the original input
      path, with no other normalization, resolution or expansion.

   バージョン 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 で非推奨: Opening "GzipFile" for writing without
   specifying the *mode* argument is deprecated.

   バージョン 3.12 で変更: Remove the "filename" attribute, use the
   "name" attribute instead.

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

   Compress the *data*, returning a "bytes" object containing the
   compressed data.  *compresslevel* and *mtime* have the same meaning
   as in the "GzipFile" constructor above, but *mtime* defaults to 0
   for reproducible output.

   Added in version 3.2.

   バージョン 3.8 で変更: Added the *mtime* parameter for reproducible
   output.

   バージョン 3.11 で変更: Speed is improved by compressing all data
   at once instead of in a streamed fashion. Calls with *mtime* set to
   "0" are delegated to "zlib.compress()" for better speed. In this
   situation the output may contain a gzip header "OS" byte value
   other than 255 "unknown" as supplied by the underlying zlib
   implementation.

   バージョン 3.13 で変更: The gzip header OS byte is guaranteed to be
   set to 255 when this function is used as was the case in 3.10 and
   earlier.

   バージョン 3.14 で変更: The *mtime* parameter now defaults to 0 for
   reproducible output. For the previous behaviour of using the
   current time, pass "None" to *mtime*.

gzip.decompress(data)

   Decompress the *data*, returning a "bytes" object containing the
   uncompressed data. This function is capable of decompressing multi-
   member gzip data (multiple gzip blocks concatenated together). When
   the data is certain to contain only one member the
   "zlib.decompress()" function with *wbits* set to 31 is faster.

   Added in version 3.2.

   バージョン 3.11 で変更: Speed is improved by decompressing members
   at once in memory instead of in a streamed fashion.


使い方の例
==========

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

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

  In case gzip (de)compression is a bottleneck, the python-isal
  package speeds up (de)compression with a mostly compatible API.


コマンドライン・インターフェース
================================

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

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

バージョン 3.8 で変更: Add a new command line interface with a usage.
By default, when you will execute the CLI, the default compression
level is 6.


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

file

   If *file* is not specified, read from "sys.stdin".

--fast

   Indicates the fastest compression method (less compression).

--best

   Indicates the slowest compression method (best compression).

-d, --decompress

   Decompress the given file.

-h, --help

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