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