| \section{\module{zipfile} --- |
| Work with ZIP archives} |
| |
| \declaremodule{standard}{zipfile} |
| \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> |
| |
| \versionadded{1.6} |
| |
| 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} |
| \seetitle[http://www.pkware.com/appnote.html]{PKZIP Application |
| Note}{Documentation on the ZIP file format by Phil |
| Katz, the creator of the format and algorithms used.} |
| |
| \seetitle[http://www.info-zip.org/pub/infozip/]{Info-ZIP Home Page}{ |
| Information about the Info-ZIP project's ZIP archive |
| programs and development libraries.} |
| \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} |