Doc/library/gzip.rst

   1
   2 :mod:`gzip` --- Support for :program:`gzip` files
   3 =================================================
   4
   5 .. module:: gzip
   6    :synopsis: Interfaces for gzip compression and decompression using file objects.
   7
   8
   9 The data compression provided by the ``zlib`` module is compatible with that
  10 used by the GNU compression program :program:`gzip`. Accordingly, the
  11 :mod:`gzip` module provides the :class:`GzipFile` class to read and write
  12 :program:`gzip`\ -format files, automatically compressing or decompressing the
  13 data so it looks like an ordinary file object.  Note that additional file
  14 formats which can be decompressed by the :program:`gzip` and :program:`gunzip`
  15 programs, such  as those produced by :program:`compress` and :program:`pack`,
  16 are not supported by this module.
  17
  18 For other archive formats, see the :mod:`bz2`, :mod:`zipfile`, and
  19 :mod:`tarfile` modules.
  20
  21 The module defines the following items:
  22
  23
  24 .. class:: GzipFile([filename[, mode[, compresslevel[, fileobj]]]])
  25
  26    Constructor for the :class:`GzipFile` class, which simulates most of the methods
  27    of a file object, with the exception of the :meth:`readinto` and
  28    :meth:`truncate` methods.  At least one of *fileobj* and *filename* must be
  29    given a non-trivial value.
  30
  31    The new class instance is based on *fileobj*, which can be a regular file, a
  32    :class:`StringIO` object, or any other object which simulates a file.  It
  33    defaults to ``None``, in which case *filename* is opened to provide a file
  34    object.
  35
  36    When *fileobj* is not ``None``, the *filename* argument is only used to be
  37    included in the :program:`gzip` file header, which may includes the original
  38    filename of the uncompressed file.  It defaults to the filename of *fileobj*, if
  39    discernible; otherwise, it defaults to the empty string, and in this case the
  40    original filename is not included in the header.
  41
  42    The *mode* argument can be any of ``'r'``, ``'rb'``, ``'a'``, ``'ab'``, ``'w'``,
  43    or ``'wb'``, depending on whether the file will be read or written.  The default
  44    is the mode of *fileobj* if discernible; otherwise, the default is ``'rb'``. If
  45    not given, the 'b' flag will be added to the mode to ensure the file is opened
  46    in binary mode for cross-platform portability.
  47
  48    The *compresslevel* argument is an integer from ``1`` to ``9`` controlling the
  49    level of compression; ``1`` is fastest and produces the least compression, and
  50    ``9`` is slowest and produces the most compression.  The default is ``9``.
  51
  52    Calling a :class:`GzipFile` object's :meth:`close` method does not close
  53    *fileobj*, since you might wish to append more material after the compressed
  54    data.  This also allows you to pass a :class:`StringIO` object opened for
  55    writing as *fileobj*, and retrieve the resulting memory buffer using the
  56    :class:`StringIO` object's :meth:`getvalue` method.
  57
  58
  59 .. function:: open(filename[, mode[, compresslevel]])
  60
  61    This is a shorthand for ``GzipFile(filename,`` ``mode,`` ``compresslevel)``.
  62    The *filename* argument is required; *mode* defaults to ``'rb'`` and
  63    *compresslevel* defaults to ``9``.
  64
  65
  66 .. seealso::
  67
  68    Module :mod:`zlib`
  69       The basic data compression module needed to support the :program:`gzip` file
  70       format.
  71