"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'" or "'xb'" , 或者是文本模式 "'rt'", "'at'", "'wt'", or
   "'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" 对
   象，或者任何一个与文件相似的对象。当 *filename* 是一个文件对象时，
   它的默认值是 "None"。

   当  *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'" and "'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" 模块会保留输入文件。

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


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

file

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

--fast

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

--best

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

-d, --decompress

   解压缩给定的文件。

-h, --help

   显示帮助消息。
