[Python-checkins] CVS: python/dist/src/Doc/lib libzipfile.tex,1.4,1.5
Fred L. Drake
python-dev@python.org
Mon, 2 Oct 2000 13:56:33 -0700
Update of /cvsroot/python/python/dist/src/Doc/lib
In directory slayer.i.sourceforge.net:/tmp/cvs-serv15558/lib
Modified Files:
libzipfile.tex
Log Message:
Substantially revised documentation for the zipfile module, partially based
on revised text from Jim Ahlstrom <jim@interet.com>.
This closes SourceForge bug #115681.
Index: libzipfile.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libzipfile.tex,v
retrieving revision 1.4
retrieving revision 1.5
diff -C2 -r1.4 -r1.5
*** libzipfile.tex 2000/09/30 00:11:45 1.4
--- libzipfile.tex 2000/10/02 20:56:30 1.5
***************
*** 12,17 ****
The ZIP file format is a common archive and compression standard.
This module provides tools to create, read, write, append, and list a
! ZIP file.
The available attributes of this module are:
--- 12,23 ----
The ZIP file format is a common archive and compression standard.
This module provides tools to create, read, write, append, and list a
! ZIP file. Any advanced use of this module will require an
! understanding of the format, as defined in
! \citetitle[http://www.pkware.com/appnote.html]{PKZIP Application
! Note}.
+ This module does not currently handle ZIP files which have appended
+ comments, or multi-disk ZIP files.
+
The available attributes of this module are:
***************
*** 24,28 ****
\end{datadesc}
! \begin{classdesc}{ZipFile}{...}
The class for reading and writing ZIP files. See
``\citetitle{ZipFile Objects}'' (section \ref{zipfile-objects}) for
--- 30,34 ----
\end{datadesc}
! \begin{classdesc}{ZipFile}{\unspecified}
The class for reading and writing ZIP files. See
``\citetitle{ZipFile Objects}'' (section \ref{zipfile-objects}) for
***************
*** 30,33 ****
--- 36,55 ----
\end{classdesc}
+ \begin{classdesc}{PyZipFile}{\unspecified}
+ Class for creating ZIP archives containing Python libraries.
+ \end{classdesc}
+
+ \begin{classdesc}{ZipInfo}{\optional{filename\optional{, date_time}}}
+ Class used the represent infomation about a member of an archive.
+ Instances of this class are returned by the \method{getinfo()} and
+ \method{listinfo()} methods of \class{ZipFile} objects. Most users
+ of the \module{zipfile} module will not need to create these, but
+ only use those created by this module.
+ \var{filename} should be the full name of the archive member, and
+ \var{date_time} should be a tuple containing six fields which
+ describe the time of the last modification to the file; the fields
+ are described in section \ref{zipinfo-objects}, ``ZipInfo Objects.''
+ \end{classdesc}
+
\begin{funcdesc}{is_zipfile}{path}
Returns true if \var{path} is a valid ZIP file based on its magic
***************
*** 36,57 ****
\end{funcdesc}
- \begin{funcdesc}{zip2date}{zdate}
- Return \code{(\var{year}, \var{month}, \var{day})} for a ZIP date
- code.
- \end{funcdesc}
-
- \begin{funcdesc}{zip2time}{ztime}
- Return \code{(\var{hour}, \var{minute}, \var{second})} for a ZIP
- time code.
- \end{funcdesc}
-
- \begin{funcdesc}{date2zip}{year, month, day}
- Return a ZIP date code.
- \end{funcdesc}
-
- \begin{funcdesc}{time2zip}{hour, minute, second}
- Return a ZIP time code.
- \end{funcdesc}
-
\begin{datadesc}{ZIP_STORED}
The numeric constant (\code{0}) for an uncompressed archive member.
--- 58,61 ----
***************
*** 87,93 ****
--- 91,99 ----
archive is appended to the file. This is meant for adding a ZIP
archive to another file, such as \file{python.exe}. Using
+
\begin{verbatim}
cat myzip.zip >> python.exe
\end{verbatim}
+
also works, and at least \program{WinZip} can read such files.
\var{compression} is the ZIP compression method to use when writing
***************
*** 98,129 ****
\end{classdesc}
! XXX explain the "extra" string for the ZIP format
!
! \begin{memberdesc}{TOC}
! A read-only dictionary whose keys are the names in the archive, and
! whose values are tuples as follows:
!
! \begin{tableii}{c|l}{code}{Index}{Meaning}
! \lineii{0}{File data seek offset}
! \lineii{1}{ZIP file "extra" data as a string}
! \lineii{2}{ZIP file bit flags}
! \lineii{3}{ZIP file compression type}
! \lineii{4}{File modification time in DOS format}
! \lineii{5}{File modification date in DOS format}
! \lineii{6}{The CRC-32 of the uncompressed data}
! \lineii{7}{The compressed size of the file}
! \lineii{8}{The uncompressed size of the file}
! \end{tableii}
! \end{memberdesc}
!
! The class ZipFile has these methods:
! \begin{methoddesc}{listdir}{}
! Return a list of names in the archive. Equivalent to
! \code{\var{zipfile}.TOC.keys()}.
\end{methoddesc}
\begin{methoddesc}{printdir}{}
! Print a table of contents for the archive to stdout.
\end{methoddesc}
--- 104,119 ----
\end{classdesc}
! \begin{methoddesc}{namelist}{}
! Return a list of archive members by name.
! \end{methoddesc}
! \begin{methoddesc}{infolist}{}
! Return a list containing a \class{ZipInfo} object for each member of
! the archive. The objects are in the same order as their entries in
! the actual ZIP file on disk if an existing archive was opened.
\end{methoddesc}
\begin{methoddesc}{printdir}{}
! Print a table of contents for the archive to \code{sys.stdout}.
\end{methoddesc}
***************
*** 133,159 ****
\end{methoddesc}
! \begin{methoddesc}{writestr}{bytes, arcname, year, month, day, hour,
! minute, second\optional{, extra}}
Write the string \var{bytes} and the other data to the archive, and
! give the archive member the name \var{arcname}. \var{extra} is the
! ZIP extra data string. The archive must be opened with mode
! \code{'w'} or \code{'a'}.
\end{methoddesc}
! \begin{methoddesc}{write}{filename, arcname\optional{, extra}}
Write the file named \var{filename} to the archive, giving it the
! archive name \var{arcname}. \var{extra} is the ZIP extra data
! string. The archive must be open with mode \code{'w'} or
! \code{'a'}.
\end{methoddesc}
! \begin{methoddesc}{writepy}{pathname\optional{, basename}}
Search for files \file{*.py} and add the corresponding file to the
archive. The corresponding file is a \file{*.pyo} file if
available, else a \file{*.pyc} file, compiling if necessary. If the
pathname is a file, the filename must end with \file{.py}, and just
! the (corresponding \file{*.py[oc]}) file is added at the top level
(no path information). If it is a directory, and the directory is
! not a package directory, then all the files \file{*.py[oc]} are
added at the top level. If the directory is a package directory,
then all \file{*.py[oc]} are added under the package name as a file
--- 123,173 ----
\end{methoddesc}
! \begin{methoddesc}{testzip}{}
! Read all the files in the archive and check their CRC's. Return the
! name of the first bad file, or else return \code{None}.
! \end{methoddesc}
!
! \begin{methoddesc}{writestr}{bytes, arcname, year, month, day,
! hour, minute, second}
Write the string \var{bytes} and the other data to the archive, and
! give the archive member the name \var{arcname}. The archive must be
! opened with mode \code{'w'} or \code{'a'}.
\end{methoddesc}
! \begin{methoddesc}{write}{filename, arcname}
Write the file named \var{filename} to the archive, giving it the
! archive name \var{arcname}. The archive must be open with mode
! \code{'w'} or \code{'a'}.
! \end{methoddesc}
!
! \begin{methoddesc}{close}{}
! Close the archive file. You must call \method{close()} before
! exiting your program or essential records will not be written.
\end{methoddesc}
+
! The following data attribute is also available:
!
! \begin{memberdesc}{debug}
! The level of debug output to use. This may be set from \code{0}
! (the default, no output) to \code{3} (the most output). Debugging
! information is written to \code{sys.stdout}.
! \end{memberdesc}
!
!
! \subsection{PyZipFile Objects \label{pyzipfile-objects}}
!
! The \class{PyZipFile} constructor takes the same parameters as the
! \class{ZipFile} constructor. Instances have one method in addition to
! those of \class{ZipFile} objects.
!
! \begin{methoddesc}[PyZipFile]{writepy}{pathname\optional{, basename}}
Search for files \file{*.py} and add the corresponding file to the
archive. The corresponding file is a \file{*.pyo} file if
available, else a \file{*.pyc} file, compiling if necessary. If the
pathname is a file, the filename must end with \file{.py}, and just
! the (corresponding \file{*.py[co]}) file is added at the top level
(no path information). If it is a directory, and the directory is
! not a package directory, then all the files \file{*.py[co]} are
added at the top level. If the directory is a package directory,
then all \file{*.py[oc]} are added under the package name as a file
***************
*** 172,177 ****
\end{methoddesc}
! \begin{methoddesc}{close}{}
! Close the archive file. You must call \method{close()} before
! exiting your program or essential records will not be written.
! \end{methoddesc}
--- 186,281 ----
\end{methoddesc}
!
! \subsection{ZipInfo Objects \label{zipinfo-objects}}
!
! Instances of the \class{ZipInfo} class are returned by the
! \method{getinfo()} and \method{listinfo()} methods of
! \class{ZipFile} objects. Each object stores information about a
! single member of the ZIP archive.
!
! Instances have the following attributes:
!
! \begin{memberdesc}[ZipInfo]{filename}
! Name of the file in the archive.
! \end{memberdesc}
!
! \begin{memberdesc}[ZipInfo]{date_time}
! The time and date of the last modification to to the archive
! member. This is a tuple of six values:
!
! \begin{tableii}{c|l}{code}{Index}{Value}
! \lineii{0}{Year}
! \lineii{1}{Month (one-based)}
! \lineii{2}{Day of month (one-based)}
! \lineii{3}{Hours (zero-based)}
! \lineii{4}{Minutes (zero-based)}
! \lineii{5}{Seconds (zero-based)}
! \end{tableii}
! \end{memberdesc}
!
! \begin{memberdesc}[ZipInfo]{compress_type}
! Type of compression for the archive member.
! \end{memberdesc}
!
! \begin{memberdesc}[ZipInfo]{comment}
! Comment for the individual archive member.
! \end{memberdesc}
!
! \begin{memberdesc}[ZipInfo]{extra}
! Expansion field data. The
! \citetitle[http://www.pkware.com/appnote.html]{PKZIP Application
! Note} contains some comments on the internal structure of the data
! contained in this string.
! \end{memberdesc}
!
! \begin{memberdesc}[ZipInfo]{create_system}
! System which created ZIP archive.
! \end{memberdesc}
!
! \begin{memberdesc}[ZipInfo]{create_version}
! PKZIP version which created ZIP archive.
! \end{memberdesc}
!
! \begin{memberdesc}[ZipInfo]{extract_version}
! PKZIP version needed to extract archive.
! \end{memberdesc}
!
! \begin{memberdesc}[ZipInfo]{reserved}
! Must be zero.
! \end{memberdesc}
!
! \begin{memberdesc}[ZipInfo]{flag_bits}
! ZIP flag bits.
! \end{memberdesc}
!
! \begin{memberdesc}[ZipInfo]{volume}
! Volume number of file header.
! \end{memberdesc}
!
! \begin{memberdesc}[ZipInfo]{internal_attr}
! Internal attributes.
! \end{memberdesc}
!
! \begin{memberdesc}[ZipInfo]{external_attr}
! External file attributes.
! \end{memberdesc}
!
! \begin{memberdesc}[ZipInfo]{header_offset}
! Byte offset to the file header.
! \end{memberdesc}
!
! \begin{memberdesc}[ZipInfo]{file_offset}
! Byte offset to the start of the file data.
! \end{memberdesc}
!
! \begin{memberdesc}[ZipInfo]{CRC}
! CRC-32 of the uncompressed file.
! \end{memberdesc}
!
! \begin{memberdesc}[ZipInfo]{compress_size}
! Size of the compressed data.
! \end{memberdesc}
!
! \begin{memberdesc}[ZipInfo]{file_size}
! Size of the uncompressed file.
! \end{memberdesc}