[Python-checkins] python/dist/src/Doc/lib libtarfile.tex,1.2,1.3

Tue Jan 13 18:41:34 EST 2004

Update of /cvsroot/python/python/dist/src/Doc/lib
In directory sc8-pr-cvs1:/tmp/cvs-serv26169
Modified Files:
	libtarfile.tex 
Log Message:
markup changes
Index: libtarfile.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libtarfile.tex,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** libtarfile.tex	12 Oct 2003 02:02:16 -0000	1.2
--- libtarfile.tex	13 Jan 2004 23:41:32 -0000	1.3
***************
*** 13,17 ****
 \begin{itemize}
 \item reads and writes \module{gzip} and \module{bzip2} compressed archives.
! \item creates POSIX 1003.1-1990 compliant or GNU tar compatible archives.
 \item reads GNU tar extensions \emph{longname}, \emph{longlink} and
 \emph{sparse}.
--- 13,17 ----
 \begin{itemize}
 \item reads and writes \module{gzip} and \module{bzip2} compressed archives.
! \item creates \POSIX{} 1003.1-1990 compliant or GNU tar compatible archives.
 \item reads GNU tar extensions \emph{longname}, \emph{longlink} and
 \emph{sparse}.
***************
*** 53,69 ****

 For special purposes, there is a second format for \var{mode}:
! \code{'filemode|[compression]'}. \code{open} will return a \class{TarFile}
! object that processes its data as a stream of blocks. No random
! seeking will be done on the file. If given, \var{fileobj} may be any
! object that has a \code{read()} resp. \code{write()} method.
! \var{bufsize} specifies the blocksize and defaults to \code{20 * 512}
! bytes. Use this variant in combination with e.g. \code{sys.stdin}, a socket
! file object or a tape device.
! However, such a \class{TarFile} object is limited in that it does not allow
! to be accessed randomly, see \citetitle{Examples} (section
! \ref{tar-examples}).
! The currently possible modes:

! \begin{tableii}{c|l}{code}{mode}{action}
 \lineii{'r|'}{Open a \emph{stream} of uncompressed tar blocks for reading.}
 \lineii{'r|gz'}{Open a gzip compressed \emph{stream} for reading.}
--- 53,69 ----

 For special purposes, there is a second format for \var{mode}:
! \code{'filemode|[compression]'}. \function{open()} will return a
! \class{TarFile} object that processes its data as a stream of
! blocks. No random seeking will be done on the file. If given,
! \var{fileobj} may be any object that has a \method{read()} or
! \method{write()} method (depending on the \var{mode}).
! \var{bufsize} specifies the blocksize and defaults to \code{20 *
! 512} bytes. Use this variant in combination with
! e.g. \code{sys.stdin}, a socket file object or a tape device.
! However, such a \class{TarFile} object is limited in that it does
! not allow to be accessed randomly, see ``Examples''
! (section~\ref{tar-examples}). The currently possible modes:

! \begin{tableii}{c|l}{code}{Mode}{Action}
 \lineii{'r|'}{Open a \emph{stream} of uncompressed tar blocks for reading.}
 \lineii{'r|gz'}{Open a gzip compressed \emph{stream} for reading.}
***************
*** 78,101 ****
 Class for reading and writing tar archives. Do not use this
 class directly, better use \function{open()} instead.
! See \citetitle{TarFile Objects} (section \ref{tarfile-objects}).
 \end{classdesc*}

 \begin{funcdesc}{is_tarfile}{name}
! Return \code{True} if \var{name} is a tar archive file, that the
! \module{tarfile} module can read.
 \end{funcdesc}

 \begin{classdesc}{TarFileCompat}{filename\optional{, mode\optional{,
! compression}}}
! 
! Class for limited access to tar archives with a \code{zipfile}-like
! interface. Please consult the documentation of \code{zipfile} for more
! details.
! \code{compression} must be one of the following constants:
 \begin{datadesc}{TAR_PLAIN}
 Constant for an uncompressed tar archive.
 \end{datadesc}
 \begin{datadesc}{TAR_GZIPPED}
! Constant for a \code{gzip} compressed tar archive.
 \end{datadesc}
 \end{classdesc}
--- 78,100 ----
 Class for reading and writing tar archives. Do not use this
 class directly, better use \function{open()} instead.
! See ``TarFile Objects'' (section~\ref{tarfile-objects}).
 \end{classdesc*}

 \begin{funcdesc}{is_tarfile}{name}
