gzip — Support forgzip files¶

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:

gzip.open(filename,mode='rb',compresslevel=9,encoding=None,errors=None,newline=None)¶

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','wb','x' or'xb' for binary mode, or'rt','at','wt', or'xt' for text 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.

Changed in version 3.4:Added support for the'x','xb' and'xt' modes.

Changed in version 3.6:Accepts apath-like object.

exceptiongzip.BadGzipFile¶

An exception raised for invalid gzip files. It inherits fromOSError.EOFError andzlib.error can also be raised for invalid gzipfiles.

Added in version 3.8.

classgzip.GzipFile(filename=None,mode=None,compresslevel=9,fileobj=None,mtime=None)¶

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, anio.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','wb','x', or'xb', depending on whether the file will be read orwritten. The default is the mode offileobj if discernible; otherwise, thedefault is'rb'. In future Python releases the mode offileobj willnot be used. It is better to always specifymode for writing.

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.

The optionalmtime argument is the timestamp requested by gzip. The timeis in Unix format, i.e., seconds since 00:00:00 UTC, January 1, 1970.Ifmtime is omitted orNone, the current time is used. Usemtime = 0to generate a compressed stream that does not depend on creation time.

See below for themtime attribute that is set when decompressing.

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 anio.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 and attribute:

peek(n)¶

Readn uncompressed bytes without advancing the file position.The number of bytes returned may be more or less than requested.

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).

Added in version 3.2.

mode¶

'rb' for reading and'wb' for writing.

Changed in version 3.13:In previous versions it was an integer1 or2.

mtime¶

When decompressing, this attribute is set to the last timestamp in the mostrecently read header. It is an integer, holding the number of secondssince the Unix epoch (00:00:00 UTC, January 1, 1970).The initial value before reading any headers isNone.

name¶

The path to the gzip file on disk, as astr orbytes.Equivalent to the output ofos.fspath() on the original input path,with no other normalization, resolution or expansion.

Changed in version 3.1:Support for thewith statement was added, along with themtime constructor argument andmtime attribute.

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.

Changed in version 3.4:Added support for the'x' and'xb' modes.

Changed in version 3.5:Added support for writing arbitrarybytes-like objects.Theread() method now accepts an argument ofNone.

Changed in version 3.6:Accepts apath-like object.

Deprecated since version 3.9:OpeningGzipFile for writing without specifying themodeargument is deprecated.

Changed in version 3.12:Remove thefilename attribute, use thenameattribute instead.

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

Compress thedata, returning abytes object containingthe compressed data.compresslevel andmtime have the same meaning as intheGzipFile constructor above,butmtime defaults to 0 for reproducible output.

Added in version 3.2.

Changed in version 3.8:Added themtime parameter for reproducible output.

Changed in version 3.11:Speed is improved by compressing all data at once instead of in astreamed fashion. Calls withmtime set to0 are delegated tozlib.compress() for better speed. In this situation theoutput may contain a gzip header “OS” byte value other than 255“unknown” as supplied by the underlying zlib implementation.

Changed in version 3.13:The gzip header OS byte is guaranteed to be set to 255 when this functionis used as was the case in 3.10 and earlier.

Changed in version 3.14:Themtime parameter now defaults to 0 for reproducible output.For the previous behaviour of using the current time,passNone tomtime.

gzip.decompress(data)¶

Decompress thedata, returning abytes object containing theuncompressed data. This function is capable of decompressing multi-membergzip data (multiple gzip blocks concatenated together). When the data iscertain to contain only one member thezlib.decompress() function withwbits set to 31 is faster.

Added in version 3.2.

Changed in version 3.11:Speed is improved by decompressing members at once in memory instead of ina streamed fashion.

importgzipwithgzip.open('/home/joe/file.txt.gz','rb')asf:file_content=f.read()

importgzipcontent=b"Lots of content here"withgzip.open('/home/joe/file.txt.gz','wb')asf:f.write(content)

importgzipimportshutilwithopen('/home/joe/file.txt','rb')asf_in:withgzip.open('/home/joe/file.txt.gz','wb')asf_out:shutil.copyfileobj(f_in,f_out)

importgzips_in=b"Lots of content here"s_out=gzip.compress(s_in)