[Python-checkins] python/dist/src/Doc/lib libtarfile.tex,1.7,1.8

[loewis at users.sourceforge.net]

Update of /cvsroot/python/python/dist/src/Doc/lib
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv22139/Doc/lib

Modified Files:
	libtarfile.tex 
Log Message:
Patch #1043890: tarfile: add extractall() method.


Index: libtarfile.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libtarfile.tex,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -d -r1.7 -r1.8
--- libtarfile.tex	11 Sep 2004 16:50:05 -0000	1.7
+++ libtarfile.tex	4 Mar 2005 19:40:34 -0000	1.8
@@ -196,12 +196,29 @@
     more available.
 \end{methoddesc}
 
+\begin{methoddesc}{extractall}{\optional{path\optional{, members}}}
+    Extract all members from the archive to the current working directory
+    or directory \var{path}. If optional \var{members} is given, it must be
+    a subset of the list returned by \method{getmembers()}.
+    Directory informations like owner, modification time and permissions are
+    set after all members have been extracted. This is done to work around two
+    problems: A directory's modification time is reset each time a file is
+    created in it. And, if a directory's permissions do not allow writing,
+    extracting files to it will fail.
+    \versionadded{2.5}
+\end{methoddesc}
+
 \begin{methoddesc}{extract}{member\optional{, path}}
     Extract a member from the archive to the current working directory,
     using its full name. Its file information is extracted as accurately as
     possible.
     \var{member} may be a filename or a \class{TarInfo} object.
     You can specify a different directory using \var{path}.
+    \begin{notice}
+    Because the \method{extract()} method allows random access to a tar
+    archive there are some issues you must take care of yourself. See the
+    description for \method{extractall()} above.
+    \end{notice}
 \end{methoddesc}
 
 \begin{methoddesc}{extractfile}{member}
@@ -416,6 +433,14 @@
 
 \subsection{Examples \label{tar-examples}}
 
+How to extract an entire tar archive to the current working directory:
+\begin{verbatim}
+import tarfile
+tar = tarfile.open("sample.tar.gz")
+tar.extractall()
+tar.close()
+\end{verbatim}
+
 How to create an uncompressed tar archive from a list of filenames:
 \begin{verbatim}
 import tarfile