! Return \constant{True} if \var{name} is a tar archive file, that
! the \module{tarfile} module can read.
 \end{funcdesc}

 \begin{classdesc}{TarFileCompat}{filename\optional{, mode\optional{,
! compression}}}
! Class for limited access to tar archives with a
! \refmodule{zipfile}-like interface. Please consult the
! documentation of the \refmodule{zipfile} module for more details.
! \var{compression} must be one of the following constants:
 \begin{datadesc}{TAR_PLAIN}
 Constant for an uncompressed tar archive.
 \end{datadesc}
 \begin{datadesc}{TAR_GZIPPED}
! Constant for a \refmodule{gzip} compressed tar archive.
 \end{datadesc}
 \end{classdesc}
***************
*** 126,130 ****

 \begin{seealso}
! \seemodule{zipfile}{Documentation of the \code{zipfile}
 standard module.}

--- 125,129 ----

 \begin{seealso}
! \seemodule{zipfile}{Documentation of the \refmodule{zipfile}
 standard module.}

***************
*** 163,167 ****
 \begin{methoddesc}{open}{...}
 Alternative constructor. The \function{open()} function on module level is
! actually a shortcut to this classmethod. See section \ref{module-tarfile}
 for details.
 \end{methoddesc}
--- 162,166 ----
 \begin{methoddesc}{open}{...}
 Alternative constructor. The \function{open()} function on module level is
! actually a shortcut to this classmethod. See section~\ref{module-tarfile}
 for details.
 \end{methoddesc}
***************
*** 188,193 ****
 \begin{methoddesc}{list}{verbose=True}
 Print a table of contents to \code{sys.stdout}. If \var{verbose} is
! \code{False}, only the names of the members are printed. If it is
! \code{True}, an \code{"ls -l"}-like output is produced.
 \end{methoddesc}

--- 187,192 ----
 \begin{methoddesc}{list}{verbose=True}
 Print a table of contents to \code{sys.stdout}. If \var{verbose} is
! \constant{False}, only the names of the members are printed. If it is
! \constant{True}, output similar to that of \program{ls -l} is produced.
 \end{methoddesc}

***************
*** 220,234 ****
 \end{methoddesc}

! \begin{methoddesc}{add}{name\optional{, arcname\optional{, recursive=True}}}
 Add the file \var{name} to the archive. \var{name} may be any type
 of file (directory, fifo, symbolic link, etc.).
 If given, \var{arcname} specifies an alternative name for the file in the
 archive. Directories are added recursively by default.
! This can be avoided by setting \var{recursive} to \code{False}.
 \end{methoddesc}

 \begin{methoddesc}{addfile}{tarinfo\optional{, fileobj}}
 Add the \class{TarInfo} object \var{tarinfo} to the archive.
! If \var{fileobj} is given, \code{tarinfo.size} bytes are read
 from it and added to the archive. You can create \class{TarInfo} objects
 using \method{gettarinfo()}.
--- 219,234 ----
 \end{methoddesc}

! \begin{methoddesc}{add}{name\optional{, arcname\optional{, recursive}}}
 Add the file \var{name} to the archive. \var{name} may be any type
 of file (directory, fifo, symbolic link, etc.).
 If given, \var{arcname} specifies an alternative name for the file in the
 archive. Directories are added recursively by default.
! This can be avoided by setting \var{recursive} to \constant{False};
! the default is \constant{True}.
 \end{methoddesc}

 \begin{methoddesc}{addfile}{tarinfo\optional{, fileobj}}
 Add the \class{TarInfo} object \var{tarinfo} to the archive.
! If \var{fileobj} is given, \code{\var{tarinfo}.size} bytes are read
 from it and added to the archive. You can create \class{TarInfo} objects
 using \method{gettarinfo()}.
***************
*** 239,293 ****
 \end{methoddesc}

! \begin{methoddesc}{gettarinfo}{\optional{name\optional{, arcname
! \optional{, fileobj}}}}
! Create a \class{TarInfo} object for either the file \var{name} or the
! file object \var{fileobj} (using \code{os.fstat()} on its file descriptor).
! You can modify some of the \class{TarInfo}'s attributes before you add it
! using \method{addfile()}.
! If given, \var{arcname} specifies an alternative name for the file in the
 archive.
 \end{methoddesc}

 \begin{methoddesc}{close}{}
! Close the \class{TarFile}. In write-mode, two finishing zero blocks are
! appended to the archive.
 \end{methoddesc}

! \begin{memberdesc}{posix=True}
! If \code{True}, create a POSIX 1003.1-1990 compliant archive. GNU
! extensions are not used, because they are not part of the POSIX standard.
! This limits the length of filenames to at most 256 and linknames to 100
! characters. A \exception{ValueError} is raised, if a pathname exceeds this
! limit.
! If \code{False}, create a GNU tar compatible archive. It will not be POSIX
! compliant, but can store pathnames of unlimited length.
 \end{memberdesc}

