Doc/library/gzip.rst

   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 This module provides a simple interface to compress and decompress files just
   8 like the GNU programs :program:`gzip` and :program:`gunzip` would.
   9
  10 The data compression is provided by the :mod:`zlib` module.
  11
  12 The :mod:`gzip` module provides the :class:`GzipFile` class which is modeled
  13 after Python's File Object. The :class:`GzipFile` class reads and writes
  14 :program:`gzip`\ -format files, automatically compressing or decompressing the
  15 data so that it looks like an ordinary file object.
  16
  17 Note that additional file formats which can be decompressed by the
  18 :program:`gzip` and :program:`gunzip` programs, such  as those produced by
  19 :program:`compress` and :program:`pack`, are not supported by this module.
  20
  21 For other archive formats, see the :mod:`bz2`, :mod:`zipfile`, and
  22 :mod:`tarfile` modules.
  23
  24 The module defines the following items:
  25
  26
  27 .. class:: GzipFile([filename[, mode[, compresslevel[, fileobj[, mtime]]]]])
  28
  29    Constructor for the :class:`GzipFile` class, which simulates most of the methods
  30    of a file object, with the exception of the :meth:`readinto` and
  31    :meth:`truncate` methods.  At least one of *fileobj* and *filename* must be
  32    given a non-trivial value.
  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
  47    is the mode of *fileobj* if discernible; otherwise, the default is ``'rb'``. If
  48    not given, the 'b' flag will be added to the mode to ensure the file is opened
  49    in binary mode for cross-platform portability.
  50
  51    The *compresslevel* argument is an integer from ``1`` to ``9`` controlling the
  52    level of compression; ``1`` is fastest and produces the least compression, and
  53    ``9`` is slowest and produces the most compression.  The default is ``9``.
  54
  55    The *mtime* argument is an optional numeric timestamp to be written to
  56    the stream when compressing.  All :program:`gzip` compressed streams are
  57    required to contain a timestamp.  If omitted or ``None``, the current
  58    time is used.  This module ignores the timestamp when decompressing;
  59    however, some programs, such as :program:`gunzip`\ , make use of it.
  60    The format of the timestamp is the same as that of the return value of
  61    ``time.time()`` and of the ``st_mtime`` member of the object returned
  62    by ``os.stat()``.
  63
  64    Calling a :class:`GzipFile` object's :meth:`close` method does not close
  65    *fileobj*, since you might wish to append more material after the compressed
  66    data.  This also allows you to pass a :class:`StringIO` object opened for
  67    writing as *fileobj*, and retrieve the resulting memory buffer using the
  68    :class:`StringIO` object's :meth:`getvalue` method.
  69
  70    :class:`GzipFile` supports the :keyword:`with` statement.
  71
  72    .. versionchanged:: 2.7
  73       Support for the :keyword:`with` statement was added.
  74
  75
  76 .. function:: open(filename[, mode[, compresslevel]])
  77
  78    This is a shorthand for ``GzipFile(filename,`` ``mode,`` ``compresslevel)``.
  79    The *filename* argument is required; *mode* defaults to ``'rb'`` and
  80    *compresslevel* defaults to ``9``.
  81
  82
  83 .. _gzip-usage-examples:
  84
  85 Examples of usage
  86 -----------------
  87
  88 Example of how to read a compressed file::
  89
  90    import gzip
  91    f = gzip.open('/home/joe/file.txt.gz', 'rb')
  92    file_content = f.read()
  93    f.close()
  94
  95 Example of how to create a compressed GZIP file::
  96
  97    import gzip
  98    content = "Lots of content here"
  99    f = gzip.open('/home/joe/file.txt.gz', 'wb')
 100    f.write(content)
 101    f.close()
 102
 103 Example of how to GZIP compress an existing file::
 104
 105    import gzip
 106    f_in = open('/home/joe/file.txt', 'rb')
 107    f_out = gzip.open('/home/joe/file.txt.gz', 'wb')
 108    f_out.writelines(f_in)
 109    f_out.close()
 110    f_in.close()
 111
 112
 113 .. seealso::
 114
 115    Module :mod:`zlib`
 116       The basic data compression module needed to support the :program:`gzip` file
 117       format.
 118