"gzip" --- 对 **gzip** 文件的支持
*********************************

**源代码：** Lib/gzip.py

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

此模块提供的简单接口帮助用户压缩和解压缩文件，功能类似于 GNU 应用程序
**gzip** 和 **gunzip**。

这是一个 *optional module*。如果它在你的 CPython 副本中缺失，请查看你
的发行方（也就是说，向你提供 Python 的人）的文档。如果你就是发行方，请
参阅 针对可选模块的要求。

数据压缩由 "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*.

注意，此模块不支持部分可以被 **gzip** 和 **gunzip** 解压的格式，如利用
**compress** 或 **pack** 压缩所得的文件。

这个模块定义了以下内容：

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

   以二进制方式或者文本方式打开一个 gzip 格式的压缩文件，返回一个
   *file object*。

   *filename* 参数可以是一个实际的文件名（一个 "str" 对象或者 "bytes"
   对象），或者是一个用来读写的已存在的文件对象。

   *mode* 参数可以是二进制模式： "'r'"、"'rb'"、"'a'"、"'ab'"、"'w'"、
   "'wb'"、"'x'" 或 "'xb'"，或者是文本模式 "'rt'"、"'at'"、"'wt'" 或
   "'xt'"。默认值是 "'rb'"。

   The *compresslevel* argument is an integer from 0 to 9, as for the
   "GzipFile" constructor.

   对于二进制模式，这个函数等价于 "GzipFile" 构造器：
   "GzipFile(filename, mode, compresslevel)"。在此情况下，*encoding*、
   *errors* 和 *newline* 三个参数一定不要设置。

   对于文本模式，将会创建一个 "GzipFile" 对象，并将它封装到一个
   "io.TextIOWrapper" 实例中，该实例具有指定的编码、错误处理行为和行结
   束符。

   在 3.3 版本发生变更: 支持 *filename* 为一个文件对象，支持文本模式和
   *encoding*, *errors* 和 *newline* 参数。

   在 3.4 版本发生变更: 支持 "'x'", "'xb'" 和 "'xt'" 三种模式。

   在 3.6 版本发生变更: 接受一个 *path-like object*。

exception gzip.BadGzipFile

   针对无效 gzip 文件引发的异常。它继承自 "OSError"。针对无效 gzip 文
   件也可能引发 "EOFError" 和 "zlib.error".

   Added in version 3.8.