! \begin{memberdesc}{dereference=False}
! If \code{False}, add symbolic and hard links to archive. If \code{True},
! add the content of the target files to the archive. This has no effect on
! systems that do not support links.
 \end{memberdesc}

! \begin{memberdesc}{ignore_zeros=False}
! If \code{False}, treat an empty block as the end of the archive. If
! \code{True}, skip empty (and invalid) blocks and try to get as many
! members as possible. This is only useful for concatenated or damaged
 archives.
 \end{memberdesc}

 \begin{memberdesc}{debug=0}
! To be set from \code{0}(no debug messages) up to \code{3}(all debug
! messages). The messages are written to \code{sys.stdout}.
 \end{memberdesc}

! \begin{memberdesc}{errorlevel=0}
! If \code{0}, all errors are ignored when using \method{extract()}.
! Nevertheless, they appear as error messages in the debug output, when
! debugging is enabled.
! If \code{1}, all \emph{fatal} errors are raised as \exception{OSError}
! or \exception{IOError} exceptions.
! If \code{2}, all \emph{non-fatal} errors are raised as \exception{TarError}
! exceptions as well.
 \end{memberdesc}

--- 239,293 ----
 \end{methoddesc}

! \begin{methoddesc}{gettarinfo}{\optional{name\optional{,
! arcname\optional{, fileobj}}}}
! Create a \class{TarInfo} object for either the file \var{name} or
! the file object \var{fileobj} (using \function{os.fstat()} on its
! file descriptor). You can modify some of the \class{TarInfo}'s
! attributes before you add it using \method{addfile()}. If given,
! \var{arcname} specifies an alternative name for the file in the
 archive.
 \end{methoddesc}

 \begin{methoddesc}{close}{}
! Close the \class{TarFile}. In write mode, two finishing zero
! blocks are appended to the archive.
 \end{methoddesc}

! \begin{memberdesc}{posix}
! If true, create a \POSIX{} 1003.1-1990 compliant archive. GNU
! extensions are not used, because they are not part of the \POSIX{}
! standard. This limits the length of filenames to at most 256 and
! link names to 100 characters. A \exception{ValueError} is raised
! if a pathname exceeds this limit. If false, create a GNU tar
! compatible archive. It will not be \POSIX{} compliant, but can
! store pathnames of unlimited length.
 \end{memberdesc}

! \begin{memberdesc}{dereference}
! If false, add symbolic and hard links to archive. If true, add the
! content of the target files to the archive. This has no effect on
! systems that do not support symbolic links.
 \end{memberdesc}

! \begin{memberdesc}{ignore_zeros}
! If false, treat an empty block as the end of the archive. If true,
! skip empty (and invalid) blocks and try to get as many members as
! possible. This is only useful for concatenated or damaged
 archives.
 \end{memberdesc}

 \begin{memberdesc}{debug=0}
! To be set from \code{0} (no debug messages; the default) up to
! \code{3} (all debug messages). The messages are written to
! \code{sys.stdout}.
 \end{memberdesc}

! \begin{memberdesc}{errorlevel}
! If \code{0} (the default), all errors are ignored when using
! \method{extract()}. Nevertheless, they appear as error messages
! in the debug output, when debugging is enabled. If \code{1}, all
! \emph{fatal} errors are raised as \exception{OSError} or
! \exception{IOError} exceptions. If \code{2}, all \emph{non-fatal}
! errors are raised as \exception{TarError} exceptions as well.
 \end{memberdesc}

***************
*** 298,308 ****
 \subsection{TarInfo Objects \label{tarinfo-objects}}

! A \class{TarInfo} object represents one member in a \class{TarFile}. Aside from
! storing all required attributes of a file (like file type, size, time,
! permissions, owner etc.), it provides some useful methods to determine its
! type. It does \emph{not} contain the file's data itself.

! \class{TarInfo} objects are returned by \code{TarFile}'s methods
! \code{getmember()}, \code{getmembers()} and \code{gettarinfo()}.

 \begin{classdesc}{TarInfo}{\optional{name}}
--- 298,309 ----
 \subsection{TarInfo Objects \label{tarinfo-objects}}

! A \class{TarInfo} object represents one member in a
! \class{TarFile}. Aside from storing all required attributes of a file
! (like file type, size, time, permissions, owner etc.), it provides
! some useful methods to determine its type. It does \emph{not} contain
! the file's data itself.

! \class{TarInfo} objects are returned by \class{TarFile}'s methods
! \method{getmember()}, \method{getmembers()} and \method{gettarinfo()}.

 \begin{classdesc}{TarInfo}{\optional{name}}
