diff options
Diffstat (limited to 'Doc/lib/libshutil.tex')
| -rw-r--r-- | Doc/lib/libshutil.tex | 152 |
1 files changed, 0 insertions, 152 deletions
diff --git a/Doc/lib/libshutil.tex b/Doc/lib/libshutil.tex deleted file mode 100644 index c5a28a0..0000000 --- a/Doc/lib/libshutil.tex +++ /dev/null @@ -1,152 +0,0 @@ -\section{\module{shutil} --- - High-level file operations} - -\declaremodule{standard}{shutil} -\modulesynopsis{High-level file operations, including copying.} -\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} -% partly based on the docstrings - - -The \module{shutil} module offers a number of high-level operations on -files and collections of files. In particular, functions are provided -which support file copying and removal. -\index{file!copying} -\index{copying files} - -\strong{Caveat:} On MacOS, the resource fork and other metadata are -not used. For file copies, this means that resources will be lost and -file type and creator codes will not be correct. - - -\begin{funcdesc}{copyfile}{src, dst} - Copy the contents of the file named \var{src} to a file named - \var{dst}. The destination location must be writable; otherwise, - an \exception{IOError} exception will be raised. - If \var{dst} already exists, it will be replaced. - Special files such as character or block devices - and pipes cannot be copied with this function. \var{src} and - \var{dst} are path names given as strings. -\end{funcdesc} - -\begin{funcdesc}{copyfileobj}{fsrc, fdst\optional{, length}} - Copy the contents of the file-like object \var{fsrc} to the - file-like object \var{fdst}. The integer \var{length}, if given, - is the buffer size. In particular, a negative \var{length} value - means to copy the data without looping over the source data in - chunks; by default the data is read in chunks to avoid uncontrolled - memory consumption. Note that if the current file position of the - \var{fsrc} object is not 0, only the contents from the current file - position to the end of the file will be copied. -\end{funcdesc} - -\begin{funcdesc}{copymode}{src, dst} - Copy the permission bits from \var{src} to \var{dst}. The file - contents, owner, and group are unaffected. \var{src} and \var{dst} - are path names given as strings. -\end{funcdesc} - -\begin{funcdesc}{copystat}{src, dst} - Copy the permission bits, last access time, last modification time, - and flags from \var{src} to \var{dst}. The file contents, owner, and - group are unaffected. \var{src} and \var{dst} are path names given - as strings. -\end{funcdesc} - -\begin{funcdesc}{copy}{src, dst} - Copy the file \var{src} to the file or directory \var{dst}. If - \var{dst} is a directory, a file with the same basename as \var{src} - is created (or overwritten) in the directory specified. Permission - bits are copied. \var{src} and \var{dst} are path names given as - strings. -\end{funcdesc} - -\begin{funcdesc}{copy2}{src, dst} - Similar to \function{copy()}, but last access time and last - modification time are copied as well. This is similar to the - \UNIX{} command \program{cp} \programopt{-p}. -\end{funcdesc} - -\begin{funcdesc}{copytree}{src, dst\optional{, symlinks}} - Recursively copy an entire directory tree rooted at \var{src}. The - destination directory, named by \var{dst}, must not already exist; - it will be created as well as missing parent directories. - Permissions and times of directories are copied with \function{copystat()}, - individual files are copied using \function{copy2()}. - If \var{symlinks} is true, symbolic links in - the source tree are represented as symbolic links in the new tree; - if false or omitted, the contents of the linked files are copied to - the new tree. If exception(s) occur, an \exception{Error} is raised - with a list of reasons. - - The source code for this should be considered an example rather than - a tool. - - \versionchanged[\exception{Error} is raised if any exceptions occur during - copying, rather than printing a message]{2.3} - - \versionchanged[Create intermediate directories needed to create \var{dst}, - rather than raising an error. Copy permissions and times of - directories using \function{copystat()}]{2.5} - -\end{funcdesc} - -\begin{funcdesc}{rmtree}{path\optional{, ignore_errors\optional{, onerror}}} - \index{directory!deleting} - Delete an entire directory tree (\var{path} must point to a directory). - If \var{ignore_errors} is true, errors resulting from failed removals - will be ignored; if false or omitted, such errors are handled by - calling a handler specified by \var{onerror} or, if that is omitted, - they raise an exception. - - If \var{onerror} is provided, it must be a callable that accepts - three parameters: \var{function}, \var{path}, and \var{excinfo}. - The first parameter, \var{function}, is the function which raised - the exception; it will be \function{os.listdir()}, \function{os.remove()} or - \function{os.rmdir()}. The second parameter, \var{path}, will be - the path name passed to \var{function}. The third parameter, - \var{excinfo}, will be the exception information return by - \function{sys.exc_info()}. Exceptions raised by \var{onerror} will - not be caught. -\end{funcdesc} - -\begin{funcdesc}{move}{src, dst} -Recursively move a file or directory to another location. - -If the destination is on our current filesystem, then simply use -rename. Otherwise, copy src to the dst and then remove src. - -\versionadded{2.3} -\end{funcdesc} - -\begin{excdesc}{Error} -This exception collects exceptions that raised during a mult-file -operation. For \function{copytree}, the exception argument is a -list of 3-tuples (\var{srcname}, \var{dstname}, \var{exception}). - -\versionadded{2.3} -\end{excdesc} - -\subsection{Example \label{shutil-example}} - -This example is the implementation of the \function{copytree()} -function, described above, with the docstring omitted. It -demonstrates many of the other functions provided by this module. - -\begin{verbatim} -def copytree(src, dst, symlinks=0): - names = os.listdir(src) - os.mkdir(dst) - for name in names: - srcname = os.path.join(src, name) - dstname = os.path.join(dst, name) - try: - if symlinks and os.path.islink(srcname): - linkto = os.readlink(srcname) - os.symlink(linkto, dstname) - elif os.path.isdir(srcname): - copytree(srcname, dstname, symlinks) - else: - copy2(srcname, dstname) - except (IOError, os.error), why: - print "Can't copy %s to %s: %s" % (`srcname`, `dstname`, str(why)) -\end{verbatim} |