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

fdrake at users.sourceforge.net fdrake at users.sourceforge.net
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 ----





More information about the Python-checkins mailing list