gzip — 支持 gzip 文件

源代码： Lib/gzip.py

---

该模块提供了一个简单的接口来压缩和解压缩文件，就像 GNU 程序 gzip 和 gunzip 一样。

数据压缩由 zlib 模块提供。

gzip 模块提供了 GzipFile 类，以及 open()、 compress() 和 decompress() 便捷函数。GzipFile 类读取和写入 gzip 格式的文件，自动压缩或解压缩数据，使其看起来像一个普通的 文件对象。

请注意，gzip 和 gunzip 程序可以解压缩的其他文件格式，例如 compress 和 pack 生成的格式，此模块不支持。

该模块定义了以下项

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 参数是一个介于 0 到 9 之间的整数，与 GzipFile 构造函数相同。

对于二进制模式，此函数等效于 GzipFile 构造函数：GzipFile(filename, mode, compresslevel)。在这种情况下，不能提供 encoding、errors 和 newline 参数。

对于文本模式，会创建一个 GzipFile 对象，并将其包装在具有指定编码、错误处理行为和行尾的 io.TextIOWrapper 实例中。

在 3.3 版本中更改: 添加了对 filename 作为文件对象，对文本模式的支持，以及 encoding、errors 和 newline 参数的支持。

在 3.4 版本中更改: 添加了对 'x'、'xb' 和 'xt' 模式的支持。

在 3.6 版本中更改: 接受 路径类对象。

exception gzip.BadGzipFile

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

3.8 版本新增。

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

GzipFile 类的构造函数，它模拟了 文件对象 的大多数方法，除了 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()（或将你的 GzipFile 与 io.TextIOWrapper 一起包装）。

compresslevel 参数是一个介于 0 到 9 之间的整数，用于控制压缩级别；1 最快且产生最小的压缩，而 9 最慢且产生最大的压缩。0 表示不压缩。默认值为 9。

可选的 mtime 参数是 gzip 请求的时间戳。时间采用 Unix 格式，即自 1970 年 1 月 1 日 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 的文件位置，但它可能会更改底层文件对象的位置（例如，如果使用 fileobj 参数构造了 GzipFile）。

在版本 3.2 中添加。

mode

读取为 'rb'，写入为 'wb'。

在 3.13 版本中更改: 在之前的版本中，它是一个整数 1 或 2。

mtime

在解压缩时，此属性设置为最近读取的标头中的最后一个时间戳。它是一个整数，表示自 Unix 纪元（1970 年 1 月 1 日 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 对象 的支持。read() 方法现在接受 None 的参数。

在 3.6 版本中更改: 接受 路径类对象。

自 3.9 版本起弃用: 不指定 mode 参数而打开 GzipFile 进行写入已被弃用。

在 3.12 版本中更改: 删除 filename 属性，请改用 name 属性。

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

压缩 data，返回一个包含压缩数据的 bytes 对象。compresslevel 和 mtime 的含义与上面的 GzipFile 构造函数中的含义相同。

在版本 3.2 中添加。

在 3.8 版本中更改: 添加了用于可重复输出的 mtime 参数。

在 3.11 版本中更改: 通过一次性压缩所有数据而不是以流式方式压缩来提高速度。将 mtime 设置为 0 的调用会委托给 zlib.compress() 以获得更快的速度。在这种情况下，输出可能包含一个 gzip 标头 “OS” 字节值，该值不是底层 zlib 实现提供的 255 “未知”。

在 3.13 版本中更改: 当使用此函数时，gzip 标头 OS 字节保证设置为 255，就像在 3.10 及更早版本中一样。

gzip.decompress(data)

解压缩 data，返回一个包含未压缩数据的 bytes 对象。此函数能够解压缩多成员 gzip 数据（多个 gzip 块连接在一起）。当数据确定只包含一个成员时，将 wbits 设置为 31 的 zlib.decompress() 函数会更快。

在版本 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 模块提供了一个简单的命令行界面来压缩或解压缩文件。

一旦执行，gzip 模块会保留输入文件。

在 3.8 版本中更改: 添加了新的命令行界面及其用法。默认情况下，当执行 CLI 时，默认压缩级别为 6。

命令行选项

file

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

--fast

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

--best

指示最慢的压缩方法（最佳压缩率）。

-d, --decompress

解压缩给定的文件。

-h, --help

显示帮助信息。