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   Delete an entire directory tree.\index{directory!deleting}
  80   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 \begin{funcdesc}{move}{src, dst}
  97 Recursively move a file or directory to another location.
  98
  99 If the destination is on our current filesystem, then simply use
 100 rename.  Otherwise, copy src to the dst and then remove src.
 101
 102 \versionadded{2.3}
 103 \end{funcdesc}
 104
 105 \begin{excdesc}{Error}
 106 This exception collects exceptions that raised during a mult-file
 107 operation. For \function{copytree}, the exception argument is a
 108 list of 3-tuples (\var{srcname}, \var{dstname}, \var{exception}).
 109
 110 \versionadded{2.3}
 111 \end{excdesc}
 112
 113 \subsection{Example \label{shutil-example}}
 114
 115 This example is the implementation of the \function{copytree()}
 116 function, described above, with the docstring omitted.  It
 117 demonstrates many of the other functions provided by this module.
 118
 119 \begin{verbatim}
 120 def copytree(src, dst, symlinks=0):
 121     names = os.listdir(src)
 122     os.mkdir(dst)
 123     for name in names:
 124         srcname = os.path.join(src, name)
 125         dstname = os.path.join(dst, name)
 126         try:
 127             if symlinks and os.path.islink(srcname):
 128                 linkto = os.readlink(srcname)
 129                 os.symlink(linkto, dstname)
 130             elif os.path.isdir(srcname):
 131                 copytree(srcname, dstname, symlinks)
 132             else:
 133                 copy2(srcname, dstname)
 134         except (IOError, os.error), why:
 135             print "Can't copy %s to %s: %s" % (`srcname`, `dstname`, str(why))
 136 \end{verbatim}