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 as well as missing parent directories.
  71   Permissions and times of directories are copied with \function{copystat()},
  72   individual files are copied using \function{copy2()}.
  73   If \var{symlinks} is true, symbolic links in
  74   the source tree are represented as symbolic links in the new tree;
  75   if false or omitted, the contents of the linked files are copied to
  76   the new tree.  If exception(s) occur, an \exception{Error} is raised
  77   with a list of reasons.
  78
  79   The source code for this should be considered an example rather than
  80   a tool.
  81
  82   \versionchanged[\exception{Error} is raised if any exceptions occur during
  83                   copying, rather than printing a message]{2.3}
  84
  85   \versionchanged[Create intermediate directories needed to create \var{dst},
  86                   rather than raising an error. Copy permissions and times of
  87                   directories using \function{copystat()}]{2.5}
  88
  89 \end{funcdesc}
  90
  91 \begin{funcdesc}{rmtree}{path\optional{, ignore_errors\optional{, onerror}}}
  92   Delete an entire directory tree.\index{directory!deleting}
  93   If \var{ignore_errors} is true,
  94   errors resulting from failed removals will be ignored; if false or
  95   omitted, such errors are handled by calling a handler specified by
  96   \var{onerror} or, if that is omitted, they raise an exception.
  97
  98   If \var{onerror} is provided, it must be a callable that accepts
  99   three parameters: \var{function}, \var{path}, and \var{excinfo}.
 100   The first parameter, \var{function}, is the function which raised
 101   the exception; it will be \function{os.listdir()}, \function{os.remove()} or
 102   \function{os.rmdir()}.  The second parameter, \var{path}, will be
 103   the path name passed to \var{function}.  The third parameter,
 104   \var{excinfo}, will be the exception information return by
 105   \function{sys.exc_info()}.  Exceptions raised by \var{onerror} will
 106   not be caught.
 107 \end{funcdesc}
 108
 109 \begin{funcdesc}{move}{src, dst}
 110 Recursively move a file or directory to another location.
 111
 112 If the destination is on our current filesystem, then simply use
 113 rename.  Otherwise, copy src to the dst and then remove src.
 114
 115 \versionadded{2.3}
 116 \end{funcdesc}
 117
 118 \begin{excdesc}{Error}
 119 This exception collects exceptions that raised during a mult-file
 120 operation. For \function{copytree}, the exception argument is a
 121 list of 3-tuples (\var{srcname}, \var{dstname}, \var{exception}).
 122
 123 \versionadded{2.3}
 124 \end{excdesc}
 125
 126 \subsection{Example \label{shutil-example}}
 127
 128 This example is the implementation of the \function{copytree()}
 129 function, described above, with the docstring omitted.  It
 130 demonstrates many of the other functions provided by this module.
 131
 132 \begin{verbatim}
 133 def copytree(src, dst, symlinks=0):
 134     names = os.listdir(src)
 135     os.mkdir(dst)
 136     for name in names:
 137         srcname = os.path.join(src, name)
 138         dstname = os.path.join(dst, name)
 139         try:
 140             if symlinks and os.path.islink(srcname):
 141                 linkto = os.readlink(srcname)
 142                 os.symlink(linkto, dstname)
 143             elif os.path.isdir(srcname):
 144                 copytree(srcname, dstname, symlinks)
 145             else:
 146                 copy2(srcname, dstname)
 147         except (IOError, os.error), why:
 148             print "Can't copy %s to %s: %s" % (`srcname`, `dstname`, str(why))
 149 \end{verbatim}