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 版本发生变更: 接受 path-like object。

exception gzip.BadGzipFile

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

在 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 的文件位置，但它可能会改变底层文件对象的位置（例如，如果 GzipFile 是使用 fileobj 参数构造的）。

在 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 objects 的支持。read() 方法现在接受 None 参数。

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

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

版本 3.12 中有修改: 移除 filename 属性，请改用 name 属性。

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

压缩 data，返回一个包含压缩数据的 bytes 对象。compresslevel 和 mtime 的含义与上面的 GzipFile 构造函数相同，但为了可重现的输出，mtime 默认为 0。

在 3.2 版本加入。

版本 3.8 中有修改: 增加了 mtime 参数以实现可重现的输出。

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

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

版本 3.14 中有修改: mtime 参数现在默认为 0 以实现可重现的输出。对于使用当前时间的先前行为，请将 None 传递给 mtime。

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（解）压缩是瓶颈，python-isal 包以大多兼容的 API 加速（解）压缩。

命令行界面

gzip 模块提供了一个简单的命令行接口来压缩或解压缩文件。

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

版本 3.8 中有修改: 添加了一个带有用法的新的命令行接口。默认情况下，当您执行 CLI 时，默认压缩级别为 6。

命令行选项

file

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

--fast

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

--best

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

-d, --decompress

解压缩给定文件。

-h, --help

显示帮助消息。