mirror of https://github.com/python/cpython
153 lines
6.1 KiB
TeX
153 lines
6.1 KiB
TeX
\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, 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}}}
|
|
\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}
|