Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libtarfile.tex @ 27998:e27f58a50737 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
SF bug #690377: Dud footnote reference in distutils docs
author Raymond Hettinger <python@rcn.com>
date Fri, 21 Feb 2003 02:47:09 +0000
parents f9a5ed092660
children 604830f1caa6
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
27098
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
1 \section{\module{tarfile} --- Read and write tar archive files}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
2
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
3 \declaremodule{standard}{tarfile}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
4 \modulesynopsis{Read and write tar-format archive files.}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
5 \versionadded{2.3}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
6
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
7 \moduleauthor{Lars Gust\"abel}{lars@gustaebel.de}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
8 \sectionauthor{Lars Gust\"abel}{lars@gustaebel.de}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
9
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
10 The \module{tarfile} module makes it possible to read and create tar archives.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
11 Some facts and figures:
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
12
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
13 \begin{itemize}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
14 \item reads and writes \module{gzip} and \module{bzip2} compressed archives.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
15 \item creates POSIX 1003.1-1990 compliant or GNU tar compatible archives.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
16 \item reads GNU tar extensions \emph{longname}, \emph{longlink} and
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
17 \emph{sparse}.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
18 \item stores pathnames of unlimited length using GNU tar extensions.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
19 \item handles directories, regular files, hardlinks, symbolic links, fifos,
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
20 character devices and block devices and is able to acquire and
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
21 restore file information like timestamp, access permissions and owner.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
22 \item can handle tape devices.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
23 \end{itemize}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
24
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
25 \begin{funcdesc}{open}{\optional{name\optional{, mode
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
26 \optional{, fileobj\optional{, bufsize}}}}}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
27 Return a \class{TarFile} object for the pathname \var{name}.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
28 For detailed information on \class{TarFile} objects,
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
29 see \citetitle{TarFile Objects} (section \ref{tarfile-objects}).
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
30
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
31 \var{mode} has to be a string of the form \code{'filemode[:compression]'},
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
32 it defaults to \code{'r'}. Here is a full list of mode combinations:
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
33
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
34 \begin{tableii}{c|l}{code}{mode}{action}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
35 \lineii{'r'}{Open for reading with transparent compression (recommended).}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
36 \lineii{'r:'}{Open for reading exclusively without compression.}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
37 \lineii{'r:gz'}{Open for reading with gzip compression.}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
38 \lineii{'r:bz2'}{Open for reading with bzip2 compression.}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
39 \lineii{'a' or 'a:'}{Open for appending with no compression.}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
40 \lineii{'w' or 'w:'}{Open for uncompressed writing.}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
41 \lineii{'w:gz'}{Open for gzip compressed writing.}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
42 \lineii{'w:bz2'}{Open for bzip2 compressed writing.}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
43 \end{tableii}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
44
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
45 Note that \code{'a:gz'} or \code{'a:bz2'} is not possible.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
46 If \var{mode} is not suitable to open a certain (compressed) file for
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
47 reading, \exception{ReadError} is raised. Use \var{mode} \code{'r'} to
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
48 avoid this. If a compression method is not supported,
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
49 \exception{CompressionError} is raised.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
50
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
51 If \var{fileobj} is specified, it is used as an alternative to
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
52 a file object opened for \var{name}.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
53
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
54 For special purposes, there is a second format for \var{mode}:
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
55 \code{'filemode|[compression]'}. \code{open} will return a \class{TarFile}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
56 object that processes its data as a stream of blocks. No random
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
57 seeking will be done on the file. If given, \var{fileobj} may be any
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
58 object that has a \code{read()} resp. \code{write()} method.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
59 \var{bufsize} specifies the blocksize and defaults to \code{20 * 512}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
60 bytes. Use this variant in combination with e.g. \code{sys.stdin}, a socket
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
61 file object or a tape device.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
62 However, such a \class{TarFile} object is limited in that it does not allow
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
63 to be accessed randomly, see \citetitle{Examples} (section
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
64 \ref{tar-examples}).
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
65 The currently possible modes:
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
66
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
67 \begin{tableii}{c|l}{code}{mode}{action}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
68 \lineii{'r|'}{Open a \emph{stream} of uncompressed tar blocks for reading.}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
69 \lineii{'r|gz'}{Open a gzip compressed \emph{stream} for reading.}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
70 \lineii{'r|bz2'}{Open a bzip2 compressed \emph{stream} for reading.}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
71 \lineii{'w|'}{Open an uncompressed \emph{stream} for writing.}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
72 \lineii{'w|gz'}{Open an gzip compressed \emph{stream} for writing.}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
73 \lineii{'w|bz2'}{Open an bzip2 compressed \emph{stream} for writing.}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
74 \end{tableii}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
75 \end{funcdesc}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
76
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
77 \begin{classdesc*}{TarFile}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
78 Class for reading and writing tar archives. Do not use this
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
79 class directly, better use \function{open()} instead.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
80 See \citetitle{TarFile Objects} (section \ref{tarfile-objects}).
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
81 \end{classdesc*}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
82
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
83 \begin{funcdesc}{is_tarfile}{name}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
84 Return \code{True} if \var{name} is a tar archive file, that the
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
85 \module{tarfile} module can read.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
86 \end{funcdesc}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
87
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
88 \begin{classdesc}{TarFileCompat}{filename\optional{, mode\optional{,
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
89 compression}}}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
90
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
91 Class for limited access to tar archives with a \code{zipfile}-like
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
92 interface. Please consult the documentation of \code{zipfile} for more
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
93 details.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
94 \code{compression} must be one of the following constants:
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
95 \begin{datadesc}{TAR_PLAIN}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
96 Constant for an uncompressed tar archive.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
97 \end{datadesc}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
98 \begin{datadesc}{TAR_GZIPPED}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
99 Constant for a \code{gzip} compressed tar archive.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
100 \end{datadesc}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
101 \end{classdesc}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
102
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
103 \begin{excdesc}{TarError}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
104 Base class for all \module{tarfile} exceptions.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
105 \end{excdesc}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
106
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
107 \begin{excdesc}{ReadError}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
108 Is raised when a tar archive is opened, that either cannot be handled by
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
109 the \module{tarfile} module or is somehow invalid.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
110 \end{excdesc}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
111
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
112 \begin{excdesc}{CompressionError}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
113 Is raised when a compression method is not supported or when the data
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
114 cannot be decoded properly.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
115 \end{excdesc}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
116
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
117 \begin{excdesc}{StreamError}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
118 Is raised for the limitations that are typical for stream-like
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
119 \class{TarFile} objects.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
120 \end{excdesc}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
121
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
122 \begin{excdesc}{ExtractError}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
123 Is raised for \emph{non-fatal} errors when using \method{extract()}, but
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
124 only if \member{TarFile.errorlevel}\code{ == 2}.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
125 \end{excdesc}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
126
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
127 \begin{seealso}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
128 \seemodule[module-zipfile]{zipfile}{Documentation of the \code{zipfile}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
129 standard module.}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
130
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
131 \seetitle[http://www.gnu.org/manual/tar/html_chapter/tar_8.html\#SEC118]
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
132 {GNU tar manual, Standard Section}{Documentation for tar archive files,
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
133 including GNU tar extensions.}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
134 \end{seealso}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
135
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
136 %-----------------
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
137 % TarFile Objects
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
138 %-----------------
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
139
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
140 \subsection{TarFile Objects \label{tarfile-objects}}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
141
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
142 The \class{TarFile} object provides an interface to a tar archive. A tar
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
143 archive is a sequence of blocks. An archive member (a stored file) is made up
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
144 of a header block followed by data blocks. It is possible, to store a file in a
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
145 tar archive several times. Each archive member is represented by a
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
146 \class{TarInfo} object, see \citetitle{TarInfo Objects} (section
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
147 \ref{tarinfo-objects}) for details.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
148
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
149 \begin{classdesc}{TarFile}{\optional{name
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
150 \optional{, mode\optional{, fileobj}}}}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
151 Open an \emph{(uncompressed)} tar archive \var{name}.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
152 \var{mode} is either \code{'r'} to read from an existing archive,
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
153 \code{'a'} to append data to an existing file or \code{'w'} to create a new
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
154 file overwriting an existing one. \var{mode} defaults to \code{'r'}.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
155
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
156 If \var{fileobj} is given, it is used for reading or writing data.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
157 If it can be determined, \var{mode} is overridden by \var{fileobj}'s mode.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
158 \begin{notice}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
159 \var{fileobj} is not closed, when \class{TarFile} is closed.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
160 \end{notice}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
161 \end{classdesc}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
162
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
163 \begin{methoddesc}{open}{...}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
164 Alternative constructor. The \function{open()} function on module level is
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
165 actually a shortcut to this classmethod. See section \ref{module-tarfile}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
166 for details.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
167 \end{methoddesc}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
168
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
169 \begin{methoddesc}{getmember}{name}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
170 Return a \class{TarInfo} object for member \var{name}. If \var{name} can
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
171 not be found in the archive, \exception{KeyError} is raised.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
172 \begin{notice}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
173 If a member occurs more than once in the archive, its last
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
174 occurence is assumed to be the most up-to-date version.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
175 \end{notice}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
176 \end{methoddesc}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
177
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
178 \begin{methoddesc}{getmembers}{}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
179 Return the members of the archive as a list of \class{TarInfo} objects.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
180 The list has the same order as the members in the archive.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
181 \end{methoddesc}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
182
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
183 \begin{methoddesc}{getnames}{}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
184 Return the members as a list of their names. It has the same order as
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
185 the list returned by \method{getmembers()}.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
186 \end{methoddesc}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
187
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
188 \begin{methoddesc}{list}{verbose=True}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
189 Print a table of contents to \code{sys.stdout}. If \var{verbose} is
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
190 \code{False}, only the names of the members are printed. If it is
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
191 \code{True}, an \code{"ls -l"}-like output is produced.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
192 \end{methoddesc}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
193
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
194 \begin{methoddesc}{next}{}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
195 Return the next member of the archive as a \class{TarInfo} object, when
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
196 \class{TarFile} is opened for reading. Return \code{None} if there is no
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
197 more available.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
198 \end{methoddesc}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
199
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
200 \begin{methoddesc}{extract}{member\optional{, path}}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
201 Extract a member from the archive to the current working directory,
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
202 using its full name. Its file information is extracted as accurately as
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
203 possible.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
204 \var{member} may be a filename or a \class{TarInfo} object.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
205 You can specify a different directory using \var{path}.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
206 \end{methoddesc}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
207
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
208 \begin{methoddesc}{extractfile}{member}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
209 Extract a member from the archive as a file object.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
210 \var{member} may be a filename or a \class{TarInfo} object.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
211 If \var{member} is a regular file, a file-like object is returned.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
212 If \var{member} is a link, a file-like object is constructed from the
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
213 link's target.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
214 If \var{member} is none of the above, \code{None} is returned.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
215 \begin{notice}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
216 The file-like object is read-only and provides the following methods:
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
217 \method{read()}, \method{readline()}, \method{readlines()},
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
218 \method{seek()}, \method{tell()}.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
219 \end{notice}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
220 \end{methoddesc}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
221
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
222 \begin{methoddesc}{add}{name\optional{, arcname\optional{, recursive=True}}}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
223 Add the file \var{name} to the archive. \var{name} may be any type
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
224 of file (directory, fifo, symbolic link, etc.).
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
225 If given, \var{arcname} specifies an alternative name for the file in the
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
226 archive. Directories are added recursively by default.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
227 This can be avoided by setting \var{recursive} to \code{False}.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
228 \end{methoddesc}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
229
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
230 \begin{methoddesc}{addfile}{tarinfo\optional{, fileobj}}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
231 Add the \class{TarInfo} object \var{tarinfo} to the archive.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
232 If \var{fileobj} is given, \code{tarinfo.size} bytes are read
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
233 from it and added to the archive. You can create \class{TarInfo} objects
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
234 using \method{gettarinfo()}.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
235 \begin{notice}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
236 On Windows platforms, \var{fileobj} should always be opened with mode
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
237 \code{'rb'} to avoid irritation about the file size.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
238 \end{notice}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
239 \end{methoddesc}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
240
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
241 \begin{methoddesc}{gettarinfo}{\optional{name\optional{, arcname
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
242 \optional{, fileobj}}}}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
243 Create a \class{TarInfo} object for either the file \var{name} or the
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
244 file object \var{fileobj} (using \code{os.fstat()} on its file descriptor).
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
245 You can modify some of the \class{TarInfo}'s attributes before you add it
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
246 using \method{addfile()}.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
247 If given, \var{arcname} specifies an alternative name for the file in the
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
248 archive.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
249 \end{methoddesc}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
250
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
251 \begin{methoddesc}{close}{}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
252 Close the \class{TarFile}. In write-mode, two finishing zero blocks are
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
253 appended to the archive.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
254 \end{methoddesc}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
255
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
256 \begin{memberdesc}{posix=True}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
257 If \code{True}, create a POSIX 1003.1-1990 compliant archive. GNU
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
258 extensions are not used, because they are not part of the POSIX standard.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
259 This limits the length of filenames to at most 256 and linknames to 100
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
260 characters. A \exception{ValueError} is raised, if a pathname exceeds this
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
261 limit.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
262 If \code{False}, create a GNU tar compatible archive. It will not be POSIX
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
263 compliant, but can store pathnames of unlimited length.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
264 \end{memberdesc}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
265
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
266 \begin{memberdesc}{dereference=False}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
267 If \code{False}, add symbolic and hard links to archive. If \code{True},
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
268 add the content of the target files to the archive. This has no effect on
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
269 systems that do not support links.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
270 \end{memberdesc}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
271
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
272 \begin{memberdesc}{ignore_zeros=False}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
273 If \code{False}, treat an empty block as the end of the archive. If
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
274 \code{True}, skip empty (and invalid) blocks and try to get as many
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
275 members as possible. This is only useful for concatenated or damaged
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
276 archives.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
277 \end{memberdesc}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
278
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
279 \begin{memberdesc}{debug=0}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
280 To be set from \code{0}(no debug messages) up to \code{3}(all debug
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
281 messages). The messages are written to \code{sys.stdout}.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
282 \end{memberdesc}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
283
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
284 \begin{memberdesc}{errorlevel=0}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
285 If \code{0}, all errors are ignored when using \method{extract()}.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
286 Nevertheless, they appear as error messages in the debug output, when
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
287 debugging is enabled.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
288 If \code{1}, all \emph{fatal} errors are raised as \exception{OSError}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
289 or \exception{IOError} exceptions.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
290 If \code{2}, all \emph{non-fatal} errors are raised as \exception{TarError}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
291 exceptions as well.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
292 \end{memberdesc}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
293
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
294 %-----------------
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
295 % TarInfo Objects
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
296 %-----------------
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
297
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
298 \subsection{TarInfo Objects \label{tarinfo-objects}}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
299
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
300 A \class{TarInfo} object represents one member in a \class{TarFile}. Aside from
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
301 storing all required attributes of a file (like file type, size, time,
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
302 permissions, owner etc.), it provides some useful methods to determine its
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
303 type. It does \emph{not} contain the file's data itself.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
304
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
305 \class{TarInfo} objects are returned by \code{TarFile}'s methods
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
306 \code{getmember()}, \code{getmembers()} and \code{gettarinfo()}.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
307
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
308 \begin{classdesc}{TarInfo}{\optional{name}}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
309 Create a \class{TarInfo} object.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
310 \end{classdesc}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
311
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
312 \begin{methoddesc}{frombuf}{}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
313 Create and return a \class{TarInfo} object from a string buffer.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
314 \end{methoddesc}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
315
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
316 \begin{methoddesc}{tobuf}{}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
317 Create a string buffer from a \class{TarInfo} object.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
318 \end{methoddesc}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
319
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
320 A \code{TarInfo} object has the following public data attributes:
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
321 \begin{memberdesc}{name}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
322 Name of the archive member.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
323 \end{memberdesc}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
324
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
325 \begin{memberdesc}{size}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
326 Size in bytes.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
327 \end{memberdesc}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
328
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
329 \begin{memberdesc}{mtime}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
330 Time of last modification.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
331 \end{memberdesc}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
332
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
333 \begin{memberdesc}{mode}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
334 Permission bits.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
335 \end{memberdesc}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
336
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
337 \begin{memberdesc}{type}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
338 File type.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
339 \var{type} is usually one of these constants:
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
340 \code{REGTYPE, AREGTYPE, LNKTYPE, SYMTYPE, DIRTYPE, FIFOTYPE, CONTTYPE,
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
341 CHRTYPE, BLKTYPE, GNUTYPE_SPARSE}.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
342 To determine the type of a \class{TarInfo} object more conveniently, use
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
343 the \code{is_*()} methods below.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
344 \end{memberdesc}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
345
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
346 \begin{memberdesc}{linkname}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
347 Name of the target file name, which is only present in \class{TarInfo}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
348 objects of type LNKTYPE and SYMTYPE.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
349 \end{memberdesc}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
350
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
351 \begin{memberdesc}{uid, gid}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
352 User and group ID of who originally stored this member.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
353 \end{memberdesc}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
354
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
355 \begin{memberdesc}{uname, gname}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
356 User and group name.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
357 \end{memberdesc}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
358
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
359 A \class{TarInfo} object also provides some convenient query methods:
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
360 \begin{methoddesc}{isfile}{}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
361 Return \code{True} if the \class{Tarinfo} object is a regular file.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
362 \end{methoddesc}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
363
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
364 \begin{methoddesc}{isreg}{}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
365 Same as \method{isfile()}.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
366 \end{methoddesc}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
367
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
368 \begin{methoddesc}{isdir}{}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
369 Return \code{True} if it is a directory.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
370 \end{methoddesc}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
371
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
372 \begin{methoddesc}{issym}{}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
373 Return \code{True} if it is a symbolic link.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
374 \end{methoddesc}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
375
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
376 \begin{methoddesc}{islnk}{}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
377 Return \code{True} if it is a hard link.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
378 \end{methoddesc}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
379
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
380 \begin{methoddesc}{ischr}{}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
381 Return \code{True} if it is a character device.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
382 \end{methoddesc}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
383
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
384 \begin{methoddesc}{isblk}{}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
385 Return \code{True} if it is a block device.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
386 \end{methoddesc}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
387
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
388 \begin{methoddesc}{isfifo}{}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
389 Return \code{True} if it is a FIFO.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
390 \end{methoddesc}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
391
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
392 \begin{methoddesc}{isdev}{}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
393 Return \code{True} if it is one of character device, block device or FIFO.
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
394 \end{methoddesc}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
395
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
396 %------------------------
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
397 % Examples
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
398 %------------------------
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
399
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
400 \subsection{Examples \label{tar-examples}}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
401
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
402 How to create an uncompressed tar archive from a list of filenames:
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
403 \begin{verbatim}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
404 import tarfile
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
405 tar = tarfile.open("sample.tar", "w")
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
406 for name in ["foo", "bar", "quux"]:
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
407 tar.add(name)
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
408 tar.close()
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
409 \end{verbatim}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
410
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
411 How to read a gzip compressed tar archive and display some member information:
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
412 \begin{verbatim}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
413 import tarfile
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
414 tar = tarfile.open("sample.tar.gz", "r:gz")
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
415 for tarinfo in tar:
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
416 print tarinfo.name, "is", tarinfo.size, "bytes in size and is",
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
417 if tarinfo.isreg():
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
418 print "a regular file."
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
419 elif tarinfo.isdir():
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
420 print "a directory."
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
421 else:
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
422 print "something else."
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
423 tar.close()
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
424 \end{verbatim}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
425
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
426 How to create a tar archive with faked information:
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
427 \begin{verbatim}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
428 import tarfile
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
429 tar = tarfile.open("sample.tar.gz", "w:gz")
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
430 for name in namelist:
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
431 tarinfo = tar.gettarinfo(name, "fakeproj-1.0/" + name)
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
432 tarinfo.uid = 123
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
433 tarinfo.gid = 456
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
434 tarinfo.uname = "johndoe"
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
435 tarinfo.gname = "fake"
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
436 tar.addfile(tarinfo, file(name))
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
437 tar.close()
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
438 \end{verbatim}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
439
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
440 The \emph{only} way to extract an uncompressed tar stream from
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
441 \code{sys.stdin}:
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
442 \begin{verbatim}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
443 import sys
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
444 import tarfile
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
445 tar = tarfile.open(mode="r|", fileobj=sys.stdin)
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
446 for tarinfo in tar:
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
447 tar.extract(tarinfo)
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
448 tar.close()
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
449 \end{verbatim}
f9a5ed092660 SF #651082, tarfile module implementation from Lars Gustäbel
Neal Norwitz <nnorwitz@gmail.com>
parents:
diff changeset
450