mirror of https://github.com/python/cpython.git
170 lines
6.1 KiB
TeX
170 lines
6.1 KiB
TeX
\section{\module{zipfile} ---
|
|
Work with ZIP archives}
|
|
|
|
\modulesynopsis{Read and write ZIP-format archive files.}
|
|
\moduleauthor{James C. Ahlstrom}{jim@interet.com}
|
|
\sectionauthor{James C. Ahlstrom}{jim@interet.com}
|
|
% LaTeX markup by Fred L. Drake, Jr. <fdrake@acm.org>
|
|
|
|
The ZIP file format is a common archive and compression standard.
|
|
This module provides tools to create, read, write, append, and list a
|
|
ZIP file.
|
|
|
|
The available attributes of this module are:
|
|
|
|
\begin{excdesc}{error}
|
|
The error raised for bad ZIP files.
|
|
\end{excdesc}
|
|
|
|
\begin{datadesc}{_debug}
|
|
Level of printing, defaults to \code{1}.
|
|
\end{datadesc}
|
|
|
|
\begin{classdesc}{ZipFile}{...}
|
|
The class for reading and writing ZIP files. See
|
|
``\citetitle{ZipFile Objects}'' (section \ref{zipfile-objects}) for
|
|
constructor details.
|
|
\end{classdesc}
|
|
|
|
\begin{funcdesc}{is_zipfile}{path}
|
|
Returns true if \var{path} is a valid ZIP file based on its magic
|
|
number, otherwise returns false. This module does not currently
|
|
handle ZIP files which have appended comments.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{zip2date}{zdate}
|
|
Return \code{(\var{year}, \var{month}, \var{day})} for a ZIP date
|
|
code.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{zip2time}{ztime}
|
|
Return \code{(\var{hour}, \var{minute}, \var{second})} for a ZIP
|
|
time code.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{date2zip}{year, month, day}
|
|
Return a ZIP date code.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{time2zip}{hour, minute, second}
|
|
Return a ZIP time code.
|
|
\end{funcdesc}
|
|
|
|
\begin{datadesc}{ZIP_STORED}
|
|
The numeric constant (\code{0}) for an uncompressed archive member.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{ZIP_DEFLATED}
|
|
The numeric constant for the usual ZIP compression method. This
|
|
requires the zlib module. No other compression methods are
|
|
currently supported.
|
|
\end{datadesc}
|
|
|
|
|
|
\begin{seealso}
|
|
\seetext{XXX point to ZIP format definition}
|
|
\seetext{XXX point to Info-ZIP home page; mention WiZ}
|
|
\end{seealso}
|
|
|
|
|
|
\subsection{ZipFile Objects \label{zipfile-objects}}
|
|
|
|
\begin{classdesc}{ZipFile}{filename\optional{, mode\optional{, compression}}}
|
|
Open a ZIP file named \var{filename}. The \var{mode} parameter
|
|
should be \code{'r'} to read an existing file, \code{'w'} to
|
|
truncate and write a new file, or \code{'a'} to append to an
|
|
existing file. For \var{mode} is \code{'a'} and \var{filename}
|
|
refers to an existing ZIP file, then additional files are added to
|
|
it. If \var{filename} does not refer to a ZIP file, then a new ZIP
|
|
archive is appended to the file. This is meant for adding a ZIP
|
|
archive to another file, such as \file{python.exe}. Using
|
|
\begin{verbatim}
|
|
cat myzip.zip >> python.exe
|
|
\end{verbatim}
|
|
also works, and at least \program{WinZip} can read such files.
|
|
\var{compression} is the ZIP compression method to use when writing
|
|
the archive, and should be \constant{ZIP_STORED} or
|
|
\constant{ZIP_DEFLATED}; unrecognized values will cause
|
|
\exception{ValueError} to be raised. The default is
|
|
\constant{ZIP_STORED}.
|
|
\end{classdesc}
|
|
|
|
XXX explain the "extra" string for the ZIP format
|
|
|
|
\begin{memberdesc}{TOC}
|
|
A read-only dictionary whose keys are the names in the archive, and
|
|
whose values are tuples as follows:
|
|
|
|
\begin{tableii}{c|l}{code}{Index}{Meaning}
|
|
\lineii{0}{File data seek offset}
|
|
\lineii{1}{ZIP file "extra" data as a string}
|
|
\lineii{2}{ZIP file bit flags}
|
|
\lineii{3}{ZIP file compression type}
|
|
\lineii{4}{File modification time in DOS format}
|
|
\lineii{5}{File modification date in DOS format}
|
|
\lineii{6}{The CRC-32 of the uncompressed data}
|
|
\lineii{7}{The compressed size of the file}
|
|
\lineii{8}{The uncompressed size of the file}
|
|
\end{tableii}
|
|
\end{memberdesc}
|
|
|
|
The class ZipFile has these methods:
|
|
|
|
\begin{methoddesc}{listdir}{}
|
|
Return a list of names in the archive. Equivalent to
|
|
\code{\var{zipfile}.TOC.keys()}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{printdir}{}
|
|
Print a table of contents for the archive to stdout.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{read}{name}
|
|
Return the bytes of the file in the archive. The archive must be
|
|
open for read or append.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{writestr}{bytes, arcname, year, month, day, hour,
|
|
minute, second\optional{, extra}}
|
|
Write the string \var{bytes} and the other data to the archive, and
|
|
give the archive member the name \var{arcname}. \var{extra} is the
|
|
ZIP extra data string. The archive must be opened with mode
|
|
\code{'w'} or \code{'a'}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{write}{filename, arcname\optional{, extra}}
|
|
Write the file named \var{filename} to the archive, giving it the
|
|
archive name \var{arcname}. \var{extra} is the ZIP extra data
|
|
string. The archive must be open with mode \code{'w'} or
|
|
\code{'a'}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{writepy}{pathname\optional{, basename}}
|
|
Search for files \file{*.py} and add the corresponding file to the
|
|
archive. The corresponding file is a \file{*.pyo} file if
|
|
available, else a \file{*.pyc} file, compiling if necessary. If the
|
|
pathname is a file, the filename must end with \file{.py}, and just
|
|
the (corresponding \file{*.py[oc]}) file is added at the top level
|
|
(no path information). If it is a directory, and the directory is
|
|
not a package directory, then all the files \file{*.py[oc]} are
|
|
added at the top level. If the directory is a package directory,
|
|
then all \file{*.py[oc]} are added under the package name as a file
|
|
path, and if any subdirectories are package directories, all of
|
|
these are added recursively. \var{basename} is intended for
|
|
internal use only. The \method{writepy()} method makes archives
|
|
with file names like this:
|
|
|
|
\begin{verbatim}
|
|
string.pyc # Top level name
|
|
test/__init__.pyc # Package directory
|
|
test/testall.pyc # Module test.testall
|
|
test/bogus/__init__.pyc # Subpackage directory
|
|
test/bogus/myfile.pyc # Submodule test.bogus.myfile
|
|
\end{verbatim}
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{close}{}
|
|
Close the archive file. You must call \method{close()} before
|
|
exiting your program or essential records will not be written.
|
|
\end{methoddesc}
|