1:mod:`!gzip` --- Support for :program:`gzip` files 2================================================== 3 4.. module:: gzip 5 :synopsis: Interfaces for gzip compression and decompression using file objects. 6 7**Source code:** :source:`Lib/gzip.py` 8 9-------------- 10 11This module provides a simple interface to compress and decompress files just 12like the GNU programs :program:`gzip` and :program:`gunzip` would. 13 14The data compression is provided by the :mod:`zlib` module. 15 16The :mod:`gzip` module provides the :class:`GzipFile` class, as well as the 17:func:`.open`, :func:`compress` and :func:`decompress` convenience functions. 18The :class:`GzipFile` class reads and writes :program:`gzip`\ -format files, 19automatically compressing or decompressing the data so that it looks like an 20ordinary :term:`file object`. 21 22Note that additional file formats which can be decompressed by the 23:program:`gzip` and :program:`gunzip` programs, such as those produced by 24:program:`compress` and :program:`pack`, are not supported by this module. 25 26The module defines the following items: 27 28 29.. function:: open(filename, mode='rb', compresslevel=9, encoding=None, errors=None, newline=None) 30 31 Open a gzip-compressed file in binary or text mode, returning a :term:`file 32 object`. 33 34 The *filename* argument can be an actual filename (a :class:`str` or 35 :class:`bytes` object), or an existing file object to read from or write to. 36 37 The *mode* argument can be any of ``'r'``, ``'rb'``, ``'a'``, ``'ab'``, 38 ``'w'``, ``'wb'``, ``'x'`` or ``'xb'`` for binary mode, or ``'rt'``, 39 ``'at'``, ``'wt'``, or ``'xt'`` for text mode. The default is ``'rb'``. 40 41 The *compresslevel* argument is an integer from 0 to 9, as for the 42 :class:`GzipFile` constructor. 43 44 For binary mode, this function is equivalent to the :class:`GzipFile` 45 constructor: ``GzipFile(filename, mode, compresslevel)``. In this case, the 46 *encoding*, *errors* and *newline* arguments must not be provided. 47 48 For text mode, a :class:`GzipFile` object is created, and wrapped in an 49 :class:`io.TextIOWrapper` instance with the specified encoding, error 50 handling behavior, and line ending(s). 51 52 .. versionchanged:: 3.3 53 Added support for *filename* being a file object, support for text mode, 54 and the *encoding*, *errors* and *newline* arguments. 55 56 .. versionchanged:: 3.4 57 Added support for the ``'x'``, ``'xb'`` and ``'xt'`` modes. 58 59 .. versionchanged:: 3.6 60 Accepts a :term:`path-like object`. 61 62.. exception:: BadGzipFile 63 64 An exception raised for invalid gzip files. It inherits from :exc:`OSError`. 65 :exc:`EOFError` and :exc:`zlib.error` can also be raised for invalid gzip 66 files. 67 68 .. versionadded:: 3.8 69 70.. class:: GzipFile(filename=None, mode=None, compresslevel=9, fileobj=None, mtime=None) 71 72 Constructor for the :class:`GzipFile` class, which simulates most of the 73 methods of a :term:`file object`, with the exception of the :meth:`~io.IOBase.truncate` 74 method. At least one of *fileobj* and *filename* must be given a non-trivial 75 value. 76 77 The new class instance is based on *fileobj*, which can be a regular file, an 78 :class:`io.BytesIO` object, or any other object which simulates a file. It 79 defaults to ``None``, in which case *filename* is opened to provide a file 80 object. 81 82 When *fileobj* is not ``None``, the *filename* argument is only used to be 83 included in the :program:`gzip` file header, which may include the original 84 filename of the uncompressed file. It defaults to the filename of *fileobj*, if 85 discernible; otherwise, it defaults to the empty string, and in this case the 86 original filename is not included in the header. 87 88 The *mode* argument can be any of ``'r'``, ``'rb'``, ``'a'``, ``'ab'``, ``'w'``, 89 ``'wb'``, ``'x'``, or ``'xb'``, depending on whether the file will be read or 90 written. The default is the mode of *fileobj* if discernible; otherwise, the 91 default is ``'rb'``. In future Python releases the mode of *fileobj* will 92 not be used. It is better to always specify *mode* for writing. 93 94 Note that the file is always opened in binary mode. To open a compressed file 95 in text mode, use :func:`.open` (or wrap your :class:`GzipFile` with an 96 :class:`io.TextIOWrapper`). 97 98 The *compresslevel* argument is an integer from ``0`` to ``9`` controlling 99 the level of compression; ``1`` is fastest and produces the least 100 compression, and ``9`` is slowest and produces the most compression. ``0`` 101 is no compression. The default is ``9``. 102 103 The optional *mtime* argument is the timestamp requested by gzip. The time 104 is in Unix format, i.e., seconds since 00:00:00 UTC, January 1, 1970. 105 If *mtime* is omitted or ``None``, the current time is used. Use *mtime* = 0 106 to generate a compressed stream that does not depend on creation time. 107 108 See below for the :attr:`mtime` attribute that is set when decompressing. 109 110 Calling a :class:`GzipFile` object's :meth:`!close` method does not close 111 *fileobj*, since you might wish to append more material after the compressed 112 data. This also allows you to pass an :class:`io.BytesIO` object opened for 113 writing as *fileobj*, and retrieve the resulting memory buffer using the 114 :class:`io.BytesIO` object's :meth:`~io.BytesIO.getvalue` method. 115 116 :class:`GzipFile` supports the :class:`io.BufferedIOBase` interface, 117 including iteration and the :keyword:`with` statement. Only the 118 :meth:`~io.IOBase.truncate` method isn't implemented. 119 120 :class:`GzipFile` also provides the following method and attribute: 121 122 .. method:: peek(n) 123 124 Read *n* uncompressed bytes without advancing the file position. 125 At most one single read on the compressed stream is done to satisfy 126 the call. The number of bytes returned may be more or less than 127 requested. 128 129 .. note:: While calling :meth:`peek` does not change the file position of 130 the :class:`GzipFile`, it may change the position of the underlying 131 file object (e.g. if the :class:`GzipFile` was constructed with the 132 *fileobj* parameter). 133 134 .. versionadded:: 3.2 135 136 .. attribute:: mode 137 138 ``'rb'`` for reading and ``'wb'`` for writing. 139 140 .. versionchanged:: 3.13 141 In previous versions it was an integer ``1`` or ``2``. 142 143 .. attribute:: mtime 144 145 When decompressing, this attribute is set to the last timestamp in the most 146 recently read header. It is an integer, holding the number of seconds 147 since the Unix epoch (00:00:00 UTC, January 1, 1970). 148 The initial value before reading any headers is ``None``. 149 150 .. attribute:: name 151 152 The path to the gzip file on disk, as a :class:`str` or :class:`bytes`. 153 Equivalent to the output of :func:`os.fspath` on the original input path, 154 with no other normalization, resolution or expansion. 155 156 .. versionchanged:: 3.1 157 Support for the :keyword:`with` statement was added, along with the 158 *mtime* constructor argument and :attr:`mtime` attribute. 159 160 .. versionchanged:: 3.2 161 Support for zero-padded and unseekable files was added. 162 163 .. versionchanged:: 3.3 164 The :meth:`io.BufferedIOBase.read1` method is now implemented. 165 166 .. versionchanged:: 3.4 167 Added support for the ``'x'`` and ``'xb'`` modes. 168 169 .. versionchanged:: 3.5 170 Added support for writing arbitrary 171 :term:`bytes-like objects <bytes-like object>`. 172 The :meth:`~io.BufferedIOBase.read` method now accepts an argument of 173 ``None``. 174 175 .. versionchanged:: 3.6 176 Accepts a :term:`path-like object`. 177 178 .. deprecated:: 3.9 179 Opening :class:`GzipFile` for writing without specifying the *mode* 180 argument is deprecated. 181 182 .. versionchanged:: 3.12 183 Remove the ``filename`` attribute, use the :attr:`~GzipFile.name` 184 attribute instead. 185 186 187.. function:: compress(data, compresslevel=9, *, mtime=None) 188 189 Compress the *data*, returning a :class:`bytes` object containing 190 the compressed data. *compresslevel* and *mtime* have the same meaning as in 191 the :class:`GzipFile` constructor above. 192 193 .. versionadded:: 3.2 194 .. versionchanged:: 3.8 195 Added the *mtime* parameter for reproducible output. 196 .. versionchanged:: 3.11 197 Speed is improved by compressing all data at once instead of in a 198 streamed fashion. Calls with *mtime* set to ``0`` are delegated to 199 :func:`zlib.compress` for better speed. In this situation the 200 output may contain a gzip header "OS" byte value other than 255 201 "unknown" as supplied by the underlying zlib implementation. 202 203 .. versionchanged:: 3.13 204 The gzip header OS byte is guaranteed to be set to 255 when this function 205 is used as was the case in 3.10 and earlier. 206 207.. function:: decompress(data) 208 209 Decompress the *data*, returning a :class:`bytes` object containing the 210 uncompressed data. This function is capable of decompressing multi-member 211 gzip data (multiple gzip blocks concatenated together). When the data is 212 certain to contain only one member the :func:`zlib.decompress` function with 213 *wbits* set to 31 is faster. 214 215 .. versionadded:: 3.2 216 .. versionchanged:: 3.11 217 Speed is improved by decompressing members at once in memory instead of in 218 a streamed fashion. 219 220.. _gzip-usage-examples: 221 222Examples of usage 223----------------- 224 225Example of how to read a compressed file:: 226 227 import gzip 228 with gzip.open('/home/joe/file.txt.gz', 'rb') as f: 229 file_content = f.read() 230 231Example of how to create a compressed GZIP file:: 232 233 import gzip 234 content = b"Lots of content here" 235 with gzip.open('/home/joe/file.txt.gz', 'wb') as f: 236 f.write(content) 237 238Example of how to GZIP compress an existing file:: 239 240 import gzip 241 import shutil 242 with open('/home/joe/file.txt', 'rb') as f_in: 243 with gzip.open('/home/joe/file.txt.gz', 'wb') as f_out: 244 shutil.copyfileobj(f_in, f_out) 245 246Example of how to GZIP compress a binary string:: 247 248 import gzip 249 s_in = b"Lots of content here" 250 s_out = gzip.compress(s_in) 251 252.. seealso:: 253 254 Module :mod:`zlib` 255 The basic data compression module needed to support the :program:`gzip` file 256 format. 257 258 259.. program:: gzip 260 261.. _gzip-cli: 262 263Command Line Interface 264---------------------- 265 266The :mod:`gzip` module provides a simple command line interface to compress or 267decompress files. 268 269Once executed the :mod:`gzip` module keeps the input file(s). 270 271.. versionchanged:: 3.8 272 273 Add a new command line interface with a usage. 274 By default, when you will execute the CLI, the default compression level is 6. 275 276Command line options 277^^^^^^^^^^^^^^^^^^^^ 278 279.. option:: file 280 281 If *file* is not specified, read from :data:`sys.stdin`. 282 283.. option:: --fast 284 285 Indicates the fastest compression method (less compression). 286 287.. option:: --best 288 289 Indicates the slowest compression method (best compression). 290 291.. option:: -d, --decompress 292 293 Decompress the given file. 294 295.. option:: -h, --help 296 297 Show the help message. 298