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