Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 | |
Raymond Hettinger | 469271d | 2011-01-27 20:38:46 +0000 | [diff] [blame] | 7 | **Source code:** :source:`Lib/gzip.py` |
| 8 | |
| 9 | -------------- |
| 10 | |
Christian Heimes | bbe741d | 2008-03-28 10:53:29 +0000 | [diff] [blame] | 11 | This module provides a simple interface to compress and decompress files just |
| 12 | like the GNU programs :program:`gzip` and :program:`gunzip` would. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 13 | |
Georg Brandl | 1f01deb | 2009-01-03 22:47:39 +0000 | [diff] [blame] | 14 | The data compression is provided by the :mod:`zlib` module. |
Christian Heimes | bbe741d | 2008-03-28 10:53:29 +0000 | [diff] [blame] | 15 | |
Antoine Pitrou | 11cb961 | 2010-09-15 11:11:28 +0000 | [diff] [blame] | 16 | The :mod:`gzip` module provides the :class:`GzipFile` class. The :class:`GzipFile` |
| 17 | class reads and writes :program:`gzip`\ -format files, automatically compressing |
| 18 | or decompressing the data so that it looks like an ordinary :term:`file object`. |
Christian Heimes | bbe741d | 2008-03-28 10:53:29 +0000 | [diff] [blame] | 19 | |
| 20 | Note that additional file formats which can be decompressed by the |
| 21 | :program:`gzip` and :program:`gunzip` programs, such as those produced by |
| 22 | :program:`compress` and :program:`pack`, are not supported by this module. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 23 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 24 | The module defines the following items: |
| 25 | |
| 26 | |
Georg Brandl | 036490d | 2009-05-17 13:00:36 +0000 | [diff] [blame] | 27 | .. class:: GzipFile(filename=None, mode=None, compresslevel=9, fileobj=None, mtime=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 28 | |
Antoine Pitrou | c3ed2e7 | 2010-09-29 10:49:46 +0000 | [diff] [blame] | 29 | Constructor for the :class:`GzipFile` class, which simulates most of the |
| 30 | methods of a :term:`file object`, with the exception of the :meth:`truncate` |
| 31 | method. At least one of *fileobj* and *filename* must be given a non-trivial |
| 32 | value. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 33 | |
| 34 | The new class instance is based on *fileobj*, which can be a regular file, a |
| 35 | :class:`StringIO` object, or any other object which simulates a file. It |
| 36 | defaults to ``None``, in which case *filename* is opened to provide a file |
| 37 | object. |
| 38 | |
| 39 | When *fileobj* is not ``None``, the *filename* argument is only used to be |
| 40 | included in the :program:`gzip` file header, which may includes the original |
| 41 | filename of the uncompressed file. It defaults to the filename of *fileobj*, if |
| 42 | discernible; otherwise, it defaults to the empty string, and in this case the |
| 43 | original filename is not included in the header. |
| 44 | |
| 45 | The *mode* argument can be any of ``'r'``, ``'rb'``, ``'a'``, ``'ab'``, ``'w'``, |
| 46 | or ``'wb'``, depending on whether the file will be read or written. The default |
Nadeem Vawda | 30d94b7 | 2012-02-11 23:45:10 +0200 | [diff] [blame^] | 47 | is the mode of *fileobj* if discernible; otherwise, the default is ``'rb'``. |
| 48 | |
| 49 | Note that the file is always opened in binary mode; text mode is not |
| 50 | supported. If you need to read a compressed file in text mode, wrap your |
| 51 | :class:`GzipFile` with an :class:`io.TextIOWrapper`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 52 | |
| 53 | The *compresslevel* argument is an integer from ``1`` to ``9`` controlling the |
| 54 | level of compression; ``1`` is fastest and produces the least compression, and |
| 55 | ``9`` is slowest and produces the most compression. The default is ``9``. |
| 56 | |
Antoine Pitrou | 42db3ef | 2009-01-04 21:37:59 +0000 | [diff] [blame] | 57 | The *mtime* argument is an optional numeric timestamp to be written to |
Benjamin Peterson | e0124bd | 2009-03-09 21:04:33 +0000 | [diff] [blame] | 58 | the stream when compressing. All :program:`gzip` compressed streams are |
Antoine Pitrou | 42db3ef | 2009-01-04 21:37:59 +0000 | [diff] [blame] | 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 |
Senthil Kumaran | a6bac95 | 2011-07-04 11:28:30 -0700 | [diff] [blame] | 63 | ``time.time()`` and of the ``st_mtime`` attribute of the object returned |
Antoine Pitrou | 42db3ef | 2009-01-04 21:37:59 +0000 | [diff] [blame] | 64 | by ``os.stat()``. |
| 65 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 |
Antoine Pitrou | e5768cf | 2010-09-23 16:45:17 +0000 | [diff] [blame] | 68 | data. This also allows you to pass a :class:`io.BytesIO` object opened for |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 69 | writing as *fileobj*, and retrieve the resulting memory buffer using the |
Antoine Pitrou | e5768cf | 2010-09-23 16:45:17 +0000 | [diff] [blame] | 70 | :class:`io.BytesIO` object's :meth:`~io.BytesIO.getvalue` method. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 71 | |
Antoine Pitrou | c3ed2e7 | 2010-09-29 10:49:46 +0000 | [diff] [blame] | 72 | :class:`GzipFile` supports the :class:`io.BufferedIOBase` interface, |
| 73 | including iteration and the :keyword:`with` statement. Only the |
Antoine Pitrou | e886047 | 2011-04-04 21:06:20 +0200 | [diff] [blame] | 74 | :meth:`read1` and :meth:`truncate` methods aren't implemented. |
Benjamin Peterson | e0124bd | 2009-03-09 21:04:33 +0000 | [diff] [blame] | 75 | |
Antoine Pitrou | 7b998e9 | 2010-10-04 21:55:14 +0000 | [diff] [blame] | 76 | :class:`GzipFile` also provides the following method: |
| 77 | |
| 78 | .. method:: peek([n]) |
| 79 | |
| 80 | Read *n* uncompressed bytes without advancing the file position. |
| 81 | At most one single read on the compressed stream is done to satisfy |
| 82 | the call. The number of bytes returned may be more or less than |
| 83 | requested. |
| 84 | |
| 85 | .. versionadded:: 3.2 |
| 86 | |
Benjamin Peterson | 10745a9 | 2009-03-09 21:08:47 +0000 | [diff] [blame] | 87 | .. versionchanged:: 3.1 |
Benjamin Peterson | e0124bd | 2009-03-09 21:04:33 +0000 | [diff] [blame] | 88 | Support for the :keyword:`with` statement was added. |
| 89 | |
Antoine Pitrou | 8e33fd7 | 2010-01-13 14:37:26 +0000 | [diff] [blame] | 90 | .. versionchanged:: 3.2 |
| 91 | Support for zero-padded files was added. |
| 92 | |
Antoine Pitrou | 7b96984 | 2010-09-23 16:22:51 +0000 | [diff] [blame] | 93 | .. versionchanged:: 3.2 |
| 94 | Support for unseekable files was added. |
| 95 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 96 | |
Georg Brandl | 036490d | 2009-05-17 13:00:36 +0000 | [diff] [blame] | 97 | .. function:: open(filename, mode='rb', compresslevel=9) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 98 | |
| 99 | This is a shorthand for ``GzipFile(filename,`` ``mode,`` ``compresslevel)``. |
| 100 | The *filename* argument is required; *mode* defaults to ``'rb'`` and |
| 101 | *compresslevel* defaults to ``9``. |
| 102 | |
Antoine Pitrou | 79c5ef1 | 2010-08-17 21:10:05 +0000 | [diff] [blame] | 103 | .. function:: compress(data, compresslevel=9) |
| 104 | |
| 105 | Compress the *data*, returning a :class:`bytes` object containing |
| 106 | the compressed data. *compresslevel* has the same meaning as in |
| 107 | the :class:`GzipFile` constructor above. |
| 108 | |
Antoine Pitrou | cdfe1c5 | 2010-08-17 21:15:00 +0000 | [diff] [blame] | 109 | .. versionadded:: 3.2 |
| 110 | |
Antoine Pitrou | 79c5ef1 | 2010-08-17 21:10:05 +0000 | [diff] [blame] | 111 | .. function:: decompress(data) |
| 112 | |
| 113 | Decompress the *data*, returning a :class:`bytes` object containing the |
| 114 | uncompressed data. |
| 115 | |
Antoine Pitrou | cdfe1c5 | 2010-08-17 21:15:00 +0000 | [diff] [blame] | 116 | .. versionadded:: 3.2 |
| 117 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 118 | |
Christian Heimes | bbe741d | 2008-03-28 10:53:29 +0000 | [diff] [blame] | 119 | .. _gzip-usage-examples: |
| 120 | |
| 121 | Examples of usage |
| 122 | ----------------- |
| 123 | |
| 124 | Example of how to read a compressed file:: |
| 125 | |
| 126 | import gzip |
Antoine Pitrou | bf1a018 | 2010-08-17 21:11:49 +0000 | [diff] [blame] | 127 | with gzip.open('/home/joe/file.txt.gz', 'rb') as f: |
| 128 | file_content = f.read() |
Christian Heimes | bbe741d | 2008-03-28 10:53:29 +0000 | [diff] [blame] | 129 | |
| 130 | Example of how to create a compressed GZIP file:: |
| 131 | |
| 132 | import gzip |
Antoine Pitrou | bf1a018 | 2010-08-17 21:11:49 +0000 | [diff] [blame] | 133 | content = b"Lots of content here" |
| 134 | with gzip.open('/home/joe/file.txt.gz', 'wb') as f: |
| 135 | f.write(content) |
Christian Heimes | bbe741d | 2008-03-28 10:53:29 +0000 | [diff] [blame] | 136 | |
| 137 | Example of how to GZIP compress an existing file:: |
| 138 | |
| 139 | import gzip |
Antoine Pitrou | bf1a018 | 2010-08-17 21:11:49 +0000 | [diff] [blame] | 140 | with open('/home/joe/file.txt', 'rb') as f_in: |
Éric Araujo | f5be090 | 2010-08-17 21:24:05 +0000 | [diff] [blame] | 141 | with gzip.open('/home/joe/file.txt.gz', 'wb') as f_out: |
Antoine Pitrou | bf1a018 | 2010-08-17 21:11:49 +0000 | [diff] [blame] | 142 | f_out.writelines(f_in) |
Christian Heimes | bbe741d | 2008-03-28 10:53:29 +0000 | [diff] [blame] | 143 | |
Antoine Pitrou | 79c5ef1 | 2010-08-17 21:10:05 +0000 | [diff] [blame] | 144 | Example of how to GZIP compress a binary string:: |
| 145 | |
| 146 | import gzip |
| 147 | s_in = b"Lots of content here" |
| 148 | s_out = gzip.compress(s_in) |
Christian Heimes | bbe741d | 2008-03-28 10:53:29 +0000 | [diff] [blame] | 149 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 150 | .. seealso:: |
| 151 | |
| 152 | Module :mod:`zlib` |
| 153 | The basic data compression module needed to support the :program:`gzip` file |
| 154 | format. |
| 155 | |