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 \var{src} to \var{dst}.  If \var{dst} exists,
  23   it will be replaced, otherwise it will be created.
  24 \end{funcdesc}
  25
  26 \begin{funcdesc}{copymode}{src, dst}
  27   Copy the permission bits from \var{src} to \var{dst}.  The file
  28   contents, owner, and group are unaffected.
  29 \end{funcdesc}
  30
  31 \begin{funcdesc}{copystat}{src, dst}
  32   Copy the permission bits, last access time, and last modification
  33   time from \var{src} to \var{dst}.  The file contents, owner, and
  34   group are unaffected.
  35 \end{funcdesc}
  36
  37 \begin{funcdesc}{copy}{src, dst}
  38   Copy the file \var{src} to the file or directory \var{dst}.  If
  39   \var{dst} is a directory, a file with the same basename as \var{src}
  40   is created (or overwritten) in the directory specified.  Permission
  41   bits are copied.
  42 \end{funcdesc}
  43
  44 \begin{funcdesc}{copy2}{src, dst}
  45   Similar to \function{copy()}, but last access time and last
  46   modification time are copied as well.  This is similar to the
  47   \UNIX{} command \program{cp -p}.
  48 \end{funcdesc}
  49
  50 \begin{funcdesc}{copytree}{src, dst\optional{, symlinks}}
  51   Recursively copy an entire directory tree rooted at \var{src}.  The
  52   destination directory, named by \var{dst}, must not already exist;
  53   it will be created.  Individual files are copied using
  54   \function{copy2()}.  If \var{symlinks} is true, symbolic links in
  55   the source tree are represented as symbolic links in the new tree;
  56   if false or omitted, the contents of the linked files are copied to
  57   the new tree.  Errors are reported to standard output.
  58
  59   The source code for this should be considered an example rather than
  60   a tool.
  61 \end{funcdesc}
  62
  63 \begin{funcdesc}{rmtree}{path\optional{, ignore_errors\optional{, onerror}}}
  64 \index{directory!deleting}
  65   Delete an entire directory tree.  If \var{ignore_errors} is true,
  66   errors will be ignored; if false or omitted, errors are handled by
  67   calling a handler specified by \var{onerror} or raise an exception.
  68
  69   If \var{onerror} is provided, it must be a callable that accepts
  70   three parameters: \var{function}, \var{path}, and \var{excinfo}.
  71   The first parameter, \var{function}, is the function which raised
  72   the exception; it will be \function{os.remove()} or
  73   \function{os.rmdir()}.  The second parameter, \var{path}, will be
  74   the path name passed to \var{function}.  The third parameter,
  75   \var{excinfo}, will be the exception information return by
  76   \function{sys.exc_info()}.  Exceptions raised by \var{onerror} will
  77   not be caught.
  78 \end{funcdesc}
  79
  80
  81 \subsection{Example \label{shutil-example}}
  82
  83 This example is the implementation of the \function{copytree()}
  84 function, described above, with the docstring omitted.
  85
  86 \begin{verbatim}
  87 def copytree(src, dst, symlinks=0):
  88     names = os.listdir(src)
  89     os.mkdir(dst)
  90     for name in names:
  91         srcname = os.path.join(src, name)
  92         dstname = os.path.join(dst, name)
  93         try:
  94             if symlinks and os.path.islink(srcname):
  95                 linkto = os.readlink(srcname)
  96                 os.symlink(linkto, dstname)
  97             elif os.path.isdir(srcname):
  98                 copytree(srcname, dstname)
  99             else:
 100                 copy2(srcname, dstname)
 101             # XXX What about devices, sockets etc.?
 102         except (IOError, os.error), why:
 103             print "Can't copy %s to %s: %s" % (`srcname`, `dstname`, str(why))
 104 \end{verbatim}