mirror of
https://github.com/python/cpython.git
synced 2024-11-26 03:14:27 +08:00
ba0a989988
letter and end with proper punctuation. "Documenting Python" will be updated accordingly so that this will be editorial policy for the Python documentation.
71 lines
3.2 KiB
TeX
71 lines
3.2 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{seek()} and \method{tell()} 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'}.
|
|
Be aware that only the \code{'rb'}, \code{'ab'}, and \code{'wb'}
|
|
values should be used 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}
|