Doc/lib/libgzip.tex

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