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}
  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}
  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}{file\optional{, mode\optional{, compression}}}
  81   Open a ZIP file, where \var{file} can be either a path to a file
  82   (a string) or a file-like object.  The \var{mode} parameter
  83   should be \code{'r'} to read an existing file, \code{'w'} to
  84   truncate and write a new file, or \code{'a'} to append to an
  85   existing file.  For \var{mode} is \code{'a'} and \var{file}
  86   refers to an existing ZIP file, then additional files are added to
  87   it.  If \var{file} does not refer to a ZIP file, then a new ZIP
  88   archive is appended to the file.  This is meant for adding a ZIP
  89   archive to another file, such as \file{python.exe}.  Using
  90
  91 \begin{verbatim}
  92 cat myzip.zip >> python.exe
  93 \end{verbatim}
  94
  95   also works, and at least \program{WinZip} can read such files.
  96   \var{compression} is the ZIP compression method to use when writing
  97   the archive, and should be \constant{ZIP_STORED} or
  98   \constant{ZIP_DEFLATED}; unrecognized values will cause
  99   \exception{RuntimeError} to be raised.  If \constant{ZIP_DEFLATED}
 100   is specified but the \refmodule{zlib} module is not available,
 101   \exception{RuntimeError} is also raised.  The default is
 102   \constant{ZIP_STORED}.
 103 \end{classdesc}
 104
 105 \begin{methoddesc}{close}{}
 106   Close the archive file.  You must call \method{close()} before
 107   exiting your program or essential records will not be written.
 108 \end{methoddesc}
 109
 110 \begin{methoddesc}{getinfo}{name}
 111   Return a \class{ZipInfo} object with information about the archive
 112   member \var{name}.
 113 \end{methoddesc}
 114
 115 \begin{methoddesc}{infolist}{}
 116   Return a list containing a \class{ZipInfo} object for each member of
 117   the archive.  The objects are in the same order as their entries in
 118   the actual ZIP file on disk if an existing archive was opened.
 119 \end{methoddesc}
 120
 121 \begin{methoddesc}{namelist}{}
 122   Return a list of archive members by name.
 123 \end{methoddesc}
 124
 125 \begin{methoddesc}{printdir}{}
 126   Print a table of contents for the archive to \code{sys.stdout}.
 127 \end{methoddesc}
 128
 129 \begin{methoddesc}{read}{name}
 130   Return the bytes of the file in the archive.  The archive must be
 131   open for read or append.
 132 \end{methoddesc}
 133
 134 \begin{methoddesc}{testzip}{}
 135   Read all the files in the archive and check their CRC's.  Return the
 136   name of the first bad file, or else return \code{None}.
 137 \end{methoddesc}
 138
 139 \begin{methoddesc}{write}{filename\optional{, arcname\optional{,
 140                           compress_type}}}
 141   Write the file named \var{filename} to the archive, giving it the
 142   archive name \var{arcname} (by default, this will be the same as
 143   \var{filename}).  If given, \var{compress_type} overrides the value
 144   given for the \var{compression} parameter to the constructor for
 145   the new entry.  The archive must be open with mode \code{'w'} or
 146   \code{'a'}.
 147 \end{methoddesc}
 148
 149 \begin{methoddesc}{writestr}{zinfo, bytes}
 150   Write the string \var{bytes} to the archive; meta-information is
 151   given as the \class{ZipInfo} instance \var{zinfo}.  At least the
 152   filename, date, and time must be given by \var{zinfo}.  The archive
 153   must be opened with mode \code{'w'} or \code{'a'}.
 154 \end{methoddesc}
 155
 156
 157 The following data attribute is also available:
 158
 159 \begin{memberdesc}{debug}
 160   The level of debug output to use.  This may be set from \code{0}
 161   (the default, no output) to \code{3} (the most output).  Debugging
 162   information is written to \code{sys.stdout}.
 163 \end{memberdesc}
 164
 165
 166 \subsection{PyZipFile Objects \label{pyzipfile-objects}}
 167
 168 The \class{PyZipFile} constructor takes the same parameters as the
 169 \class{ZipFile} constructor.  Instances have one method in addition to
 170 those of \class{ZipFile} objects.
 171
 172 \begin{methoddesc}[PyZipFile]{writepy}{pathname\optional{, basename}}
 173   Search for files \file{*.py} and add the corresponding file to the
 174   archive.  The corresponding file is a \file{*.pyo} file if
 175   available, else a \file{*.pyc} file, compiling if necessary.  If the
 176   pathname is a file, the filename must end with \file{.py}, and just
 177   the (corresponding \file{*.py[co]}) file is added at the top level
 178   (no path information).  If it is a directory, and the directory is
 179   not a package directory, then all the files \file{*.py[co]} are
 180   added at the top level.  If the directory is a package directory,
 181   then all \file{*.py[oc]} are added under the package name as a file
 182   path, and if any subdirectories are package directories, all of
 183   these are added recursively.  \var{basename} is intended for
 184   internal use only.  The \method{writepy()} method makes archives
 185   with file names like this:
 186
 187 \begin{verbatim}
 188     string.pyc                                # Top level name
 189     test/__init__.pyc                         # Package directory
 190     test/testall.pyc                          # Module test.testall
 191     test/bogus/__init__.pyc                   # Subpackage directory
 192     test/bogus/myfile.pyc                     # Submodule test.bogus.myfile
 193 \end{verbatim}
 194 \end{methoddesc}
 195
 196
 197 \subsection{ZipInfo Objects \label{zipinfo-objects}}
 198
 199 Instances of the \class{ZipInfo} class are returned by the
 200 \method{getinfo()} and \method{infolist()} methods of
 201 \class{ZipFile} objects.  Each object stores information about a
 202 single member of the ZIP archive.
 203
 204 Instances have the following attributes:
 205
 206 \begin{memberdesc}[ZipInfo]{filename}
 207   Name of the file in the archive.
 208 \end{memberdesc}
 209
 210 \begin{memberdesc}[ZipInfo]{date_time}
 211   The time and date of the last modification to to the archive
 212   member.  This is a tuple of six values:
 213
 214 \begin{tableii}{c|l}{code}{Index}{Value}
 215   \lineii{0}{Year}
 216   \lineii{1}{Month (one-based)}
 217   \lineii{2}{Day of month (one-based)}
 218   \lineii{3}{Hours (zero-based)}
 219   \lineii{4}{Minutes (zero-based)}
 220   \lineii{5}{Seconds (zero-based)}
 221 \end{tableii}
 222 \end{memberdesc}
 223
 224 \begin{memberdesc}[ZipInfo]{compress_type}
 225   Type of compression for the archive member.
 226 \end{memberdesc}
 227
 228 \begin{memberdesc}[ZipInfo]{comment}
 229   Comment for the individual archive member.
 230 \end{memberdesc}
 231
 232 \begin{memberdesc}[ZipInfo]{extra}
 233   Expansion field data.  The
 234   \citetitle[http://www.pkware.com/appnote.html]{PKZIP Application
 235   Note} contains some comments on the internal structure of the data
 236   contained in this string.
 237 \end{memberdesc}
 238
 239 \begin{memberdesc}[ZipInfo]{create_system}
 240   System which created ZIP archive.
 241 \end{memberdesc}
 242
 243 \begin{memberdesc}[ZipInfo]{create_version}
 244   PKZIP version which created ZIP archive.
 245 \end{memberdesc}
 246
 247 \begin{memberdesc}[ZipInfo]{extract_version}
 248   PKZIP version needed to extract archive.
 249 \end{memberdesc}
 250
 251 \begin{memberdesc}[ZipInfo]{reserved}
 252   Must be zero.
 253 \end{memberdesc}
 254
 255 \begin{memberdesc}[ZipInfo]{flag_bits}
 256   ZIP flag bits.
 257 \end{memberdesc}
 258
 259 \begin{memberdesc}[ZipInfo]{volume}
 260   Volume number of file header.
 261 \end{memberdesc}
 262
 263 \begin{memberdesc}[ZipInfo]{internal_attr}
 264   Internal attributes.
 265 \end{memberdesc}
 266
 267 \begin{memberdesc}[ZipInfo]{external_attr}
 268  External file attributes.
 269 \end{memberdesc}
 270
 271 \begin{memberdesc}[ZipInfo]{header_offset}
 272   Byte offset to the file header.
 273 \end{memberdesc}
 274
 275 \begin{memberdesc}[ZipInfo]{file_offset}
 276   Byte offset to the start of the file data.
 277 \end{memberdesc}
 278
 279 \begin{memberdesc}[ZipInfo]{CRC}
 280   CRC-32 of the uncompressed file.
 281 \end{memberdesc}
 282
 283 \begin{memberdesc}[ZipInfo]{compress_size}
 284   Size of the compressed data.
 285 \end{memberdesc}
 286
 287 \begin{memberdesc}[ZipInfo]{file_size}
 288   Size of the uncompressed file.
 289 \end{memberdesc}