Fred Drake | 3c9f936 | 2000-03-31 17:51:10 +0000 | [diff] [blame] | 1 | \section{\module{zipfile} --- |
| 2 | Work with ZIP archives} |
| 3 | |
Fred Drake | 1675375 | 2000-09-18 16:21:11 +0000 | [diff] [blame] | 4 | \declaremodule{standard}{zipfile} |
Fred Drake | 3c9f936 | 2000-03-31 17:51:10 +0000 | [diff] [blame] | 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 | |
Fred Drake | 6300bd4 | 2000-09-07 14:01:40 +0000 | [diff] [blame] | 10 | \versionadded{1.6} |
| 11 | |
Fred Drake | 3c9f936 | 2000-03-31 17:51:10 +0000 | [diff] [blame] | 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 |
Fred Drake | 4278024 | 2000-10-02 20:56:30 +0000 | [diff] [blame] | 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. |
Fred Drake | 3c9f936 | 2000-03-31 17:51:10 +0000 | [diff] [blame] | 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 | |
Fred Drake | 4278024 | 2000-10-02 20:56:30 +0000 | [diff] [blame] | 28 | \begin{classdesc}{ZipFile}{\unspecified} |
Fred Drake | 3c9f936 | 2000-03-31 17:51:10 +0000 | [diff] [blame] | 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 | |
Fred Drake | 4278024 | 2000-10-02 20:56:30 +0000 | [diff] [blame] | 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 |
Fred Drake | e35360f | 2000-10-03 15:16:31 +0000 | [diff] [blame] | 41 | \method{infolist()} methods of \class{ZipFile} objects. Most users |
Fred Drake | 4278024 | 2000-10-02 20:56:30 +0000 | [diff] [blame] | 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 | |
Fred Drake | 5d63a39 | 2000-10-06 15:29:56 +0000 | [diff] [blame] | 50 | \begin{funcdesc}{is_zipfile}{filename} |
| 51 | Returns true if \var{filename} is a valid ZIP file based on its magic |
Fred Drake | 3c9f936 | 2000-03-31 17:51:10 +0000 | [diff] [blame] | 52 | number, otherwise returns false. This module does not currently |
| 53 | handle ZIP files which have appended comments. |
| 54 | \end{funcdesc} |
| 55 | |
Fred Drake | 3c9f936 | 2000-03-31 17:51:10 +0000 | [diff] [blame] | 56 | \begin{datadesc}{ZIP_STORED} |
Fred Drake | 5d63a39 | 2000-10-06 15:29:56 +0000 | [diff] [blame] | 57 | The numeric constant for an uncompressed archive member. |
Fred Drake | 3c9f936 | 2000-03-31 17:51:10 +0000 | [diff] [blame] | 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} |
Fred Drake | 58295de | 2000-09-30 00:11:45 +0000 | [diff] [blame] | 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.} |
Fred Drake | 3c9f936 | 2000-03-31 17:51:10 +0000 | [diff] [blame] | 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 |
Fred Drake | 4278024 | 2000-10-02 20:56:30 +0000 | [diff] [blame] | 89 | |
Fred Drake | 3c9f936 | 2000-03-31 17:51:10 +0000 | [diff] [blame] | 90 | \begin{verbatim} |
| 91 | cat myzip.zip >> python.exe |
| 92 | \end{verbatim} |
Fred Drake | 4278024 | 2000-10-02 20:56:30 +0000 | [diff] [blame] | 93 | |
Fred Drake | 3c9f936 | 2000-03-31 17:51:10 +0000 | [diff] [blame] | 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 |
Fred Drake | e35360f | 2000-10-03 15:16:31 +0000 | [diff] [blame] | 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 |
Fred Drake | 3c9f936 | 2000-03-31 17:51:10 +0000 | [diff] [blame] | 101 | \constant{ZIP_STORED}. |
| 102 | \end{classdesc} |
| 103 | |
Fred Drake | e35360f | 2000-10-03 15:16:31 +0000 | [diff] [blame] | 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 | |
Fred Drake | 4278024 | 2000-10-02 20:56:30 +0000 | [diff] [blame] | 114 | \begin{methoddesc}{namelist}{} |
| 115 | Return a list of archive members by name. |
| 116 | \end{methoddesc} |
Fred Drake | 3c9f936 | 2000-03-31 17:51:10 +0000 | [diff] [blame] | 117 | |
Fred Drake | 4278024 | 2000-10-02 20:56:30 +0000 | [diff] [blame] | 118 | \begin{methoddesc}{infolist}{} |
| 119 | Return a list containing a \class{ZipInfo} object for each member of |
| 120 | the archive. The objects are in the same order as their entries in |
| 121 | the actual ZIP file on disk if an existing archive was opened. |
Fred Drake | 3c9f936 | 2000-03-31 17:51:10 +0000 | [diff] [blame] | 122 | \end{methoddesc} |
| 123 | |
| 124 | \begin{methoddesc}{printdir}{} |
Fred Drake | 4278024 | 2000-10-02 20:56:30 +0000 | [diff] [blame] | 125 | Print a table of contents for the archive to \code{sys.stdout}. |
Fred Drake | 3c9f936 | 2000-03-31 17:51:10 +0000 | [diff] [blame] | 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 | |
Fred Drake | 4278024 | 2000-10-02 20:56:30 +0000 | [diff] [blame] | 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 | |
Fred Drake | e35360f | 2000-10-03 15:16:31 +0000 | [diff] [blame] | 138 | \begin{methoddesc}{write}{filename\optional{, arcname\optional{, |
| 139 | compress_type}}} |
Fred Drake | 4278024 | 2000-10-02 20:56:30 +0000 | [diff] [blame] | 140 | Write the file named \var{filename} to the archive, giving it the |
Fred Drake | e35360f | 2000-10-03 15:16:31 +0000 | [diff] [blame] | 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'}. |
Fred Drake | 3c9f936 | 2000-03-31 17:51:10 +0000 | [diff] [blame] | 146 | \end{methoddesc} |
| 147 | |
Fred Drake | e35360f | 2000-10-03 15:16:31 +0000 | [diff] [blame] | 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'}. |
Fred Drake | 3c9f936 | 2000-03-31 17:51:10 +0000 | [diff] [blame] | 153 | \end{methoddesc} |
| 154 | |
Fred Drake | 4278024 | 2000-10-02 20:56:30 +0000 | [diff] [blame] | 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}} |
Fred Drake | 3c9f936 | 2000-03-31 17:51:10 +0000 | [diff] [blame] | 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 |
Fred Drake | 4278024 | 2000-10-02 20:56:30 +0000 | [diff] [blame] | 176 | the (corresponding \file{*.py[co]}) file is added at the top level |
Fred Drake | 3c9f936 | 2000-03-31 17:51:10 +0000 | [diff] [blame] | 177 | (no path information). If it is a directory, and the directory is |
Fred Drake | 4278024 | 2000-10-02 20:56:30 +0000 | [diff] [blame] | 178 | not a package directory, then all the files \file{*.py[co]} are |
Fred Drake | 3c9f936 | 2000-03-31 17:51:10 +0000 | [diff] [blame] | 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 | |
Fred Drake | 4278024 | 2000-10-02 20:56:30 +0000 | [diff] [blame] | 195 | |
| 196 | \subsection{ZipInfo Objects \label{zipinfo-objects}} |
| 197 | |
| 198 | Instances of the \class{ZipInfo} class are returned by the |
Fred Drake | e35360f | 2000-10-03 15:16:31 +0000 | [diff] [blame] | 199 | \method{getinfo()} and \method{infolist()} methods of |
Fred Drake | 4278024 | 2000-10-02 20:56:30 +0000 | [diff] [blame] | 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} |