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

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

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

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

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

数据压缩由 "zlib" 模块提供。

"gzip" 模块提供了 "GzipFile" 类，以及 "open()", "compress()" 和
"decompress()" 等便捷函数。 "GzipFile" 类可以读写 **gzip** 格式的文件
，自动压缩和解压缩数据以使其看起来像是普通的 *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 来加快 (解) 压缩的速度。


命令行接口
==========

"gzip" 模块提供了简单的命令行界面用于压缩或解压缩文件。

在执行之后 "gzip" 模块会保留输入文件。module keeps the input file(s).

在 3.8 版本发生变更: 添加一个带有用法说明的新命令行界面命令。默认情况
下，当你要执行 CLI 时，默认压缩等级为 6。


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

file

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

--fast

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

--best

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

-d, --decompress

   解压缩给定的文件。

-h, --help

   显示帮助消息。
