Doc/lib/libzipfile.tex

   1 \section{\module{zipfile} ---
   2          Work with ZIP archives}
   3
   4 \declaremodule{standard}{zipfile}
   5 \modulesynopsis{Read and write ZIP-format archive files.}
   6 \moduleauthor{James C. Ahlstrom}{jim@interet.com}
   7 \sectionauthor{James C. Ahlstrom}{jim@interet.com}
   8 % LaTeX markup by Fred L. Drake, Jr. <fdrake@acm.org>
   9
  10 \versionadded{1.6}
  11
  12 The ZIP file format is a common archive and compression standard.
  13 This module provides tools to create, read, write, append, and list a
  14 ZIP file.  Any advanced use of this module will require an
  15 understanding of the format, as defined in
  16 \citetitle[http://www.pkware.com/appnote.html]{PKZIP Application
  17 Note}.
  18
  19 This module does not currently handle ZIP files which have appended
  20 comments, or multi-disk ZIP files.
  21
  22 The available attributes of this module are:
  23
  24 \begin{excdesc}{error}
  25   The error raised for bad ZIP files.
  26 \end{excdesc}
  27
  28 \begin{classdesc}{ZipFile}{\unspecified}
  29   The class for reading and writing ZIP files.  See
  30   ``\citetitle{ZipFile Objects}'' (section \ref{zipfile-objects}) for
  31   constructor details.
  32 \end{classdesc}
  33
  34 \begin{classdesc}{PyZipFile}{\unspecified}
  35   Class for creating ZIP archives containing Python libraries.
  36 \end{classdesc}
  37
  38 \begin{classdesc}{ZipInfo}{\optional{filename\optional{, date_time}}}
  39   Class used the represent infomation about a member of an archive.
  40   Instances of this class are returned by the \method{getinfo()} and
  41   \method{infolist()} methods of \class{ZipFile} objects.  Most users
  42   of the \module{zipfile} module will not need to create these, but
  43   only use those created by this module.
  44   \var{filename} should be the full name of the archive member, and
  45   \var{date_time} should be a tuple containing six fields which
  46   describe the time of the last modification to the file; the fields
  47   are described in section \ref{zipinfo-objects}, ``ZipInfo Objects.''
  48 \end{classdesc}
  49
  50 \begin{funcdesc}{is_zipfile}{filename}
  51   Returns true if \var{filename} is a valid ZIP file based on its magic
  52   number, otherwise returns false.  This module does not currently
  53   handle ZIP files which have appended comments.
  54 \end{funcdesc}
  55
  56 \begin{datadesc}{ZIP_STORED}
  57   The numeric constant for an uncompressed archive member.
  58 \end{datadesc}
  59
  60 \begin{datadesc}{ZIP_DEFLATED}
  61   The numeric constant for the usual ZIP compression method.  This
  62   requires the zlib module.  No other compression methods are
  63   currently supported.
  64 \end{datadesc}
  65
  66
  67 \begin{seealso}
  68   \seetitle[http://www.pkware.com/appnote.html]{PKZIP Application
  69             Note}{Documentation on the ZIP file format by Phil
  70             Katz, the creator of the format and algorithms used.}
  71
  72   \seetitle[http://www.info-zip.org/pub/infozip/]{Info-ZIP Home Page}{
  73             Information about the Info-ZIP project's ZIP archive
  74             programs and development libraries.}
  75 \end{seealso}
  76
  77
  78 \subsection{ZipFile Objects \label{zipfile-objects}}
  79
  80 \begin{classdesc}{ZipFile}{filename\optional{, mode\optional{, compression}}}
  81   Open a ZIP file named \var{filename}.  The \var{mode} parameter
  82   should be \code{'r'} to read an existing file, \code{'w'} to
  83   truncate and write a new file, or \code{'a'} to append to an
  84   existing file.  For \var{mode} is \code{'a'} and \var{filename}
  85   refers to an existing ZIP file, then additional files are added to
  86   it.  If \var{filename} does not refer to a ZIP file, then a new ZIP
  87   archive is appended to the file.  This is meant for adding a ZIP
  88   archive to another file, such as \file{python.exe}.  Using
  89
  90 \begin{verbatim}
  91 cat myzip.zip >> python.exe
  92 \end{verbatim}
  93
  94   also works, and at least \program{WinZip} can read such files.
  95   \var{compression} is the ZIP compression method to use when writing
  96   the archive, and should be \constant{ZIP_STORED} or
  97   \constant{ZIP_DEFLATED}; unrecognized values will cause
  98   \exception{RuntimeError} to be raised.  If \constant{ZIP_DEFLATED}
  99   is specified but the \refmodule{zlib} module is not avaialble,
 100   \exception{RuntimeError} is also raised.  The default is
 101   \constant{ZIP_STORED}.
 102 \end{classdesc}
 103
 104 \begin{methoddesc}{close}{}
 105   Close the archive file.  You must call \method{close()} before
 106   exiting your program or essential records will not be written.
 107 \end{methoddesc}
 108
 109 \begin{methoddesc}{getinfo}{name}
 110   Return a \class{ZipInfo} object with information about the archive
 111   member \var{name}.
 112 \end{methoddesc}
 113
 114 \begin{methoddesc}{infolist}{}
 115   Return a list containing a \class{ZipInfo} object for each member of
 116   the archive.  The objects are in the same order as their entries in
 117   the actual ZIP file on disk if an existing archive was opened.
 118 \end{methoddesc}
 119
 120 \begin{methoddesc}{namelist}{}
 121   Return a list of archive members by name.
 122 \end{methoddesc}
 123
 124 \begin{methoddesc}{printdir}{}
 125   Print a table of contents for the archive to \code{sys.stdout}.
 126 \end{methoddesc}
 127
 128 \begin{methoddesc}{read}{name}
 129   Return the bytes of the file in the archive.  The archive must be
 130   open for read or append.
 131 \end{methoddesc}
 132
 133 \begin{methoddesc}{testzip}{}
 134   Read all the files in the archive and check their CRC's.  Return the
 135   name of the first bad file, or else return \code{None}.
 136 \end{methoddesc}
 137
 138 \begin{methoddesc}{write}{filename\optional{, arcname\optional{,
 139                           compress_type}}}
 140   Write the file named \var{filename} to the archive, giving it the
 141   archive name \var{arcname} (by default, this will be the same as
 142   \var{filename}).  If given, \var{compress_type} overrides the value
 143   given for the \var{compression} parameter to the constructor for
 144   the new entry.  The archive must be open with mode \code{'w'} or
 145   \code{'a'}.
 146 \end{methoddesc}
 147
 148 \begin{methoddesc}{writestr}{zinfo, bytes}
 149   Write the string \var{bytes} to the archive; meta-information is
 150   given as the \class{ZipInfo} instance \var{zinfo}.  At least the
 151   filename, date, and time must be given by \var{zinfo}.  The archive
 152   must be opened with mode \code{'w'} or \code{'a'}.
 153 \end{methoddesc}
 154
 155
 156 The following data attribute is also available:
 157
 158 \begin{memberdesc}{debug}
 159   The level of debug output to use.  This may be set from \code{0}
 160   (the default, no output) to \code{3} (the most output).  Debugging
 161   information is written to \code{sys.stdout}.
 162 \end{memberdesc}
 163
 164
 165 \subsection{PyZipFile Objects \label{pyzipfile-objects}}
 166
 167 The \class{PyZipFile} constructor takes the same parameters as the
 168 \class{ZipFile} constructor.  Instances have one method in addition to
 169 those of \class{ZipFile} objects.
 170
 171 \begin{methoddesc}[PyZipFile]{writepy}{pathname\optional{, basename}}
 172   Search for files \file{*.py} and add the corresponding file to the
 173   archive.  The corresponding file is a \file{*.pyo} file if
 174   available, else a \file{*.pyc} file, compiling if necessary.  If the
 175   pathname is a file, the filename must end with \file{.py}, and just
 176   the (corresponding \file{*.py[co]}) file is added at the top level
 177   (no path information).  If it is a directory, and the directory is
 178   not a package directory, then all the files \file{*.py[co]} are
 179   added at the top level.  If the directory is a package directory,
 180   then all \file{*.py[oc]} are added under the package name as a file
 181   path, and if any subdirectories are package directories, all of
 182   these are added recursively.  \var{basename} is intended for
 183   internal use only.  The \method{writepy()} method makes archives
 184   with file names like this:
 185
 186 \begin{verbatim}
 187     string.pyc                                # Top level name
 188     test/__init__.pyc                         # Package directory
 189     test/testall.pyc                          # Module test.testall
 190     test/bogus/__init__.pyc                   # Subpackage directory
 191     test/bogus/myfile.pyc                     # Submodule test.bogus.myfile
 192 \end{verbatim}
 193 \end{methoddesc}
 194
 195
 196 \subsection{ZipInfo Objects \label{zipinfo-objects}}
 197
 198 Instances of the \class{ZipInfo} class are returned by the
 199 \method{getinfo()} and \method{infolist()} methods of
 200 \class{ZipFile} objects.  Each object stores information about a
 201 single member of the ZIP archive.
 202
 203 Instances have the following attributes:
 204
 205 \begin{memberdesc}[ZipInfo]{filename}
 206   Name of the file in the archive.
 207 \end{memberdesc}
 208
 209 \begin{memberdesc}[ZipInfo]{date_time}
 210   The time and date of the last modification to to the archive
 211   member.  This is a tuple of six values:
 212
 213 \begin{tableii}{c|l}{code}{Index}{Value}
 214   \lineii{0}{Year}
 215   \lineii{1}{Month (one-based)}
 216   \lineii{2}{Day of month (one-based)}
 217   \lineii{3}{Hours (zero-based)}
 218   \lineii{4}{Minutes (zero-based)}
 219   \lineii{5}{Seconds (zero-based)}
 220 \end{tableii}
 221 \end{memberdesc}
 222
 223 \begin{memberdesc}[ZipInfo]{compress_type}
 224   Type of compression for the archive member.
 225 \end{memberdesc}
 226
 227 \begin{memberdesc}[ZipInfo]{comment}
 228   Comment for the individual archive member.
 229 \end{memberdesc}
 230
 231 \begin{memberdesc}[ZipInfo]{extra}
 232   Expansion field data.  The
 233   \citetitle[http://www.pkware.com/appnote.html]{PKZIP Application
 234   Note} contains some comments on the internal structure of the data
 235   contained in this string.
 236 \end{memberdesc}
 237
 238 \begin{memberdesc}[ZipInfo]{create_system}
 239   System which created ZIP archive.
 240 \end{memberdesc}
 241
 242 \begin{memberdesc}[ZipInfo]{create_version}
 243   PKZIP version which created ZIP archive.
 244 \end{memberdesc}
 245
 246 \begin{memberdesc}[ZipInfo]{extract_version}
 247   PKZIP version needed to extract archive.
 248 \end{memberdesc}
 249
 250 \begin{memberdesc}[ZipInfo]{reserved}
 251   Must be zero.
 252 \end{memberdesc}
 253
 254 \begin{memberdesc}[ZipInfo]{flag_bits}
 255   ZIP flag bits.
 256 \end{memberdesc}
 257
 258 \begin{memberdesc}[ZipInfo]{volume}
 259   Volume number of file header.
 260 \end{memberdesc}
 261
 262 \begin{memberdesc}[ZipInfo]{internal_attr}
 263   Internal attributes.
 264 \end{memberdesc}
 265
 266 \begin{memberdesc}[ZipInfo]{external_attr}
 267  External file attributes.
 268 \end{memberdesc}
 269
 270 \begin{memberdesc}[ZipInfo]{header_offset}
 271   Byte offset to the file header.
 272 \end{memberdesc}
 273
 274 \begin{memberdesc}[ZipInfo]{file_offset}
 275   Byte offset to the start of the file data.
 276 \end{memberdesc}
 277
 278 \begin{memberdesc}[ZipInfo]{CRC}
 279   CRC-32 of the uncompressed file.
 280 \end{memberdesc}
 281
 282 \begin{memberdesc}[ZipInfo]{compress_size}
 283   Size of the compressed data.
 284 \end{memberdesc}
 285
 286 \begin{memberdesc}[ZipInfo]{file_size}
 287   Size of the uncompressed file.
 288 \end{memberdesc}