Doc/library/shutil.rst

   1
   2 :mod:`shutil` --- High-level file operations
   3 ============================================
   4
   5 .. module:: shutil
   6    :synopsis: High-level file operations, including copying.
   7 .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
   8 .. partly based on the docstrings
   9
  10 .. index::
  11    single: file; copying
  12    single: copying files
  13
  14 The :mod:`shutil` module offers a number of high-level operations on files and
  15 collections of files.  In particular, functions are provided  which support file
  16 copying and removal. For operations on individual files, see also the
  17 :mod:`os` module.
  18
  19 .. warning::
  20
  21    Even the higher-level file copying functions (:func:`copy`, :func:`copy2`)
  22    can't copy all file metadata.
  23
  24    On POSIX platforms, this means that file owner and group are lost as well
  25    as ACLs.  On MacOS, the resource fork and other metadata are not used.
  26    This means that resources will be lost and file type and creator codes will
  27    not be correct. On Windows, file owners, ACLs and alternate data streams
  28    are not copied.
  29
  30
  31 .. function:: copyfile(src, dst)
  32
  33    Copy the contents (no metadata) of the file named *src* to a file named *dst*.
  34    The destination location must be writable; otherwise,  an :exc:`IOError` exception
  35    will be raised. If *dst* already exists, it will be replaced.   Special files
  36    such as character or block devices and pipes cannot be copied with this
  37    function.  *src* and *dst* are path names given as strings.
  38
  39
  40 .. function:: copyfileobj(fsrc, fdst[, length])
  41
  42    Copy the contents of the file-like object *fsrc* to the file-like object *fdst*.
  43    The integer *length*, if given, is the buffer size. In particular, a negative
  44    *length* value means to copy the data without looping over the source data in
  45    chunks; by default the data is read in chunks to avoid uncontrolled memory
  46    consumption. Note that if the current file position of the *fsrc* object is not
  47    0, only the contents from the current file position to the end of the file will
  48    be copied.
  49
  50
  51 .. function:: copymode(src, dst)
  52
  53    Copy the permission bits from *src* to *dst*.  The file contents, owner, and
  54    group are unaffected.  *src* and *dst* are path names given as strings.
  55
  56
  57 .. function:: copystat(src, dst)
  58
  59    Copy the permission bits, last access time, last modification time, and flags
  60    from *src* to *dst*.  The file contents, owner, and group are unaffected.  *src*
  61    and *dst* are path names given as strings.
  62
  63
  64 .. function:: copy(src, dst)
  65
  66    Copy the file *src* to the file or directory *dst*.  If *dst* is a directory, a
  67    file with the same basename as *src*  is created (or overwritten) in the
  68    directory specified.  Permission bits are copied.  *src* and *dst* are path
  69    names given as strings.
  70
  71
  72 .. function:: copy2(src, dst)
  73
  74    Similar to :func:`copy`, but last access time and last modification time are
  75    copied as well.  This is similar to the Unix command :program:`cp -p`.
  76
  77
  78 .. function:: copytree(src, dst[, symlinks])
  79
  80    Recursively copy an entire directory tree rooted at *src*.  The destination
  81    directory, named by *dst*, must not already exist; it will be created as well as
  82    missing parent directories. Permissions and times of directories are copied with
  83    :func:`copystat`, individual files are copied using :func:`copy2`.   If
  84    *symlinks* is true, symbolic links in the source tree are represented as
  85    symbolic links in the new tree; if false or omitted, the contents of the linked
  86    files are copied to the new tree.  If exception(s) occur, an :exc:`Error` is
  87    raised with a list of reasons.
  88
  89    The source code for this should be considered an example rather than a tool.
  90
  91    .. versionchanged:: 2.3
  92       :exc:`Error` is raised if any exceptions occur during copying, rather than
  93       printing a message.
  94
  95    .. versionchanged:: 2.5
  96       Create intermediate directories needed to create *dst*, rather than raising an
  97       error. Copy permissions and times of directories using :func:`copystat`.
  98
  99
 100 .. function:: rmtree(path[, ignore_errors[, onerror]])
 101
 102    .. index:: single: directory; deleting
 103
 104    Delete an entire directory tree; *path* must point to a directory (but not a
 105    symbolic link to a directory).  If *ignore_errors* is true, errors resulting
 106    from failed removals will be ignored; if false or omitted, such errors are
 107    handled by calling a handler specified by *onerror* or, if that is omitted,
 108    they raise an exception.
 109
 110    If *onerror* is provided, it must be a callable that accepts three
 111    parameters: *function*, *path*, and *excinfo*. The first parameter,
 112    *function*, is the function which raised the exception; it will be
 113    :func:`os.path.islink`, :func:`os.listdir`, :func:`os.remove` or
 114    :func:`os.rmdir`.  The second parameter, *path*, will be the path name passed
 115    to *function*.  The third parameter, *excinfo*, will be the exception
 116    information return by :func:`sys.exc_info`.  Exceptions raised by *onerror*
 117    will not be caught.
 118
 119    .. versionchanged:: 2.6
 120       Explicitly check for *path* being a symbolic link and raise :exc:`OSError`
 121       in that case.
 122
 123
 124 .. function:: move(src, dst)
 125
 126    Recursively move a file or directory to another location.
 127
 128    If the destination is on the current filesystem, then simply use rename.
 129    Otherwise, copy src to the dst and then remove src.
 130
 131    .. versionadded:: 2.3
 132
 133
 134 .. exception:: Error
 135
 136    This exception collects exceptions that raised during a multi-file operation. For
 137    :func:`copytree`, the exception argument is a list of 3-tuples (*srcname*,
 138    *dstname*, *exception*).
 139
 140    .. versionadded:: 2.3
 141
 142
 143 .. _shutil-example:
 144
 145 Example
 146 -------
 147
 148 This example is the implementation of the :func:`copytree` function, described
 149 above, with the docstring omitted.  It demonstrates many of the other functions
 150 provided by this module. ::
 151
 152    def copytree(src, dst, symlinks=False):
 153        names = os.listdir(src)
 154        os.makedirs(dst)
 155        errors = []
 156        for name in names:
 157            srcname = os.path.join(src, name)
 158            dstname = os.path.join(dst, name)
 159            try:
 160                if symlinks and os.path.islink(srcname):
 161                    linkto = os.readlink(srcname)
 162                    os.symlink(linkto, dstname)
 163                elif os.path.isdir(srcname):
 164                    copytree(srcname, dstname, symlinks)
 165                else:
 166                    copy2(srcname, dstname)
 167                # XXX What about devices, sockets etc.?
 168            except (IOError, os.error), why:
 169                errors.append((srcname, dstname, str(why)))
 170            # catch the Error from the recursive copytree so that we can
 171            # continue with other files
 172            except Error, err:
 173                errors.extend(err.args[0])
 174        try:
 175            copystat(src, dst)
 176        except WindowsError:
 177            # can't copy file access times on Windows
 178            pass
 179        except OSError, why:
 180            errors.extend((src, dst, str(why)))
 181        if errors:
 182            raise Error, errors