# `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` モジュールで提供されています。

The `gzip` module provides the `GzipFile` class, as well as the `open()`, `compress()` and `decompress()` convenience functions. The `GzipFile` class reads and writes gzip-format files, automatically compressing or decompressing the data so that it looks like an ordinary file object.

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

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

gzip.open(filename, mode='rb', compresslevel=6, encoding=None, errors=None, newline=None, *, mtime=None)

  gzip 圧縮ファイルをバイナリまたはテキストモードで開き、ファイルオブジェクト を返します。

  引数 filename には実際のファイル名 (`str` または `bytes` オブジェクト) か、既存のファイルオブジェクトを指定します。

  引数 mode には、バイナリモード用に `'r'`、`'rb'`、`'a'`、`'ab'`、`'w'`、`'wb'`、`'x'`、または `'xb'`、テキストモード用に `'rt'`、`'at'`、`'wt'`、または `'xt'` を指定できます。デフォルトは `'rb'` です。

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

  The keyword-only argument mtime represents a Unix timestamp.

  For binary mode, this function is equivalent to the `GzipFile` constructor: `GzipFile(filename, mode, compresslevel, mtime=mtime)`. In this case, the encoding, errors and newline arguments must not be provided.

  テキストモードでは、`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 で変更: The default compression level was reduced to 6 (down from 9). It is the default level used by most compression tools and a better tradeoff between speed and performance.

  バージョン 3.16.0a0 (unreleased) で変更: Added keyword-only argument mtime which is passed to the class constructor of `GzipFile`.

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=6, 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. Set mtime to `0` to generate a compressed stream that does not depend on creation time. If mtime is omitted or `None`, the current time is used; however, if the current time is outside the range 00:00:00 UTC, January 1, 1970 through 06:28:15 UTC, February 7, 2106, or explicitly passed mtime argument is outside the range `0` to `2**32-1`, then the value `0` is used instead.

  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.

  バージョン 3.15 で変更: The default compression level was reduced to 6 (down from 9). It is the default level used by most compression tools and a better tradeoff between speed and performance.

gzip.compress(data, compresslevel=6, *, 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.

  バージョン 3.15 で変更: The default compression level was reduced to 6 (down from 9). It is the default level used by most compression tools and a better tradeoff between speed and performance.

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.

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

The `gzip` module provides a simple command line interface to compress or decompress files.

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

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