| \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. Any advanced use of this module will require an |
| understanding of the format, as defined in |
| \citetitle[http://www.pkware.com/appnote.html]{PKZIP Application |
| Note}. |
| |
| This module does not currently handle ZIP files which have appended |
| comments, or multi-disk ZIP files. |
| |
| The available attributes of this module are: |
| |
| \begin{excdesc}{error} |
| The error raised for bad ZIP files. |
| \end{excdesc} |
| |
| \begin{classdesc}{ZipFile}{\unspecified} |
| The class for reading and writing ZIP files. See |
| ``\citetitle{ZipFile Objects}'' (section \ref{zipfile-objects}) for |
| constructor details. |
| \end{classdesc} |
| |
| \begin{classdesc}{PyZipFile}{\unspecified} |
| Class for creating ZIP archives containing Python libraries. |
| \end{classdesc} |
| |
| \begin{classdesc}{ZipInfo}{\optional{filename\optional{, date_time}}} |
| Class used the represent infomation about a member of an archive. |
| Instances of this class are returned by the \method{getinfo()} and |
| \method{infolist()} methods of \class{ZipFile} objects. Most users |
| of the \module{zipfile} module will not need to create these, but |
| only use those created by this module. |
| \var{filename} should be the full name of the archive member, and |
| \var{date_time} should be a tuple containing six fields which |
| describe the time of the last modification to the file; the fields |
| are described in section \ref{zipinfo-objects}, ``ZipInfo Objects.'' |
| \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{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{RuntimeError} to be raised. If \constant{ZIP_DEFLATED} |
| is specified but the \refmodule{zlib} module is not avaialble, |
| \exception{RuntimeError} is also raised. The default is |
| \constant{ZIP_STORED}. |
| \end{classdesc} |
| |
| \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} |
| |
| \begin{methoddesc}{getinfo}{name} |
| Return a \class{ZipInfo} object with information about the archive |
| member \var{name}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{namelist}{} |
| Return a list of archive members by name. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{infolist}{} |
| Return a list containing a \class{ZipInfo} object for each member of |
| the archive. The objects are in the same order as their entries in |
| the actual ZIP file on disk if an existing archive was opened. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{printdir}{} |
| Print a table of contents for the archive to \code{sys.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}{testzip}{} |
| Read all the files in the archive and check their CRC's. Return the |
| name of the first bad file, or else return \code{None}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{write}{filename\optional{, arcname\optional{, |
| compress_type}}} |
| Write the file named \var{filename} to the archive, giving it the |
| archive name \var{arcname} (by default, this will be the same as |
| \var{filename}). If given, \var{compress_type} overrides the value |
| given for the \var{compression} parameter to the constructor for |
| the new entry. The archive must be open with mode \code{'w'} or |
| \code{'a'}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{writestr}{zinfo, bytes} |
| Write the string \var{bytes} to the archive; meta-information is |
| given as the \class{ZipInfo} instance \var{zinfo}. At least the |
| filename, date, and time must be given by \var{zinfo}. The archive |
| must be opened with mode \code{'w'} or \code{'a'}. |
| \end{methoddesc} |
| |
| |
| The following data attribute is also available: |
| |
| \begin{memberdesc}{debug} |
| The level of debug output to use. This may be set from \code{0} |
| (the default, no output) to \code{3} (the most output). Debugging |
| information is written to \code{sys.stdout}. |
| \end{memberdesc} |
| |
| |
| \subsection{PyZipFile Objects \label{pyzipfile-objects}} |
| |
| The \class{PyZipFile} constructor takes the same parameters as the |
| \class{ZipFile} constructor. Instances have one method in addition to |
| those of \class{ZipFile} objects. |
| |
| \begin{methoddesc}[PyZipFile]{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[co]}) 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[co]} 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} |
| |
| |
| \subsection{ZipInfo Objects \label{zipinfo-objects}} |
| |
| Instances of the \class{ZipInfo} class are returned by the |
| \method{getinfo()} and \method{infolist()} methods of |
| \class{ZipFile} objects. Each object stores information about a |
| single member of the ZIP archive. |
| |
| Instances have the following attributes: |
| |
| \begin{memberdesc}[ZipInfo]{filename} |
| Name of the file in the archive. |
| \end{memberdesc} |
| |
| \begin{memberdesc}[ZipInfo]{date_time} |
| The time and date of the last modification to to the archive |
| member. This is a tuple of six values: |
| |
| \begin{tableii}{c|l}{code}{Index}{Value} |
| \lineii{0}{Year} |
| \lineii{1}{Month (one-based)} |
| \lineii{2}{Day of month (one-based)} |
| \lineii{3}{Hours (zero-based)} |
| \lineii{4}{Minutes (zero-based)} |
| \lineii{5}{Seconds (zero-based)} |
| \end{tableii} |
| \end{memberdesc} |
| |
| \begin{memberdesc}[ZipInfo]{compress_type} |
| Type of compression for the archive member. |
| \end{memberdesc} |
| |
| \begin{memberdesc}[ZipInfo]{comment} |
| Comment for the individual archive member. |
| \end{memberdesc} |
| |
| \begin{memberdesc}[ZipInfo]{extra} |
| Expansion field data. The |
| \citetitle[http://www.pkware.com/appnote.html]{PKZIP Application |
| Note} contains some comments on the internal structure of the data |
| contained in this string. |
| \end{memberdesc} |
| |
| \begin{memberdesc}[ZipInfo]{create_system} |
| System which created ZIP archive. |
| \end{memberdesc} |
| |
| \begin{memberdesc}[ZipInfo]{create_version} |
| PKZIP version which created ZIP archive. |
| \end{memberdesc} |
| |
| \begin{memberdesc}[ZipInfo]{extract_version} |
| PKZIP version needed to extract archive. |
| \end{memberdesc} |
| |
| \begin{memberdesc}[ZipInfo]{reserved} |
| Must be zero. |
| \end{memberdesc} |
| |
| \begin{memberdesc}[ZipInfo]{flag_bits} |
| ZIP flag bits. |
| \end{memberdesc} |
| |
| \begin{memberdesc}[ZipInfo]{volume} |
| Volume number of file header. |
| \end{memberdesc} |
| |
| \begin{memberdesc}[ZipInfo]{internal_attr} |
| Internal attributes. |
| \end{memberdesc} |
| |
| \begin{memberdesc}[ZipInfo]{external_attr} |
| External file attributes. |
| \end{memberdesc} |
| |
| \begin{memberdesc}[ZipInfo]{header_offset} |
| Byte offset to the file header. |
| \end{memberdesc} |
| |
| \begin{memberdesc}[ZipInfo]{file_offset} |
| Byte offset to the start of the file data. |
| \end{memberdesc} |
| |
| \begin{memberdesc}[ZipInfo]{CRC} |
| CRC-32 of the uncompressed file. |
| \end{memberdesc} |
| |
| \begin{memberdesc}[ZipInfo]{compress_size} |
| Size of the compressed data. |
| \end{memberdesc} |
| |
| \begin{memberdesc}[ZipInfo]{file_size} |
| Size of the uncompressed file. |
| \end{memberdesc} |