PageRenderTime 408ms CodeModel.GetById 196ms app.highlight 4ms RepoModel.GetById 206ms app.codeStats 0ms

/Doc/library/gzip.rst

http://unladen-swallow.googlecode.com/
ReStructuredText | 104 lines | 73 code | 31 blank | 0 comment | 0 complexity | ac0ecb8ddbf8a7f6317207579e045f32 MD5 | raw file
  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
  7This module provides a simple interface to compress and decompress files just
  8like the GNU programs :program:`gzip` and :program:`gunzip` would.
  9
 10The data compression is provided by the :mod:`zlib` module.
 11
 12The :mod:`gzip` module provides the :class:`GzipFile` class which is modeled
 13after Python's File Object. The :class:`GzipFile` class reads and writes
 14:program:`gzip`\ -format files, automatically compressing or decompressing the
 15data so that it looks like an ordinary file object.
 16
 17Note 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
 21For other archive formats, see the :mod:`bz2`, :mod:`zipfile`, and
 22:mod:`tarfile` modules.
 23
 24The 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
 71Examples of usage
 72-----------------
 73
 74Example 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
 81Example 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
 89Example 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