class gzip.GzipFile(filename=None, mode=None, compresslevel=9, fileobj=None, mtime=None)

   "GzipFile" 类的构造器，它模拟了 *file object* 的大部分方法，但
   "truncate()" 方法除外。 *fileobj* 和 *filename* 中至少有一个必须为
   非空值。

   新的实例基于 *fileobj*，它可以是一个普通文件，一个 "io.BytesIO" 对
   象，或者任何模拟文件的对象。它的默认值是 "None"，在此情况下会打开
   *filename* 来提供文件对象。

   当 *fileobj* 不为 "None" 时，*filename* 参数只用于 **gzip** 文件头
   中，文件头有可能包含未压缩文件的源文件名。如果可识别，默认为
   *fileobj* 的文件名；否则默认为空字符串，在这种情况下文件头将不包含
   源文件名。

   *mode* 参数可以是 "'r'", "'rb'", "'a'", "'ab'", "'w'", "'wb'",
   "'x'" 或 "'xb'" 中的一个，具体取决于文件将被读取还是被写入。如果可
   识别则默认为 *fileobj* 的模式；否则默认为 "'rb'"。在未来的 Python
   发布版中将不再使用 *fileobj* 的模式。最好总是指定 *mode* 为写入模式
   。

   需要注意的是，文件默认使用二进制模式打开。如果要以文本模式打开一个
   压缩文件，请使用 "open()" 方法 (或者使用 "io.TextIOWrapper" 包装
   "GzipFile")。

   *compresslevel* 参数是一个从 "0" 到 "9" 的整数，用于控制压缩等级；
   "1" 最快但压缩比例最小，"9" 最慢但压缩比例最大。"0" 不压缩。默认为
   "9"。

   可选的 *mtime* 参数是 gzip 所请求的时间戳。该时间为 Unix 格式，即距
   离 1970-01-01 00:00:00 UTC 的秒数。 如果 *mtime* 被省略或为 "None"
   ，则会使用当前时间。使用 *mtime* = 0 可生成不依赖于创建时间的压缩流
   。

   有关在解压缩时设置的 "mtime" 属性见下文。

   调用 "GzipFile" 对象的 "close()" 方法不会关闭 *fileobj*，因为你可能
   希望在已压缩的数据后追加更多内容。你还可以传入一个以写入模式打开的
   "io.BytesIO" 对象作为 *fileobj*，并使用 "io.BytesIO" 对象的
   "getvalue()" 方法提取所得到的内存缓冲区数据。

   "GzipFile" 支持 "io.BufferedIOBase" 接口，包括迭代和 "with" 语句。
   只有 "truncate()" 方法未被实现。

   "GzipFile" 还提供了以下的方法和属性：

   peek(n)

      读取 *n* 个未压缩字节而不前移文件指针位置。所返回的字节数有可能
      多于或少于所请求的。

      备注:

        调用 "peek()" 不会改变 "GzipFile" 的文件位置，但它可能改变底层
        文件对象的位置（例如 "GzipFile" 是使用 *fileobj* 参数来构造的
        情况）。

      Added in version 3.2.

   mode

      "'rb'" 表示可读而 "'wb'" 表示可写。

      在 3.13 版本发生变更: 在之前版本中该值为整数 "1" 或 "2"。

   mtime

      当解压缩时，该属性将被设为最近读取的标头中的最后时间戳。它是一个
      整数，保存从 Unix 纪元 (1970-01-01 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 版本发生变更: 支持写入任意 *bytes-like objects*。"read()" 方
   法可以接受 "None" 为参数。

   在 3.6 版本发生变更: 接受一个 *path-like object*。

   自 3.9 版本弃用: 打开 "GzipFile" 用于写入而不指定 *mode* 参数的做法
   已被弃用。

   在 3.12 版本发生变更: 移除 "filename" 属性，改用 "name" 属性。

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

   对 *data* 进行压缩，返回一个包含已压缩数据的 "bytes" 对象。
   *compresslevel* 和 *mtime* 具有与上文 "GzipFile" 构造器中相同的含义
   ，但 *mtime* 默认为 0 以确保可复现的输出。

   Added in version 3.2.

   在 3.8 版本发生变更: 添加了 *mtime* 形参用于可重复的输出。

   在 3.11 版本发生变更: 速度的提升是通过一次性压缩所有数据代替流的方
   式来达成的。将 *mtime* 设为 "0" 的调用被委托给 "zlib.compress()" 以
   加快速度。在此情况下输出可能包含一个 gzip 标头 "OS" 字节值而不是下
   层 zlib 实现所提供的 255 "unknown"。

   在 3.13 版本发生变更: 当使用此函数时 gzip 标头 OS 字节会保证如在
   3.10 和更早版本中一样被设为 255。

   在 3.14 版本发生变更: 现在 *mtime* 形参默认为 0 以确保可复现的输出
   。要保留之前版本中使用当前时间的行为，则将 "None" 传给 *mtime*。

gzip.decompress(data)

   解压缩 *data*，返回一个包含已解压数据的 "bytes" 对象。此函数可以解
   压缩多成员的 gzip 数据（即多个 gzip 块拼接在一起）。当数据确定只包
   含一个成员时则 *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 (解) 压缩成为瓶颈的情况，python-isal 软件包会使用基本兼容
  的 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 版本发生变更: 添加一个带有用法说明的新命令行界面命令。默认情况
下，当你要执行 CLI 时，默认压缩等级为 6。


命令行选项
----------

file

   如果未指定 *file*，则从 "sys.stdin" 读取。

--fast

   指明最快速的压缩方法（较低压缩率）。

--best

   指明最慢速的压缩方法（最高压缩率）。

-d, --decompress

   解压缩给定的文件。

-h, --help

   显示帮助消息。
