# `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 を受け入れるようになりました。

exception `gzip.``BadGzipFile`

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

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

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

  バージョン 3.9 で非推奨: Opening `GzipFile` for writing without specifying the mode argument is deprecated.

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

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

  バージョン 3.2 で追加.

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

`gzip.``decompress`(data)

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

  バージョン 3.2 で追加.

## 使い方の例

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

    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` モジュールは、 ファイルを圧縮、展開するための簡単なコマンドラインインターフェースを提供しています。

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```

  file を指定しない場合、 `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```

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