Debian Codegraph @

Doc/library/gzip.rst

raw
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
11 This module provides a simple interface to compress and decompress files just
12 like the GNU programs :program:`gzip` and :program:`gunzip` would.
13
14 The data compression is provided by the :mod:`zlib` module.
15
16 The :mod:`gzip` module provides the :class:`GzipFile` class, as well as the
17 :func:`.open`, :func:`compress` and :func:`decompress` convenience functions.
18 The :class:`GzipFile` class reads and writes :program:`gzip`\ -format files,
19 automatically compressing or decompressing the data so that it looks like an
20 ordinary :term:`file object`.
21
22 Note 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
26 The 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 The number of bytes returned may be more or less than requested.
126
127 .. note:: While calling :meth:`peek` does not change the file position of
128 the :class:`GzipFile`, it may change the position of the underlying
129 file object (e.g. if the :class:`GzipFile` was constructed with the
130 *fileobj* parameter).
131
132 .. versionadded:: 3.2
133
134 .. attribute:: mode
135
136 ``'rb'`` for reading and ``'wb'`` for writing.
137
138 .. versionchanged:: 3.13
139 In previous versions it was an integer ``1`` or ``2``.
140
141 .. attribute:: mtime
142
143 When decompressing, this attribute is set to the last timestamp in the most
144 recently read header. It is an integer, holding the number of seconds
145 since the Unix epoch (00:00:00 UTC, January 1, 1970).
146 The initial value before reading any headers is ``None``.
147
148 .. attribute:: name
149
150 The path to the gzip file on disk, as a :class:`str` or :class:`bytes`.
151 Equivalent to the output of :func:`os.fspath` on the original input path,
152 with no other normalization, resolution or expansion.
153
154 .. versionchanged:: 3.1
155 Support for the :keyword:`with` statement was added, along with the
156 *mtime* constructor argument and :attr:`mtime` attribute.
157
158 .. versionchanged:: 3.2
159 Support for zero-padded and unseekable files was added.
160
161 .. versionchanged:: 3.3
162 The :meth:`io.BufferedIOBase.read1` method is now implemented.
163
164 .. versionchanged:: 3.4
165 Added support for the ``'x'`` and ``'xb'`` modes.
166
167 .. versionchanged:: 3.5
168 Added support for writing arbitrary
169 :term:`bytes-like objects <bytes-like object>`.
170 The :meth:`~io.BufferedIOBase.read` method now accepts an argument of
171 ``None``.
172
173 .. versionchanged:: 3.6
174 Accepts a :term:`path-like object`.
175
176 .. deprecated:: 3.9
177 Opening :class:`GzipFile` for writing without specifying the *mode*
178 argument is deprecated.
179
180 .. versionchanged:: 3.12
181 Remove the ``filename`` attribute, use the :attr:`~GzipFile.name`
182 attribute instead.
183
184
185 .. function:: compress(data, compresslevel=9, *, mtime=None)
186
187 Compress the *data*, returning a :class:`bytes` object containing
188 the compressed data. *compresslevel* and *mtime* have the same meaning as in
189 the :class:`GzipFile` constructor above.
190
191 .. versionadded:: 3.2
192 .. versionchanged:: 3.8
193 Added the *mtime* parameter for reproducible output.
194 .. versionchanged:: 3.11
195 Speed is improved by compressing all data at once instead of in a
196 streamed fashion. Calls with *mtime* set to ``0`` are delegated to
197 :func:`zlib.compress` for better speed. In this situation the
198 output may contain a gzip header "OS" byte value other than 255
199 "unknown" as supplied by the underlying zlib implementation.
200
201 .. versionchanged:: 3.13
202 The gzip header OS byte is guaranteed to be set to 255 when this function
203 is used as was the case in 3.10 and earlier.
204
205 .. function:: decompress(data)
206
207 Decompress the *data*, returning a :class:`bytes` object containing the
208 uncompressed data. This function is capable of decompressing multi-member
209 gzip data (multiple gzip blocks concatenated together). When the data is
210 certain to contain only one member the :func:`zlib.decompress` function with
211 *wbits* set to 31 is faster.
212
213 .. versionadded:: 3.2
214 .. versionchanged:: 3.11
215 Speed is improved by decompressing members at once in memory instead of in
216 a streamed fashion.
217
218 .. _gzip-usage-examples:
219
220 Examples of usage
221 -----------------
222
223 Example of how to read a compressed file::
224
225 import gzip
226 with gzip.open('/home/joe/file.txt.gz', 'rb') as f:
227 file_content = f.read()
228
229 Example of how to create a compressed GZIP file::
230
231 import gzip
232 content = b"Lots of content here"
233 with gzip.open('/home/joe/file.txt.gz', 'wb') as f:
234 f.write(content)
235
236 Example of how to GZIP compress an existing file::
237
238 import gzip
239 import shutil
240 with open('/home/joe/file.txt', 'rb') as f_in:
241 with gzip.open('/home/joe/file.txt.gz', 'wb') as f_out:
242 shutil.copyfileobj(f_in, f_out)
243
244 Example of how to GZIP compress a binary string::
245
246 import gzip
247 s_in = b"Lots of content here"
248 s_out = gzip.compress(s_in)
249
250 .. seealso::
251
252 Module :mod:`zlib`
253 The basic data compression module needed to support the :program:`gzip` file
254 format.
255
256 In case gzip (de)compression is a bottleneck, the `python-isal`_
257 package speeds up (de)compression with a mostly compatible API.
258
259 .. _python-isal: https://github.com/pycompression/python-isal
260
261 .. program:: gzip
262
263 .. _gzip-cli:
264
265 Command-line interface
266 ----------------------
267
268 The :mod:`gzip` module provides a simple command line interface to compress or
269 decompress files.
270
271 Once executed the :mod:`gzip` module keeps the input file(s).
272
273 .. versionchanged:: 3.8
274
275 Add a new command line interface with a usage.
276 By default, when you will execute the CLI, the default compression level is 6.
277
278 Command-line options
279 ^^^^^^^^^^^^^^^^^^^^
280
281 .. option:: file
282
283 If *file* is not specified, read from :data:`sys.stdin`.
284
285 .. option:: --fast
286
287 Indicates the fastest compression method (less compression).
288
289 .. option:: --best
290
291 Indicates the slowest compression method (best compression).
292
293 .. option:: -d, --decompress
294
295 Decompress the given file.
296
297 .. option:: -h, --help
298
299 Show the help message.