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