71 lines
3.3 KiB
TeX
71 lines
3.3 KiB
TeX
\section{\module{gzip} ---
|
|
Support for \program{gzip} files}
|
|
|
|
\declaremodule{standard}{gzip}
|
|
\modulesynopsis{Interfaces for \program{gzip} compression and
|
|
decompression using file objects.}
|
|
|
|
|
|
The data compression provided by the \code{zlib} module is compatible
|
|
with that used by the GNU compression program \program{gzip}.
|
|
Accordingly, the \module{gzip} module provides the \class{GzipFile}
|
|
class to read and write \program{gzip}-format files, automatically
|
|
compressing or decompressing the data so it looks like an ordinary
|
|
file object. Note that additional file formats which can be
|
|
decompressed by the \program{gzip} and \program{gunzip} programs, such
|
|
as those produced by \program{compress} and \program{pack}, are not
|
|
supported by this module.
|
|
|
|
The module defines the following items:
|
|
|
|
\begin{classdesc}{GzipFile}{\optional{filename\optional{, mode\optional{,
|
|
compresslevel\optional{, fileobj}}}}}
|
|
Constructor for the \class{GzipFile} class, which simulates most of
|
|
the methods of a file object, with the exception of the \method{readinto()},
|
|
\method{truncate()}, and \method{xreadlines()} methods. At least one of
|
|
\var{fileobj} and \var{filename} must be given a non-trivial value.
|
|
|
|
The new class instance is based on \var{fileobj}, which can be a
|
|
regular file, a \class{StringIO} object, or any other object which
|
|
simulates a file. It defaults to \code{None}, in which case
|
|
\var{filename} is opened to provide a file object.
|
|
|
|
When \var{fileobj} is not \code{None}, the \var{filename} argument is
|
|
only used to be included in the \program{gzip} file header, which may
|
|
includes the original filename of the uncompressed file. It defaults
|
|
to the filename of \var{fileobj}, if discernible; otherwise, it
|
|
defaults to the empty string, and in this case the original filename
|
|
is not included in the header.
|
|
|
|
The \var{mode} argument can be any of \code{'r'}, \code{'rb'},
|
|
\code{'a'}, \code{'ab'}, \code{'w'}, or \code{'wb'}, depending on
|
|
whether the file will be read or written. The default is the mode of
|
|
\var{fileobj} if discernible; otherwise, the default is \code{'rb'}.
|
|
If not given, the 'b' flag will be added to the mode to ensure the
|
|
file is opened in binary mode for cross-platform portability.
|
|
|
|
The \var{compresslevel} argument is an integer from \code{1} to
|
|
\code{9} controlling the level of compression; \code{1} is fastest and
|
|
produces the least compression, and \code{9} is slowest and produces
|
|
the most compression. The default is \code{9}.
|
|
|
|
Calling a \class{GzipFile} object's \method{close()} method does not
|
|
close \var{fileobj}, since you might wish to append more material
|
|
after the compressed data. This also allows you to pass a
|
|
\class{StringIO} object opened for writing as \var{fileobj}, and
|
|
retrieve the resulting memory buffer using the \class{StringIO}
|
|
object's \method{getvalue()} method.
|
|
\end{classdesc}
|
|
|
|
\begin{funcdesc}{open}{filename\optional{, mode\optional{, compresslevel}}}
|
|
This is a shorthand for \code{GzipFile(\var{filename},}
|
|
\code{\var{mode},} \code{\var{compresslevel})}. The \var{filename}
|
|
argument is required; \var{mode} defaults to \code{'rb'} and
|
|
\var{compresslevel} defaults to \code{9}.
|
|
\end{funcdesc}
|
|
|
|
\begin{seealso}
|
|
\seemodule{zlib}{The basic data compression module needed to support
|
|
the \program{gzip} file format.}
|
|
\end{seealso}
|