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 which is modeled 17after Python's File Object. The :class:`GzipFile` class reads and writes 18:program:`gzip`\ -format files, automatically compressing or decompressing the 19data so that it looks like an ordinary file object. 20 21Note that additional file formats which can be decompressed by the 22:program:`gzip` and :program:`gunzip` programs, such as those produced by 23:program:`compress` and :program:`pack`, are not supported by this module. 24 25The module defines the following items: 26 27 28.. class:: GzipFile([filename[, mode[, compresslevel[, fileobj[, mtime]]]]]) 29 30 Constructor for the :class:`GzipFile` class, which simulates most of the methods 31 of a file object, with the exception of the :meth:`readinto` and 32 :meth:`truncate` methods. At least one of *fileobj* and *filename* must be 33 given a non-trivial value. 34 35 The new class instance is based on *fileobj*, which can be a regular file, a 36 :class:`~StringIO.StringIO` object, or any other object which simulates a file. It 37 defaults to ``None``, in which case *filename* is opened to provide a file 38 object. 39 40 When *fileobj* is not ``None``, the *filename* argument is only used to be 41 included in the :program:`gzip` file header, which may include the original 42 filename of the uncompressed file. It defaults to the filename of *fileobj*, if 43 discernible; otherwise, it defaults to the empty string, and in this case the 44 original filename is not included in the header. 45 46 The *mode* argument can be any of ``'r'``, ``'rb'``, ``'a'``, ``'ab'``, ``'w'``, 47 or ``'wb'``, depending on whether the file will be read or written. The default 48 is the mode of *fileobj* if discernible; otherwise, the default is ``'rb'``. If 49 not given, the 'b' flag will be added to the mode to ensure the file is opened 50 in binary mode for cross-platform portability. 51 52 The *compresslevel* argument is an integer from ``0`` to ``9`` controlling 53 the level of compression; ``1`` is fastest and produces the least 54 compression, and ``9`` is slowest and produces the most compression. ``0`` 55 is no compression. The default is ``9``. 56 57 The *mtime* argument is an optional numeric timestamp to be written to 58 the stream when compressing. All :program:`gzip` compressed streams are 59 required to contain a timestamp. If omitted or ``None``, the current 60 time is used. This module ignores the timestamp when decompressing; 61 however, some programs, such as :program:`gunzip`\ , make use of it. 62 The format of the timestamp is the same as that of the return value of 63 ``time.time()`` and of the ``st_mtime`` attribute of the object returned 64 by ``os.stat()``. 65 66 Calling a :class:`GzipFile` object's :meth:`close` method does not close 67 *fileobj*, since you might wish to append more material after the compressed 68 data. This also allows you to pass a :class:`~StringIO.StringIO` object opened for 69 writing as *fileobj*, and retrieve the resulting memory buffer using the 70 :class:`~StringIO.StringIO` object's :meth:`~StringIO.StringIO.getvalue` method. 71 72 :class:`GzipFile` supports iteration and the :keyword:`with` statement. 73 74 .. versionchanged:: 2.7 75 Support for the :keyword:`with` statement was added. 76 77 .. versionchanged:: 2.7 78 Support for zero-padded files was added. 79 80 .. versionadded:: 2.7 81 The *mtime* argument. 82 83 84.. function:: open(filename[, mode[, compresslevel]]) 85 86 This is a shorthand for ``GzipFile(filename,`` ``mode,`` ``compresslevel)``. 87 The *filename* argument is required; *mode* defaults to ``'rb'`` and 88 *compresslevel* defaults to ``9``. 89 90 91.. _gzip-usage-examples: 92 93Examples of usage 94----------------- 95 96Example of how to read a compressed file:: 97 98 import gzip 99 with gzip.open('file.txt.gz', 'rb') as f: 100 file_content = f.read() 101 102Example of how to create a compressed GZIP file:: 103 104 import gzip 105 content = "Lots of content here" 106 with gzip.open('file.txt.gz', 'wb') as f: 107 f.write(content) 108 109Example of how to GZIP compress an existing file:: 110 111 import gzip 112 import shutil 113 with open('file.txt', 'rb') as f_in, gzip.open('file.txt.gz', 'wb') as f_out: 114 shutil.copyfileobj(f_in, f_out) 115 116 117.. seealso:: 118 119 Module :mod:`zlib` 120 The basic data compression module needed to support the :program:`gzip` file 121 format. 122 123