***************
*** 319,322 ****
--- 320,324 ----

 A \code{TarInfo} object has the following public data attributes:
+ 
 \begin{memberdesc}{name}
 Name of the archive member.
***************
*** 336,363 ****

 \begin{memberdesc}{type}
! File type.
! \var{type} is usually one of these constants:
! \code{REGTYPE, AREGTYPE, LNKTYPE, SYMTYPE, DIRTYPE, FIFOTYPE, CONTTYPE,
! CHRTYPE, BLKTYPE, GNUTYPE_SPARSE}.
! To determine the type of a \class{TarInfo} object more conveniently, use
! the \code{is_*()} methods below.
 \end{memberdesc}

 \begin{memberdesc}{linkname}
! Name of the target file name, which is only present in \class{TarInfo}
! objects of type LNKTYPE and SYMTYPE.
 \end{memberdesc}

! \begin{memberdesc}{uid, gid}
! User and group ID of who originally stored this member.
 \end{memberdesc}

! \begin{memberdesc}{uname, gname}
! User and group name.
 \end{memberdesc}

 A \class{TarInfo} object also provides some convenient query methods:
 \begin{methoddesc}{isfile}{}
! Return \code{True} if the \class{Tarinfo} object is a regular file.
 \end{methoddesc}

--- 338,377 ----

 \begin{memberdesc}{type}
! File type. \var{type} is usually one of these constants:
! \constant{REGTYPE}, \constant{AREGTYPE}, \constant{LNKTYPE},
! \constant{SYMTYPE}, \constant{DIRTYPE}, \constant{FIFOTYPE},
! \constant{CONTTYPE}, \constant{CHRTYPE}, \constant{BLKTYPE},
! \constant{GNUTYPE_SPARSE}. To determine the type of a
! \class{TarInfo} object more conveniently, use the \code{is_*()}
! methods below.
 \end{memberdesc}

 \begin{memberdesc}{linkname}
! Name of the target file name, which is only present in
! \class{TarInfo} objects of type \constant{LNKTYPE} and
! \constant{SYMTYPE}.
 \end{memberdesc}

! \begin{memberdesc}{uid}
! User ID of the user who originally stored this member.
 \end{memberdesc}

! \begin{memberdesc}{gid}
! Group ID of the user who originally stored this member.
! \end{memberdesc}
! 
! \begin{memberdesc}{uname}
! User name.
! \end{memberdesc}
! 
! \begin{memberdesc}{gname}
! Group name.
 \end{memberdesc}

 A \class{TarInfo} object also provides some convenient query methods:
+ 
 \begin{methoddesc}{isfile}{}
! Return \constant{True} if the \class{Tarinfo} object is a regular
! file.
 \end{methoddesc}

***************
*** 367,395 ****

 \begin{methoddesc}{isdir}{}
! Return \code{True} if it is a directory.
 \end{methoddesc}

 \begin{methoddesc}{issym}{}
! Return \code{True} if it is a symbolic link.
 \end{methoddesc}

 \begin{methoddesc}{islnk}{}
! Return \code{True} if it is a hard link.
 \end{methoddesc}

 \begin{methoddesc}{ischr}{}
! Return \code{True} if it is a character device.
 \end{methoddesc}

 \begin{methoddesc}{isblk}{}
! Return \code{True} if it is a block device.
 \end{methoddesc}

 \begin{methoddesc}{isfifo}{}
! Return \code{True} if it is a FIFO.
 \end{methoddesc}

 \begin{methoddesc}{isdev}{}
! Return \code{True} if it is one of character device, block device or FIFO.
 \end{methoddesc}

--- 381,410 ----

 \begin{methoddesc}{isdir}{}
! Return \constant{True} if it is a directory.
 \end{methoddesc}

 \begin{methoddesc}{issym}{}
! Return \constant{True} if it is a symbolic link.
 \end{methoddesc}

 \begin{methoddesc}{islnk}{}
! Return \constant{True} if it is a hard link.
 \end{methoddesc}

 \begin{methoddesc}{ischr}{}
! Return \constant{True} if it is a character device.
 \end{methoddesc}

 \begin{methoddesc}{isblk}{}
! Return \constant{True} if it is a block device.
 \end{methoddesc}

 \begin{methoddesc}{isfifo}{}
! Return \constant{True} if it is a FIFO.
 \end{methoddesc}

 \begin{methoddesc}{isdev}{}
! Return \constant{True} if it is one of character device, block
! device or FIFO.
 \end{methoddesc}

***************
*** 448,450 ****
 tar.close()
 \end{verbatim}
- 
--- 463,464 ----