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.  Errors are reported to standard output.
  73
  74   The source code for this should be considered an example rather than
  75   a tool.
  76 \end{funcdesc}
  77
  78 \begin{funcdesc}{rmtree}{path\optional{, ignore_errors\optional{, onerror}}}
  79 \index{directory!deleting}
  80   Delete an entire directory tree.  If \var{ignore_errors} is true,
  81   errors resulting from failed removals will be ignored; if false or
  82   omitted, such errors are handled by calling a handler specified by
  83   \var{onerror} or, if that is omitted, they raise an exception.
  84
  85   If \var{onerror} is provided, it must be a callable that accepts
  86   three parameters: \var{function}, \var{path}, and \var{excinfo}.
  87   The first parameter, \var{function}, is the function which raised
  88   the exception; it will be \function{os.remove()} or
  89   \function{os.rmdir()}.  The second parameter, \var{path}, will be
  90   the path name passed to \var{function}.  The third parameter,
  91   \var{excinfo}, will be the exception information return by
  92   \function{sys.exc_info()}.  Exceptions raised by \var{onerror} will
  93   not be caught.
  94 \end{funcdesc}
  95
  96
  97 \subsection{Example \label{shutil-example}}
  98
  99 This example is the implementation of the \function{copytree()}
 100 function, described above, with the docstring omitted.  It
 101 demonstrates many of the other functions provided by this module.
 102
 103 \begin{verbatim}
 104 def copytree(src, dst, symlinks=0):
 105     names = os.listdir(src)
 106     os.mkdir(dst)
 107     for name in names:
 108         srcname = os.path.join(src, name)
 109         dstname = os.path.join(dst, name)
 110         try:
 111             if symlinks and os.path.islink(srcname):
 112                 linkto = os.readlink(srcname)
 113                 os.symlink(linkto, dstname)
 114             elif os.path.isdir(srcname):
 115                 copytree(srcname, dstname, symlinks)
 116             else:
 117                 copy2(srcname, dstname)
 118         except (IOError, os.error), why:
 119             print "Can't copy %s to %s: %s" % (`srcname`, `dstname`, str(why))
 120 \end{verbatim}