Source code:Lib/gzip.py
This module provides a simple interface to compress and decompress files justlike the GNU programsgzip andgunzip would.
The data compression is provided by thezlib module.
Thegzip module provides theGzipFile class, as well as theopen(),compress() anddecompress() convenience functions.TheGzipFile class reads and writesgzip-format files,automatically compressing or decompressing the data so that it looks like anordinaryfile object.
Note that additional file formats which can be decompressed by thegzip andgunzip programs, such as those produced bycompress andpack, are not supported by this module.
The module defines the following items:
Open a gzip-compressed file in binary or text mode, returning afileobject.
Thefilename argument can be an actual filename (astr orbytes object), or an existing file object to read from or write to.
Themode argument can be any of'r','rb','a','ab','w', or'wb' for binary mode, or'rt','at', or'wt' fortext mode. The default is'rb'.
Thecompresslevel argument is an integer from 0 to 9, as for theGzipFile constructor.
For binary mode, this function is equivalent to theGzipFileconstructor:GzipFile(filename,mode,compresslevel). In this case, theencoding,errors andnewline arguments must not be provided.
For text mode, aGzipFile object is created, and wrapped in anio.TextIOWrapper instance with the specified encoding, errorhandling behavior, and line ending(s).
Changed in version 3.3:Added support forfilename being a file object, support for text mode,and theencoding,errors andnewline arguments.
Constructor for theGzipFile class, which simulates most of themethods of afile object, with the exception of thetruncate()method. At least one offileobj andfilename must be given a non-trivialvalue.
The new class instance is based onfileobj, which can be a regular file, aio.BytesIO object, or any other object which simulates a file. Itdefaults toNone, in which casefilename is opened to provide a fileobject.
Whenfileobj is notNone, thefilename argument is only used to beincluded in thegzip file header, which may include the originalfilename of the uncompressed file. It defaults to the filename offileobj, ifdiscernible; otherwise, it defaults to the empty string, and in this case theoriginal filename is not included in the header.
Themode argument can be any of'r','rb','a','ab','w',or'wb', depending on whether the file will be read or written. The defaultis the mode offileobj if discernible; otherwise, the default is'rb'.
Note that the file is always opened in binary mode. To open a compressed filein text mode, useopen() (or wrap yourGzipFile with anio.TextIOWrapper).
Thecompresslevel argument is an integer from0 to9 controllingthe level of compression;1 is fastest and produces the leastcompression, and9 is slowest and produces the most compression.0is no compression. The default is9.
Themtime argument is an optional numeric timestamp to be written tothe stream when compressing. Allgzip compressed streams arerequired to contain a timestamp. If omitted orNone, the currenttime is used. This module ignores the timestamp when decompressing;however, some programs, such asgunzip, make use of it.The format of the timestamp is the same as that of the return value oftime.time() and of thest_mtime attribute of the object returnedbyos.stat().
Calling aGzipFile object’sclose() method does not closefileobj, since you might wish to append more material after the compresseddata. This also allows you to pass aio.BytesIO object opened forwriting asfileobj, and retrieve the resulting memory buffer using theio.BytesIO object’sgetvalue() method.
GzipFile supports theio.BufferedIOBase interface,including iteration and thewith statement. Only thetruncate() method isn’t implemented.
GzipFile also provides the following method:
Readn uncompressed bytes without advancing the file position.At most one single read on the compressed stream is done to satisfythe call. The number of bytes returned may be more or less thanrequested.
Note
While callingpeek() does not change the file position oftheGzipFile, it may change the position of the underlyingfile object (e.g. if theGzipFile was constructed with thefileobj parameter).
New in version 3.2.
Changed in version 3.1:Support for thewith statement was added, along with themtime argument.
Changed in version 3.2:Support for zero-padded and unseekable files was added.
Changed in version 3.3:Theio.BufferedIOBase.read1() method is now implemented.
Compress thedata, returning abytes object containingthe compressed data.compresslevel has the same meaning as intheGzipFile constructor above.
New in version 3.2.
Decompress thedata, returning abytes object containing theuncompressed data.
New in version 3.2.
Example of how to read a compressed file:
importgzipwithgzip.open('/home/joe/file.txt.gz','rb')asf:file_content=f.read()
Example of how to create a compressed GZIP file:
importgzipcontent=b"Lots of content here"withgzip.open('/home/joe/file.txt.gz','wb')asf:f.write(content)
Example of how to GZIP compress an existing file:
importgzipwithopen('/home/joe/file.txt','rb')asf_in:withgzip.open('/home/joe/file.txt.gz','wb')asf_out:f_out.writelines(f_in)
Example of how to GZIP compress a binary string:
importgzips_in=b"Lots of content here"s_out=gzip.compress(s_in)
See also
13.1.zlib — Compression compatible withgzip
13.3.bz2 — Support forbzip2 compression
Enter search terms or a module, class or function name.
