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 |
| 14 | ZIP file. |
| 15 | |
| 16 | The available attributes of this module are: |
| 17 | |
| 18 | \begin{excdesc}{error} |
| 19 | The error raised for bad ZIP files. |
| 20 | \end{excdesc} |
| 21 | |
| 22 | \begin{datadesc}{_debug} |
| 23 | Level of printing, defaults to \code{1}. |
| 24 | \end{datadesc} |
| 25 | |
| 26 | \begin{classdesc}{ZipFile}{...} |
| 27 | The class for reading and writing ZIP files. See |
| 28 | ``\citetitle{ZipFile Objects}'' (section \ref{zipfile-objects}) for |
| 29 | constructor details. |
| 30 | \end{classdesc} |
| 31 | |
| 32 | \begin{funcdesc}{is_zipfile}{path} |
| 33 | Returns true if \var{path} is a valid ZIP file based on its magic |
| 34 | number, otherwise returns false. This module does not currently |
| 35 | handle ZIP files which have appended comments. |
| 36 | \end{funcdesc} |
| 37 | |
| 38 | \begin{funcdesc}{zip2date}{zdate} |
| 39 | Return \code{(\var{year}, \var{month}, \var{day})} for a ZIP date |
| 40 | code. |
| 41 | \end{funcdesc} |
| 42 | |
| 43 | \begin{funcdesc}{zip2time}{ztime} |
| 44 | Return \code{(\var{hour}, \var{minute}, \var{second})} for a ZIP |
| 45 | time code. |
| 46 | \end{funcdesc} |
| 47 | |
| 48 | \begin{funcdesc}{date2zip}{year, month, day} |
| 49 | Return a ZIP date code. |
| 50 | \end{funcdesc} |
| 51 | |
| 52 | \begin{funcdesc}{time2zip}{hour, minute, second} |
| 53 | Return a ZIP time code. |
| 54 | \end{funcdesc} |
| 55 | |
| 56 | \begin{datadesc}{ZIP_STORED} |
| 57 | The numeric constant (\code{0}) 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} |
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 |
| 89 | \begin{verbatim} |
| 90 | cat myzip.zip >> python.exe |
| 91 | \end{verbatim} |
| 92 | also works, and at least \program{WinZip} can read such files. |
| 93 | \var{compression} is the ZIP compression method to use when writing |
| 94 | the archive, and should be \constant{ZIP_STORED} or |
| 95 | \constant{ZIP_DEFLATED}; unrecognized values will cause |
| 96 | \exception{ValueError} to be raised. The default is |
| 97 | \constant{ZIP_STORED}. |
| 98 | \end{classdesc} |
| 99 | |
| 100 | XXX explain the "extra" string for the ZIP format |
| 101 | |
| 102 | \begin{memberdesc}{TOC} |
| 103 | A read-only dictionary whose keys are the names in the archive, and |
| 104 | whose values are tuples as follows: |
| 105 | |
| 106 | \begin{tableii}{c|l}{code}{Index}{Meaning} |
| 107 | \lineii{0}{File data seek offset} |
| 108 | \lineii{1}{ZIP file "extra" data as a string} |
| 109 | \lineii{2}{ZIP file bit flags} |
| 110 | \lineii{3}{ZIP file compression type} |
| 111 | \lineii{4}{File modification time in DOS format} |
| 112 | \lineii{5}{File modification date in DOS format} |
| 113 | \lineii{6}{The CRC-32 of the uncompressed data} |
| 114 | \lineii{7}{The compressed size of the file} |
| 115 | \lineii{8}{The uncompressed size of the file} |
| 116 | \end{tableii} |
| 117 | \end{memberdesc} |
| 118 | |
| 119 | The class ZipFile has these methods: |
| 120 | |
| 121 | \begin{methoddesc}{listdir}{} |
| 122 | Return a list of names in the archive. Equivalent to |
| 123 | \code{\var{zipfile}.TOC.keys()}. |
| 124 | \end{methoddesc} |
| 125 | |
| 126 | \begin{methoddesc}{printdir}{} |
| 127 | Print a table of contents for the archive to stdout. |
| 128 | \end{methoddesc} |
| 129 | |
| 130 | \begin{methoddesc}{read}{name} |
| 131 | Return the bytes of the file in the archive. The archive must be |
| 132 | open for read or append. |
| 133 | \end{methoddesc} |
| 134 | |
| 135 | \begin{methoddesc}{writestr}{bytes, arcname, year, month, day, hour, |
| 136 | minute, second\optional{, extra}} |
| 137 | Write the string \var{bytes} and the other data to the archive, and |
| 138 | give the archive member the name \var{arcname}. \var{extra} is the |
| 139 | ZIP extra data string. The archive must be opened with mode |
| 140 | \code{'w'} or \code{'a'}. |
| 141 | \end{methoddesc} |
| 142 | |
| 143 | \begin{methoddesc}{write}{filename, arcname\optional{, extra}} |
| 144 | Write the file named \var{filename} to the archive, giving it the |
| 145 | archive name \var{arcname}. \var{extra} is the ZIP extra data |
| 146 | string. The archive must be open with mode \code{'w'} or |
| 147 | \code{'a'}. |
| 148 | \end{methoddesc} |
| 149 | |
| 150 | \begin{methoddesc}{writepy}{pathname\optional{, basename}} |
| 151 | Search for files \file{*.py} and add the corresponding file to the |
| 152 | archive. The corresponding file is a \file{*.pyo} file if |
| 153 | available, else a \file{*.pyc} file, compiling if necessary. If the |
| 154 | pathname is a file, the filename must end with \file{.py}, and just |
| 155 | the (corresponding \file{*.py[oc]}) file is added at the top level |
| 156 | (no path information). If it is a directory, and the directory is |
| 157 | not a package directory, then all the files \file{*.py[oc]} are |
| 158 | added at the top level. If the directory is a package directory, |
| 159 | then all \file{*.py[oc]} are added under the package name as a file |
| 160 | path, and if any subdirectories are package directories, all of |
| 161 | these are added recursively. \var{basename} is intended for |
| 162 | internal use only. The \method{writepy()} method makes archives |
| 163 | with file names like this: |
| 164 | |
| 165 | \begin{verbatim} |
| 166 | string.pyc # Top level name |
| 167 | test/__init__.pyc # Package directory |
| 168 | test/testall.pyc # Module test.testall |
| 169 | test/bogus/__init__.pyc # Subpackage directory |
| 170 | test/bogus/myfile.pyc # Submodule test.bogus.myfile |
| 171 | \end{verbatim} |
| 172 | \end{methoddesc} |
| 173 | |
| 174 | \begin{methoddesc}{close}{} |
| 175 | Close the archive file. You must call \method{close()} before |
| 176 | exiting your program or essential records will not be written. |
| 177 | \end{methoddesc} |