ref: 6184a4ef2eba1d49f0386e9ce94f4877d3d9edb2
dir: /sys/src/cmd/python/Doc/lib/libshutil.tex/
\section{\module{shutil} --- High-level file operations} \declaremodule{standard}{shutil} \modulesynopsis{High-level file operations, including copying.} \sectionauthor{Fred L. Drake, Jr.}{[email protected]} % 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, 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 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}