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]]]])

    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    Calling a :class:`GzipFile` object's :meth:`close` method does not close

    56    *fileobj*, since you might wish to append more material after the compressed

    57    data.  This also allows you to pass a :class:`StringIO` object opened for

    58    writing as *fileobj*, and retrieve the resulting memory buffer using the

    59    :class:`StringIO` object's :meth:`getvalue` method.

    60 

    61 

    62 .. function:: open(filename[, mode[, compresslevel]])

    63 

    64    This is a shorthand for ``GzipFile(filename,`` ``mode,`` ``compresslevel)``.

    65    The *filename* argument is required; *mode* defaults to ``'rb'`` and

    66    *compresslevel* defaults to ``9``.

    67 

    68 

    69 .. _gzip-usage-examples:

    70 

    71 Examples of usage

    72 -----------------

    73 

    74 Example of how to read a compressed file::

    75 

    76    import gzip

    77    f = gzip.open('/home/joe/file.txt.gz', 'rb')

    78    file_content = f.read()

    79    f.close()

    80 

    81 Example of how to create a compressed GZIP file::

    82 

    83    import gzip

    84    content = "Lots of content here"

    85    f = gzip.open('/home/joe/file.txt.gz', 'wb')

    86    f.write(content)

    87    f.close()

    88 

    89 Example of how to GZIP compress an existing file::

    90 

    91    import gzip

    92    f_in = open('/home/joe/file.txt', 'rb')

    93    f_out = gzip.open('/home/joe/file.txt.gz', 'wb')

    94    f_out.writelines(f_in)

    95    f_out.close()

    96    f_in.close()

    97 

    98 

    99 .. seealso::

   100 

   101    Module :mod:`zlib`

   102       The basic data compression module needed to support the :program:`gzip` file

   103       format.

   104