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 to represent information 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 \code{True} if \var{filename} is a valid ZIP file based on its magic
  52   number, otherwise returns \code{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_or_arcname, bytes}
 150   Write the string \var{bytes} to the archive; \var{zinfo_or_arcname}
 151   is either the file name it will be given in the archive, or a
 152   \class{ZipInfo} instance.  If it's an instance, at least the
 153   filename, date, and time must be given.  If it's a name, the date
 154   and time is set to the current date and time. The archive must be
 155   opened with mode \code{'w'} or \code{'a'}.
 156 \end{methoddesc}
 157
 158
 159 The following data attribute is also available:
 160
 161 \begin{memberdesc}{debug}
 162   The level of debug output to use.  This may be set from \code{0}
 163   (the default, no output) to \code{3} (the most output).  Debugging
 164   information is written to \code{sys.stdout}.
 165 \end{memberdesc}
 166
 167
 168 \subsection{PyZipFile Objects \label{pyzipfile-objects}}
 169
 170 The \class{PyZipFile} constructor takes the same parameters as the
 171 \class{ZipFile} constructor.  Instances have one method in addition to
 172 those of \class{ZipFile} objects.
 173
 174 \begin{methoddesc}[PyZipFile]{writepy}{pathname\optional{, basename}}
 175   Search for files \file{*.py} and add the corresponding file to the
 176   archive.  The corresponding file is a \file{*.pyo} file if
 177   available, else a \file{*.pyc} file, compiling if necessary.  If the
 178   pathname is a file, the filename must end with \file{.py}, and just
 179   the (corresponding \file{*.py[co]}) file is added at the top level
 180   (no path information).  If it is a directory, and the directory is
 181   not a package directory, then all the files \file{*.py[co]} are
 182   added at the top level.  If the directory is a package directory,
 183   then all \file{*.py[oc]} are added under the package name as a file
 184   path, and if any subdirectories are package directories, all of
 185   these are added recursively.  \var{basename} is intended for
 186   internal use only.  The \method{writepy()} method makes archives
 187   with file names like this:
 188
 189 \begin{verbatim}
 190     string.pyc                                # Top level name
 191     test/__init__.pyc                         # Package directory
 192     test/testall.pyc                          # Module test.testall
 193     test/bogus/__init__.pyc                   # Subpackage directory
 194     test/bogus/myfile.pyc                     # Submodule test.bogus.myfile
 195 \end{verbatim}
 196 \end{methoddesc}
 197
 198
 199 \subsection{ZipInfo Objects \label{zipinfo-objects}}
 200
 201 Instances of the \class{ZipInfo} class are returned by the
 202 \method{getinfo()} and \method{infolist()} methods of
 203 \class{ZipFile} objects.  Each object stores information about a
 204 single member of the ZIP archive.
 205
 206 Instances have the following attributes:
 207
 208 \begin{memberdesc}[ZipInfo]{filename}
 209   Name of the file in the archive.
 210 \end{memberdesc}
 211
 212 \begin{memberdesc}[ZipInfo]{date_time}
 213   The time and date of the last modification to the archive
 214   member.  This is a tuple of six values:
 215
 216 \begin{tableii}{c|l}{code}{Index}{Value}
 217   \lineii{0}{Year}
 218   \lineii{1}{Month (one-based)}
 219   \lineii{2}{Day of month (one-based)}
 220   \lineii{3}{Hours (zero-based)}
 221   \lineii{4}{Minutes (zero-based)}
 222   \lineii{5}{Seconds (zero-based)}
 223 \end{tableii}
 224 \end{memberdesc}
 225
 226 \begin{memberdesc}[ZipInfo]{compress_type}
 227   Type of compression for the archive member.
 228 \end{memberdesc}
 229
 230 \begin{memberdesc}[ZipInfo]{comment}
 231   Comment for the individual archive member.
 232 \end{memberdesc}
 233
 234 \begin{memberdesc}[ZipInfo]{extra}
 235   Expansion field data.  The
 236   \citetitle[http://www.pkware.com/appnote.html]{PKZIP Application
 237   Note} contains some comments on the internal structure of the data
 238   contained in this string.
 239 \end{memberdesc}
 240
 241 \begin{memberdesc}[ZipInfo]{create_system}
 242   System which created ZIP archive.
 243 \end{memberdesc}
 244
 245 \begin{memberdesc}[ZipInfo]{create_version}
 246   PKZIP version which created ZIP archive.
 247 \end{memberdesc}
 248
 249 \begin{memberdesc}[ZipInfo]{extract_version}
 250   PKZIP version needed to extract archive.
 251 \end{memberdesc}
 252
 253 \begin{memberdesc}[ZipInfo]{reserved}
 254   Must be zero.
 255 \end{memberdesc}
 256
 257 \begin{memberdesc}[ZipInfo]{flag_bits}
 258   ZIP flag bits.
 259 \end{memberdesc}
 260
 261 \begin{memberdesc}[ZipInfo]{volume}
 262   Volume number of file header.
 263 \end{memberdesc}
 264
 265 \begin{memberdesc}[ZipInfo]{internal_attr}
 266   Internal attributes.
 267 \end{memberdesc}
 268
 269 \begin{memberdesc}[ZipInfo]{external_attr}
 270  External file attributes.
 271 \end{memberdesc}
 272
 273 \begin{memberdesc}[ZipInfo]{header_offset}
 274   Byte offset to the file header.
 275 \end{memberdesc}
 276
 277 \begin{memberdesc}[ZipInfo]{file_offset}
 278   Byte offset to the start of the file data.
 279 \end{memberdesc}
 280
 281 \begin{memberdesc}[ZipInfo]{CRC}
 282   CRC-32 of the uncompressed file.
 283 \end{memberdesc}
 284
 285 \begin{memberdesc}[ZipInfo]{compress_size}
 286   Size of the compressed data.
 287 \end{memberdesc}
 288
 289 \begin{memberdesc}[ZipInfo]{file_size}
 290   Size of the uncompressed file.
 291 \end{memberdesc}