Doc/lib/libshutil.tex

   1 \section{\module{shutil} ---
   2          High-level file operations}
   3
   4 \declaremodule{standard}{shutil}
   5 \modulesynopsis{High-level file operations, including copying.}
   6 \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
   7 % partly based on the docstrings
   8
   9
  10 The \module{shutil} module offers a number of high-level operations on
  11 files and collections of files.  In particular, functions are provided
  12 which support file copying and removal.
  13 \index{file!copying}
  14 \index{copying files}
  15
  16 \strong{Caveat:}  On MacOS, the resource fork and other metadata are
  17 not used.  For file copies, this means that resources will be lost and
  18 file type and creator codes will not be correct.
  19
  20
  21 \begin{funcdesc}{copyfile}{src, dst}
  22   Copy the contents of the file named \var{src} to a file named
  23   \var{dst}.  The destination location must be writable; otherwise,
  24   an \exception{IOError} exception will be raised.
  25   If \var{dst} already exists, it will be replaced.
  26   Special files such as character or block devices
  27   and pipes cannot be copied with this function.  \var{src} and
  28   \var{dst} are path names given as strings.
  29 \end{funcdesc}
  30
  31 \begin{funcdesc}{copyfileobj}{fsrc, fdst\optional{, length}}
  32   Copy the contents of the file-like object \var{fsrc} to the
  33   file-like object \var{fdst}.  The integer \var{length}, if given,
  34   is the buffer size. In particular, a negative \var{length} value
  35   means to copy the data without looping over the source data in
  36   chunks; by default the data is read in chunks to avoid uncontrolled
  37   memory consumption.
  38 \end{funcdesc}
  39
  40 \begin{funcdesc}{copymode}{src, dst}
  41   Copy the permission bits from \var{src} to \var{dst}.  The file
  42   contents, owner, and group are unaffected.  \var{src} and \var{dst}
  43   are path names given as strings.
  44 \end{funcdesc}
  45
  46 \begin{funcdesc}{copystat}{src, dst}
  47   Copy the permission bits, last access time, and last modification
  48   time from \var{src} to \var{dst}.  The file contents, owner, and
  49   group are unaffected.  \var{src} and \var{dst} are path names given
  50   as strings.
  51 \end{funcdesc}
  52
  53 \begin{funcdesc}{copy}{src, dst}
  54   Copy the file \var{src} to the file or directory \var{dst}.  If
  55   \var{dst} is a directory, a file with the same basename as \var{src}
  56   is created (or overwritten) in the directory specified.  Permission
  57   bits are copied.  \var{src} and \var{dst} are path names given as
  58   strings.
  59 \end{funcdesc}
  60
  61 \begin{funcdesc}{copy2}{src, dst}
  62   Similar to \function{copy()}, but last access time and last
  63   modification time are copied as well.  This is similar to the
  64   \UNIX{} command \program{cp} \programopt{-p}.
  65 \end{funcdesc}
  66
  67 \begin{funcdesc}{copytree}{src, dst\optional{, symlinks}}
  68   Recursively copy an entire directory tree rooted at \var{src}.  The
  69   destination directory, named by \var{dst}, must not already exist;
  70   it will be created.  Individual files are copied using
  71   \function{copy2()}.  If \var{symlinks} is true, symbolic links in
  72   the source tree are represented as symbolic links in the new tree;
  73   if false or omitted, the contents of the linked files are copied to
  74   the new tree.  If exception(s) occur, an Error is raised
  75   with a list of reasons.
  76
  77   The source code for this should be considered an example rather than
  78   a tool.
  79 \versionchanged[Error is raised if any exceptions occur during copying,
  80 rather than printing a message]{2.3}
  81 \end{funcdesc}
  82
  83 \begin{funcdesc}{rmtree}{path\optional{, ignore_errors\optional{, onerror}}}
  84   Delete an entire directory tree.\index{directory!deleting}
  85   If \var{ignore_errors} is true,
  86   errors resulting from failed removals will be ignored; if false or
  87   omitted, such errors are handled by calling a handler specified by
  88   \var{onerror} or, if that is omitted, they raise an exception.
  89
  90   If \var{onerror} is provided, it must be a callable that accepts
  91   three parameters: \var{function}, \var{path}, and \var{excinfo}.
  92   The first parameter, \var{function}, is the function which raised
  93   the exception; it will be \function{os.listdir()}, \function{os.remove()} or
  94   \function{os.rmdir()}.  The second parameter, \var{path}, will be
  95   the path name passed to \var{function}.  The third parameter,
  96   \var{excinfo}, will be the exception information return by
  97   \function{sys.exc_info()}.  Exceptions raised by \var{onerror} will
  98   not be caught.
  99 \end{funcdesc}
 100
 101 \begin{funcdesc}{move}{src, dst}
 102 Recursively move a file or directory to another location.
 103
 104 If the destination is on our current filesystem, then simply use
 105 rename.  Otherwise, copy src to the dst and then remove src.
 106
 107 \versionadded{2.3}
 108 \end{funcdesc}
 109
 110 \begin{excdesc}{Error}
 111 This exception collects exceptions that raised during a mult-file
 112 operation. For \function{copytree}, the exception argument is a
 113 list of 3-tuples (\var{srcname}, \var{dstname}, \var{exception}).
 114
 115 \versionadded{2.3}
 116 \end{excdesc}
 117
 118 \subsection{Example \label{shutil-example}}
 119
 120 This example is the implementation of the \function{copytree()}
 121 function, described above, with the docstring omitted.  It
 122 demonstrates many of the other functions provided by this module.
 123
 124 \begin{verbatim}
 125 def copytree(src, dst, symlinks=0):
 126     names = os.listdir(src)
 127     os.mkdir(dst)
 128     for name in names:
 129         srcname = os.path.join(src, name)
 130         dstname = os.path.join(dst, name)
 131         try:
 132             if symlinks and os.path.islink(srcname):
 133                 linkto = os.readlink(srcname)
 134                 os.symlink(linkto, dstname)
 135             elif os.path.isdir(srcname):
 136                 copytree(srcname, dstname, symlinks)
 137             else:
 138                 copy2(srcname, dstname)
 139         except (IOError, os.error), why:
 140             print "Can't copy %s to %s: %s" % (`srcname`, `dstname`, str(why))
 141 \end{verbatim}