\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 onfiles 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 arenot 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, and last modification  time 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}}}  Delete an entire directory tree.\index{directory!deleting}  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 userename.  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-fileoperation. For \function{copytree}, the exception argument is alist 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.  Itdemonstrates 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}