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 Mac OS, 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:: copyfileobj(fsrc, fdst[, length])
  32
  33    Copy the contents of the file-like object *fsrc* to the file-like object *fdst*.
  34    The integer *length*, if given, is the buffer size. In particular, a negative
  35    *length* value means to copy the data without looping over the source data in
  36    chunks; by default the data is read in chunks to avoid uncontrolled memory
  37    consumption. Note that if the current file position of the *fsrc* object is not
  38    0, only the contents from the current file position to the end of the file will
  39    be copied.
  40
  41
  42 .. function:: copyfile(src, dst)
  43
  44    Copy the contents (no metadata) of the file named *src* to a file named *dst*.
  45    *dst* must be the complete target file name; look at :func:`copy` for a copy that
  46    accepts a target directory path.  If *src* and *dst* are the same files,
  47    :exc:`Error` is raised.
  48    The destination location must be writable; otherwise,  an :exc:`IOError` exception
  49    will be raised. If *dst* already exists, it will be replaced.   Special files
  50    such as character or block devices and pipes cannot be copied with this
  51    function.  *src* and *dst* are path names given as strings.
  52
  53
  54 .. function:: copymode(src, dst)
  55
  56    Copy the permission bits from *src* to *dst*.  The file contents, owner, and
  57    group are unaffected.  *src* and *dst* are path names given as strings.
  58
  59
  60 .. function:: copystat(src, dst)
  61
  62    Copy the permission bits, last access time, last modification time, and flags
  63    from *src* to *dst*.  The file contents, owner, and group are unaffected.  *src*
  64    and *dst* are path names given as strings.
  65
  66
  67 .. function:: copy(src, dst)
  68
  69    Copy the file *src* to the file or directory *dst*.  If *dst* is a directory, a
  70    file with the same basename as *src*  is created (or overwritten) in the
  71    directory specified.  Permission bits are copied.  *src* and *dst* are path
  72    names given as strings.
  73
  74
  75 .. function:: copy2(src, dst)
  76
  77    Similar to :func:`copy`, but metadata is copied as well -- in fact, this is just
  78    :func:`copy` followed by :func:`copystat`.  This is similar to the
  79    Unix command :program:`cp -p`.
  80
  81
  82 .. function:: ignore_patterns(\*patterns)
  83
  84    This factory function creates a function that can be used as a callable for
  85    :func:`copytree`\'s *ignore* argument, ignoring files and directories that
  86    match one of the glob-style *patterns* provided.  See the example below.
  87
  88    .. versionadded:: 2.6
  89
  90
  91 .. function:: copytree(src, dst[, symlinks=False[, ignore=None]])
  92
  93    Recursively copy an entire directory tree rooted at *src*.  The destination
  94    directory, named by *dst*, must not already exist; it will be created as well
  95    as missing parent directories.  Permissions and times of directories are
  96    copied with :func:`copystat`, individual files are copied using
  97    :func:`copy2`.
  98
  99    If *symlinks* is true, symbolic links in the source tree are represented as
 100    symbolic links in the new tree; if false or omitted, the contents of the
 101    linked files are copied to the new tree.
 102
 103    If *ignore* is given, it must be a callable that will receive as its
 104    arguments the directory being visited by :func:`copytree`, and a list of its
 105    contents, as returned by :func:`os.listdir`.  Since :func:`copytree` is
 106    called recursively, the *ignore* callable will be called once for each
 107    directory that is copied.  The callable must return a sequence of directory
 108    and file names relative to the current directory (i.e. a subset of the items
 109    in its second argument); these names will then be ignored in the copy
 110    process.  :func:`ignore_patterns` can be used to create such a callable that
 111    ignores names based on glob-style patterns.
 112
 113    If exception(s) occur, an :exc:`Error` is raised with a list of reasons.
 114
 115    The source code for this should be considered an example rather than the
 116    ultimate tool.
 117
 118    .. versionchanged:: 2.3
 119       :exc:`Error` is raised if any exceptions occur during copying, rather than
 120       printing a message.
 121
 122    .. versionchanged:: 2.5
 123       Create intermediate directories needed to create *dst*, rather than raising an
 124       error. Copy permissions and times of directories using :func:`copystat`.
 125
 126    .. versionchanged:: 2.6
 127       Added the *ignore* argument to be able to influence what is being copied.
 128
 129
 130 .. function:: rmtree(path[, ignore_errors[, onerror]])
 131
 132    .. index:: single: directory; deleting
 133
 134    Delete an entire directory tree; *path* must point to a directory (but not a
 135    symbolic link to a directory).  If *ignore_errors* is true, errors resulting
 136    from failed removals will be ignored; if false or omitted, such errors are
 137    handled by calling a handler specified by *onerror* or, if that is omitted,
 138    they raise an exception.
 139
 140    If *onerror* is provided, it must be a callable that accepts three
 141    parameters: *function*, *path*, and *excinfo*. The first parameter,
 142    *function*, is the function which raised the exception; it will be
 143    :func:`os.path.islink`, :func:`os.listdir`, :func:`os.remove` or
 144    :func:`os.rmdir`.  The second parameter, *path*, will be the path name passed
 145    to *function*.  The third parameter, *excinfo*, will be the exception
 146    information return by :func:`sys.exc_info`.  Exceptions raised by *onerror*
 147    will not be caught.
 148
 149    .. versionchanged:: 2.6
 150       Explicitly check for *path* being a symbolic link and raise :exc:`OSError`
 151       in that case.
 152
 153
 154 .. function:: move(src, dst)
 155
 156    Recursively move a file or directory to another location.
 157
 158    If the destination is on the current filesystem, then simply use rename.
 159    Otherwise, copy src (with :func:`copy2`) to the dst and then remove src.
 160
 161    .. versionadded:: 2.3
 162
 163
 164 .. exception:: Error
 165
 166    This exception collects exceptions that raised during a multi-file operation. For
 167    :func:`copytree`, the exception argument is a list of 3-tuples (*srcname*,
 168    *dstname*, *exception*).
 169
 170    .. versionadded:: 2.3
 171
 172
 173 .. _shutil-example:
 174
 175 Example
 176 -------
 177
 178 This example is the implementation of the :func:`copytree` function, described
 179 above, with the docstring omitted.  It demonstrates many of the other functions
 180 provided by this module. ::
 181
 182    def copytree(src, dst, symlinks=False, ignore=None):
 183        names = os.listdir(src)
 184        if ignore is not None:
 185            ignored_names = ignore(src, names)
 186        else:
 187            ignored_names = set()
 188
 189        os.makedirs(dst)
 190        errors = []
 191        for name in names:
 192            if name in ignored_names:
 193                continue
 194            srcname = os.path.join(src, name)
 195            dstname = os.path.join(dst, name)
 196            try:
 197                if symlinks and os.path.islink(srcname):
 198                    linkto = os.readlink(srcname)
 199                    os.symlink(linkto, dstname)
 200                elif os.path.isdir(srcname):
 201                    copytree(srcname, dstname, symlinks, ignore)
 202                else:
 203                    copy2(srcname, dstname)
 204                # XXX What about devices, sockets etc.?
 205            except (IOError, os.error), why:
 206                errors.append((srcname, dstname, str(why)))
 207            # catch the Error from the recursive copytree so that we can
 208            # continue with other files
 209            except Error, err:
 210                errors.extend(err.args[0])
 211        try:
 212            copystat(src, dst)
 213        except WindowsError:
 214            # can't copy file access times on Windows
 215            pass
 216        except OSError, why:
 217            errors.extend((src, dst, str(why)))
 218        if errors:
 219            raise Error(errors)
 220
 221 Another example that uses the :func:`ignore_patterns` helper::
 222
 223    from shutil import copytree, ignore_patterns
 224
 225    copytree(source, destination, ignore=ignore_patterns('*.pyc', 'tmp*'))
 226
 227 This will copy everything except ``.pyc`` files and files or directories whose
 228 name starts with ``tmp``.
 229
 230 Another example that uses the *ignore* argument to add a logging call::
 231
 232    from shutil import copytree
 233    import logging
 234
 235    def _logpath(path, names):
 236        logging.info('Working in %s' % path)
 237        return []   # nothing will be ignored
 238
 239    copytree(source, destination, ignore=_logpath)
 240