blob: edd5587b4a895a32c3289c4baa4edf7a41dcf017 [file] [log] [blame]
Georg Brandl116aa622007-08-15 14:28:22 +00001:mod:`gzip` --- Support for :program:`gzip` files
2=================================================
3
4.. module:: gzip
5 :synopsis: Interfaces for gzip compression and decompression using file objects.
6
Christian Heimesbbe741d2008-03-28 10:53:29 +00007This module provides a simple interface to compress and decompress files just
8like the GNU programs :program:`gzip` and :program:`gunzip` would.
Georg Brandl116aa622007-08-15 14:28:22 +00009
Georg Brandl1f01deb2009-01-03 22:47:39 +000010The data compression is provided by the :mod:`zlib` module.
Christian Heimesbbe741d2008-03-28 10:53:29 +000011
Antoine Pitrou11cb9612010-09-15 11:11:28 +000012The :mod:`gzip` module provides the :class:`GzipFile` class. The :class:`GzipFile`
13class reads and writes :program:`gzip`\ -format files, automatically compressing
14or decompressing the data so that it looks like an ordinary :term:`file object`.
Christian Heimesbbe741d2008-03-28 10:53:29 +000015
16Note that additional file formats which can be decompressed by the
17:program:`gzip` and :program:`gunzip` programs, such as those produced by
18:program:`compress` and :program:`pack`, are not supported by this module.
Georg Brandl116aa622007-08-15 14:28:22 +000019
Guido van Rossum77677112007-11-05 19:43:04 +000020For other archive formats, see the :mod:`bz2`, :mod:`zipfile`, and
21:mod:`tarfile` modules.
22
Georg Brandl116aa622007-08-15 14:28:22 +000023The module defines the following items:
24
25
Georg Brandl036490d2009-05-17 13:00:36 +000026.. class:: GzipFile(filename=None, mode=None, compresslevel=9, fileobj=None, mtime=None)
Georg Brandl116aa622007-08-15 14:28:22 +000027
28 Constructor for the :class:`GzipFile` class, which simulates most of the methods
Antoine Pitrou11cb9612010-09-15 11:11:28 +000029 of a :term:`file object`, with the exception of the :meth:`readinto` and
Georg Brandl116aa622007-08-15 14:28:22 +000030 :meth:`truncate` methods. At least one of *fileobj* and *filename* must be
31 given a non-trivial value.
32
33 The new class instance is based on *fileobj*, which can be a regular file, a
34 :class:`StringIO` object, or any other object which simulates a file. It
35 defaults to ``None``, in which case *filename* is opened to provide a file
36 object.
37
38 When *fileobj* is not ``None``, the *filename* argument is only used to be
39 included in the :program:`gzip` file header, which may includes the original
40 filename of the uncompressed file. It defaults to the filename of *fileobj*, if
41 discernible; otherwise, it defaults to the empty string, and in this case the
42 original filename is not included in the header.
43
44 The *mode* argument can be any of ``'r'``, ``'rb'``, ``'a'``, ``'ab'``, ``'w'``,
45 or ``'wb'``, depending on whether the file will be read or written. The default
46 is the mode of *fileobj* if discernible; otherwise, the default is ``'rb'``. If
47 not given, the 'b' flag will be added to the mode to ensure the file is opened
48 in binary mode for cross-platform portability.
49
50 The *compresslevel* argument is an integer from ``1`` to ``9`` controlling the
51 level of compression; ``1`` is fastest and produces the least compression, and
52 ``9`` is slowest and produces the most compression. The default is ``9``.
53
Antoine Pitrou42db3ef2009-01-04 21:37:59 +000054 The *mtime* argument is an optional numeric timestamp to be written to
Benjamin Petersone0124bd2009-03-09 21:04:33 +000055 the stream when compressing. All :program:`gzip` compressed streams are
Antoine Pitrou42db3ef2009-01-04 21:37:59 +000056 required to contain a timestamp. If omitted or ``None``, the current
57 time is used. This module ignores the timestamp when decompressing;
58 however, some programs, such as :program:`gunzip`\ , make use of it.
59 The format of the timestamp is the same as that of the return value of
60 ``time.time()`` and of the ``st_mtime`` member of the object returned
61 by ``os.stat()``.
62
Georg Brandl116aa622007-08-15 14:28:22 +000063 Calling a :class:`GzipFile` object's :meth:`close` method does not close
64 *fileobj*, since you might wish to append more material after the compressed
65 data. This also allows you to pass a :class:`StringIO` object opened for
66 writing as *fileobj*, and retrieve the resulting memory buffer using the
67 :class:`StringIO` object's :meth:`getvalue` method.
68
Benjamin Peterson886af962010-03-21 23:13:07 +000069 :class:`GzipFile` supports iteration and the :keyword:`with` statement.
Benjamin Petersone0124bd2009-03-09 21:04:33 +000070
Benjamin Peterson10745a92009-03-09 21:08:47 +000071 .. versionchanged:: 3.1
Benjamin Petersone0124bd2009-03-09 21:04:33 +000072 Support for the :keyword:`with` statement was added.
73
Antoine Pitrou8e33fd72010-01-13 14:37:26 +000074 .. versionchanged:: 3.2
75 Support for zero-padded files was added.
76
Georg Brandl116aa622007-08-15 14:28:22 +000077
Georg Brandl036490d2009-05-17 13:00:36 +000078.. function:: open(filename, mode='rb', compresslevel=9)
Georg Brandl116aa622007-08-15 14:28:22 +000079
80 This is a shorthand for ``GzipFile(filename,`` ``mode,`` ``compresslevel)``.
81 The *filename* argument is required; *mode* defaults to ``'rb'`` and
82 *compresslevel* defaults to ``9``.
83
Antoine Pitrou79c5ef12010-08-17 21:10:05 +000084.. function:: compress(data, compresslevel=9)
85
86 Compress the *data*, returning a :class:`bytes` object containing
87 the compressed data. *compresslevel* has the same meaning as in
88 the :class:`GzipFile` constructor above.
89
Antoine Pitroucdfe1c52010-08-17 21:15:00 +000090 .. versionadded:: 3.2
91
Antoine Pitrou79c5ef12010-08-17 21:10:05 +000092.. function:: decompress(data)
93
94 Decompress the *data*, returning a :class:`bytes` object containing the
95 uncompressed data.
96
Antoine Pitroucdfe1c52010-08-17 21:15:00 +000097 .. versionadded:: 3.2
98
Georg Brandl116aa622007-08-15 14:28:22 +000099
Christian Heimesbbe741d2008-03-28 10:53:29 +0000100.. _gzip-usage-examples:
101
102Examples of usage
103-----------------
104
105Example of how to read a compressed file::
106
107 import gzip
Antoine Pitroubf1a0182010-08-17 21:11:49 +0000108 with gzip.open('/home/joe/file.txt.gz', 'rb') as f:
109 file_content = f.read()
Christian Heimesbbe741d2008-03-28 10:53:29 +0000110
111Example of how to create a compressed GZIP file::
112
113 import gzip
Antoine Pitroubf1a0182010-08-17 21:11:49 +0000114 content = b"Lots of content here"
115 with gzip.open('/home/joe/file.txt.gz', 'wb') as f:
116 f.write(content)
Christian Heimesbbe741d2008-03-28 10:53:29 +0000117
118Example of how to GZIP compress an existing file::
119
120 import gzip
Antoine Pitroubf1a0182010-08-17 21:11:49 +0000121 with open('/home/joe/file.txt', 'rb') as f_in:
Éric Araujof5be0902010-08-17 21:24:05 +0000122 with gzip.open('/home/joe/file.txt.gz', 'wb') as f_out:
Antoine Pitroubf1a0182010-08-17 21:11:49 +0000123 f_out.writelines(f_in)
Christian Heimesbbe741d2008-03-28 10:53:29 +0000124
Antoine Pitrou79c5ef12010-08-17 21:10:05 +0000125Example of how to GZIP compress a binary string::
126
127 import gzip
128 s_in = b"Lots of content here"
129 s_out = gzip.compress(s_in)
Christian Heimesbbe741d2008-03-28 10:53:29 +0000130
Georg Brandl116aa622007-08-15 14:28:22 +0000131.. seealso::
132
133 Module :mod:`zlib`
134 The basic data compression module needed to support the :program:`gzip` file
135 format.
136