Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 4278024

Browse files
freddrakefreddrake
committed
Substantially revised documentation for the zipfile module, partially based
on revised text from Jim Ahlstrom <[email protected]>. This closes SourceForge bug #115681.
1 parent 5df72f0 commit 4278024

1 file changed

Lines changed: 164 additions & 60 deletions

File tree

‎Doc/lib/libzipfile.tex‎

Lines changed: 164 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,13 @@ \section{\module{zipfile} ---
1111

1212
The ZIP file format is a common archive and compression standard.
1313
This module provides tools to create, read, write, append, and list a
14-
ZIP file.
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.
1521

1622
The available attributes of this module are:
1723

@@ -23,36 +29,34 @@ \section{\module{zipfile} ---
2329
Level of printing, defaults to \code{1}.
2430
\end{datadesc}
2531

26-
\begin{classdesc}{ZipFile}{...}
32+
\begin{classdesc}{ZipFile}{\unspecified}
2733
The class for reading and writing ZIP files. See
2834
``\citetitle{ZipFile Objects}'' (section \ref{zipfile-objects}) for
2935
constructor details.
3036
\end{classdesc}
3137

38+
\begin{classdesc}{PyZipFile}{\unspecified}
39+
Class for creating ZIP archives containing Python libraries.
40+
\end{classdesc}
41+
42+
\begin{classdesc}{ZipInfo}{\optional{filename\optional{, date_time}}}
43+
Class used the represent infomation about a member of an archive.
44+
Instances of this class are returned by the \method{getinfo()} and
45+
\method{listinfo()} methods of \class{ZipFile} objects. Most users
46+
of the \module{zipfile} module will not need to create these, but
47+
only use those created by this module.
48+
\var{filename} should be the full name of the archive member, and
49+
\var{date_time} should be a tuple containing six fields which
50+
describe the time of the last modification to the file; the fields
51+
are described in section \ref{zipinfo-objects}, ``ZipInfo Objects.''
52+
\end{classdesc}
53+
3254
\begin{funcdesc}{is_zipfile}{path}
3355
Returns true if \var{path} is a valid ZIP file based on its magic
3456
number, otherwise returns false. This module does not currently
3557
handle ZIP files which have appended comments.
3658
\end{funcdesc}
3759

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-
5660
\begin{datadesc}{ZIP_STORED}
5761
The numeric constant (\code{0}) for an uncompressed archive member.
5862
\end{datadesc}
@@ -86,9 +90,11 @@ \subsection{ZipFile Objects \label{zipfile-objects}}
8690
it. If \var{filename} does not refer to a ZIP file, then a new ZIP
8791
archive is appended to the file. This is meant for adding a ZIP
8892
archive to another file, such as \file{python.exe}. Using
93+
8994
\begin{verbatim}
9095
cat myzip.zip >> python.exe
9196
\end{verbatim}
97+
9298
also works, and at least \program{WinZip} can read such files.
9399
\var{compression} is the ZIP compression method to use when writing
94100
the archive, and should be \constant{ZIP_STORED} or
@@ -97,64 +103,72 @@ \subsection{ZipFile Objects \label{zipfile-objects}}
97103
\constant{ZIP_STORED}.
98104
\end{classdesc}
99105

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:
106+
\begin{methoddesc}{namelist}{}
107+
Return a list of archive members by name.
108+
\end{methoddesc}
120109

121-
\begin{methoddesc}{listdir}{}
122-
Return a list of names in the archive. Equivalent to
123-
\code{\var{zipfile}.TOC.keys()}.
110+
\begin{methoddesc}{infolist}{}
111+
Return a list containing a \class{ZipInfo} object for each member of
112+
the archive. The objects are in the same order as their entries in
113+
the actual ZIP file on disk if an existing archive was opened.
124114
\end{methoddesc}
125115

126116
\begin{methoddesc}{printdir}{}
127-
Print a table of contents for the archive to stdout.
117+
Print a table of contents for the archive to \code{sys.stdout}.
128118
\end{methoddesc}
129119

130120
\begin{methoddesc}{read}{name}
131121
Return the bytes of the file in the archive. The archive must be
132122
open for read or append.
133123
\end{methoddesc}
134124

135-
\begin{methoddesc}{writestr}{bytes, arcname, year, month, day, hour,
136-
minute, second\optional{, extra}}
125+
\begin{methoddesc}{testzip}{}
126+
Read all the files in the archive and check their CRC's. Return the
127+
name of the first bad file, or else return \code{None}.
128+
\end{methoddesc}
129+
130+
\begin{methoddesc}{writestr}{bytes, arcname, year, month, day,
131+
hour, minute, second}
137132
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'}.
133+
give the archive member the name \var{arcname}. The archive must be
134+
opened with mode \code{'w'} or \code{'a'}.
141135
\end{methoddesc}
142136

143-
\begin{methoddesc}{write}{filename, arcname\optional{, extra}}
137+
\begin{methoddesc}{write}{filename, arcname}
144138
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'}.
139+
archive name \var{arcname}. The archive must be open with mode
140+
\code{'w'} or \code{'a'}.
141+
\end{methoddesc}
142+
143+
\begin{methoddesc}{close}{}
144+
Close the archive file. You must call \method{close()} before
145+
exiting your program or essential records will not be written.
148146
\end{methoddesc}
149147

150-
\begin{methoddesc}{writepy}{pathname\optional{, basename}}
148+
149+
The following data attribute is also available:
150+
151+
\begin{memberdesc}{debug}
152+
The level of debug output to use. This may be set from \code{0}
153+
(the default, no output) to \code{3} (the most output). Debugging
154+
information is written to \code{sys.stdout}.
155+
\end{memberdesc}
156+
157+
158+
\subsection{PyZipFile Objects \label{pyzipfile-objects}}
159+
160+
The \class{PyZipFile} constructor takes the same parameters as the
161+
\class{ZipFile} constructor. Instances have one method in addition to
162+
those of \class{ZipFile} objects.
163+
164+
\begin{methoddesc}[PyZipFile]{writepy}{pathname\optional{, basename}}
151165
Search for files \file{*.py} and add the corresponding file to the
152166
archive. The corresponding file is a \file{*.pyo} file if
153167
available, else a \file{*.pyc} file, compiling if necessary. If the
154168
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
169+
the (corresponding \file{*.py[co]}) file is added at the top level
156170
(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
171+
not a package directory, then all the files \file{*.py[co]} are
158172
added at the top level. If the directory is a package directory,
159173
then all \file{*.py[oc]} are added under the package name as a file
160174
path, and if any subdirectories are package directories, all of
@@ -171,7 +185,97 @@ \subsection{ZipFile Objects \label{zipfile-objects}}
171185
\end{verbatim}
172186
\end{methoddesc}
173187

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}
188+
189+
\subsection{ZipInfo Objects \label{zipinfo-objects}}
190+
191+
Instances of the \class{ZipInfo} class are returned by the
192+
\method{getinfo()} and \method{listinfo()} methods of
193+
\class{ZipFile} objects. Each object stores information about a
194+
single member of the ZIP archive.
195+
196+
Instances have the following attributes:
197+
198+
\begin{memberdesc}[ZipInfo]{filename}
199+
Name of the file in the archive.
200+
\end{memberdesc}
201+
202+
\begin{memberdesc}[ZipInfo]{date_time}
203+
The time and date of the last modification to to the archive
204+
member. This is a tuple of six values:
205+
206+
\begin{tableii}{c|l}{code}{Index}{Value}
207+
\lineii{0}{Year}
208+
\lineii{1}{Month (one-based)}
209+
\lineii{2}{Day of month (one-based)}
210+
\lineii{3}{Hours (zero-based)}
211+
\lineii{4}{Minutes (zero-based)}
212+
\lineii{5}{Seconds (zero-based)}
213+
\end{tableii}
214+
\end{memberdesc}
215+
216+
\begin{memberdesc}[ZipInfo]{compress_type}
217+
Type of compression for the archive member.
218+
\end{memberdesc}
219+
220+
\begin{memberdesc}[ZipInfo]{comment}
221+
Comment for the individual archive member.
222+
\end{memberdesc}
223+
224+
\begin{memberdesc}[ZipInfo]{extra}
225+
Expansion field data. The
226+
\citetitle[http://www.pkware.com/appnote.html]{PKZIP Application
227+
Note} contains some comments on the internal structure of the data
228+
contained in this string.
229+
\end{memberdesc}
230+
231+
\begin{memberdesc}[ZipInfo]{create_system}
232+
System which created ZIP archive.
233+
\end{memberdesc}
234+
235+
\begin{memberdesc}[ZipInfo]{create_version}
236+
PKZIP version which created ZIP archive.
237+
\end{memberdesc}
238+
239+
\begin{memberdesc}[ZipInfo]{extract_version}
240+
PKZIP version needed to extract archive.
241+
\end{memberdesc}
242+
243+
\begin{memberdesc}[ZipInfo]{reserved}
244+
Must be zero.
245+
\end{memberdesc}
246+
247+
\begin{memberdesc}[ZipInfo]{flag_bits}
248+
ZIP flag bits.
249+
\end{memberdesc}
250+
251+
\begin{memberdesc}[ZipInfo]{volume}
252+
Volume number of file header.
253+
\end{memberdesc}
254+
255+
\begin{memberdesc}[ZipInfo]{internal_attr}
256+
Internal attributes.
257+
\end{memberdesc}
258+
259+
\begin{memberdesc}[ZipInfo]{external_attr}
260+
External file attributes.
261+
\end{memberdesc}
262+
263+
\begin{memberdesc}[ZipInfo]{header_offset}
264+
Byte offset to the file header.
265+
\end{memberdesc}
266+
267+
\begin{memberdesc}[ZipInfo]{file_offset}
268+
Byte offset to the start of the file data.
269+
\end{memberdesc}
270+
271+
\begin{memberdesc}[ZipInfo]{CRC}
272+
CRC-32 of the uncompressed file.
273+
\end{memberdesc}
274+
275+
\begin{memberdesc}[ZipInfo]{compress_size}
276+
Size of the compressed data.
277+
\end{memberdesc}
278+
279+
\begin{memberdesc}[ZipInfo]{file_size}
280+
Size of the uncompressed file.
281+
\end{memberdesc}

0 commit comments

Comments
 (0)