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 中更改: 接受 类路径对象。
- 异常 gzip.BadGzipFile¶
针对无效的 gzip 文件引发的异常。它继承自
OSError
。对于无效的 gzip 文件,也可以引发EOFError
和zlib.error
。3.8 版新增。
- 类 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* 参数是一个可选的数字时间戳,在压缩时写入到流中的最后修改时间字段。它应该只在压缩模式下提供。如果省略或为
None
,则使用当前时间。有关更多详细信息,请参阅mtime
属性。调用
GzipFile
对象的close()
方法不会关闭 *fileobj*,因为您可能希望在压缩数据之后追加更多内容。这也允许您传递一个为写入而打开的io.BytesIO
对象作为 *fileobj*,并使用io.BytesIO
对象的getvalue()
方法检索生成的内存缓冲区。GzipFile
支持io.BufferedIOBase
接口,包括迭代和with
语句。只有truncate()
方法未实现。GzipFile
还提供以下方法和属性- peek(n)¶
读取 *n* 个未压缩的字节,而不推进文件位置。最多对压缩流进行一次读取以满足调用。返回的字节数可能多于或少于请求的字节数。
3.2 版新增。
- mtime¶
解压缩时,可以从该属性中读取最近读取的标头中最后修改时间字段的值,作为整数。读取任何标头之前的初始值为
None
。所有 gzip 压缩流都必须包含此时间戳字段。一些程序(例如 gunzip)会使用此时间戳。格式与
time.time()
的返回值和os.stat()
返回的对象的st_mtime
属性相同。
- name¶
磁盘上 gzip 文件的路径,为
str
或bytes
类型。等效于对原始输入路径执行os.fspath()
的输出,不进行任何其他规范化、解析或扩展。
在 3.2 版更改: 添加了对零填充和不可查找文件的支持。
在 3.3 版更改: 现在实现了
io.BufferedIOBase.read1()
方法。在 3.4 版更改: 添加了对
'x'
和'xb'
模式的支持。在版本 3.6 中更改: 接受 类路径对象。
在 3.12 版更改: 删除了
filename
属性,请改用name
属性。3.9 版后已弃用: 不指定 *mode* 参数就打开
GzipFile
进行写入已被弃用。
- gzip.compress(data, compresslevel=9, *, mtime=None)¶
压缩 data,返回一个包含压缩数据的
bytes
对象。compresslevel 和 mtime 的含义与上述GzipFile
构造函数中的含义相同。当 mtime 设置为0
时,此函数等效于将 wbits 设置为31
的zlib.compress()
。zlib 函数速度更快。3.2 版新增。
版本 3.8 中的变化: 添加了 mtime 参数以实现可重现的输出。
版本 3.11 中的变化: 通过一次性压缩所有数据而不是以流式方式压缩数据来提高速度。将 mtime 设置为
0
的调用将委托给zlib.compress()
以提高速度。在这种情况下,输出可能包含 gzip 标头“OS”字节值,而不是底层 zlib 实现提供的 255“未知”。
- 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。
命令行选项¶
- --fast¶
表示最快的压缩方法(压缩率较低)。
- --best¶
表示最慢的压缩方法(压缩率最高)。
- -d, --decompress¶
解压缩给定的文件。
- -h, --help¶
显示帮助信息。