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.

    47    The destination location must be writable; otherwise,  an :exc:`IOError` exception

    48    will be raised. If *dst* already exists, it will be replaced.   Special files

    49    such as character or block devices and pipes cannot be copied with this

    50    function.  *src* and *dst* are path names given as strings.

    51 

    52 

    53 .. function:: copymode(src, dst)

    54 

    55    Copy the permission bits from *src* to *dst*.  The file contents, owner, and

    56    group are unaffected.  *src* and *dst* are path names given as strings.

    57 

    58 

    59 .. function:: copystat(src, dst)

    60 

    61    Copy the permission bits, last access time, last modification time, and flags

    62    from *src* to *dst*.  The file contents, owner, and group are unaffected.  *src*

    63    and *dst* are path names given as strings.

    64 

    65 

    66 .. function:: copy(src, dst)

    67 

    68    Copy the file *src* to the file or directory *dst*.  If *dst* is a directory, a

    69    file with the same basename as *src*  is created (or overwritten) in the

    70    directory specified.  Permission bits are copied.  *src* and *dst* are path

    71    names given as strings.

    72 

    73 

    74 .. function:: copy2(src, dst)

    75 

    76    Similar to :func:`copy`, but metadata is copied as well -- in fact, this is just

    77    :func:`copy` followed by :func:`copystat`.  This is similar to the

    78    Unix command :program:`cp -p`.

    79 

    80 

    81 .. function:: ignore_patterns(\*patterns)

    82 

    83    This factory function creates a function that can be used as a callable for

    84    :func:`copytree`\'s *ignore* argument, ignoring files and directories that

    85    match one of the glob-style *patterns* provided.  See the example below.

    86 

    87    .. versionadded:: 2.6

    88 

    89 

    90 .. function:: copytree(src, dst[, symlinks=False[, ignore=None]])

    91 

    92    Recursively copy an entire directory tree rooted at *src*.  The destination

    93    directory, named by *dst*, must not already exist; it will be created as well

    94    as missing parent directories.  Permissions and times of directories are

    95    copied with :func:`copystat`, individual files are copied using

    96    :func:`copy2`.

    97 

    98    If *symlinks* is true, symbolic links in the source tree are represented as

    99    symbolic links in the new tree; if false or omitted, the contents of the

   100    linked files are copied to the new tree.

   101 

   102    If *ignore* is given, it must be a callable that will receive as its

   103    arguments the directory being visited by :func:`copytree`, and a list of its

   104    contents, as returned by :func:`os.listdir`.  Since :func:`copytree` is

   105    called recursively, the *ignore* callable will be called once for each

   106    directory that is copied.  The callable must return a sequence of directory

   107    and file names relative to the current directory (i.e. a subset of the items

   108    in its second argument); these names will then be ignored in the copy

   109    process.  :func:`ignore_patterns` can be used to create such a callable that

   110    ignores names based on glob-style patterns.

   111 

   112    If exception(s) occur, an :exc:`Error` is raised with a list of reasons.

   113 

   114    The source code for this should be considered an example rather than the

   115    ultimate tool.

   116 

   117    .. versionchanged:: 2.3

   118       :exc:`Error` is raised if any exceptions occur during copying, rather than

   119       printing a message.

   120 

   121    .. versionchanged:: 2.5

   122       Create intermediate directories needed to create *dst*, rather than raising an

   123       error. Copy permissions and times of directories using :func:`copystat`.

   124 

   125    .. versionchanged:: 2.6

   126       Added the *ignore* argument to be able to influence what is being copied. 

   127 

   128 

   129 .. function:: rmtree(path[, ignore_errors[, onerror]])

   130 

   131    .. index:: single: directory; deleting

   132 

   133    Delete an entire directory tree; *path* must point to a directory (but not a

   134    symbolic link to a directory).  If *ignore_errors* is true, errors resulting

   135    from failed removals will be ignored; if false or omitted, such errors are

   136    handled by calling a handler specified by *onerror* or, if that is omitted,

   137    they raise an exception.

   138 

   139    If *onerror* is provided, it must be a callable that accepts three

   140    parameters: *function*, *path*, and *excinfo*. The first parameter,

   141    *function*, is the function which raised the exception; it will be

   142    :func:`os.path.islink`, :func:`os.listdir`, :func:`os.remove` or

   143    :func:`os.rmdir`.  The second parameter, *path*, will be the path name passed

   144    to *function*.  The third parameter, *excinfo*, will be the exception

   145    information return by :func:`sys.exc_info`.  Exceptions raised by *onerror*

   146    will not be caught.

   147 

   148    .. versionchanged:: 2.6

   149       Explicitly check for *path* being a symbolic link and raise :exc:`OSError`

   150       in that case.

   151 

   152 

   153 .. function:: move(src, dst)

   154 

   155    Recursively move a file or directory to another location.

   156 

   157    If the destination is on the current filesystem, then simply use rename.

   158    Otherwise, copy src to the dst and then remove src.

   159 

   160    .. versionadded:: 2.3

   161 

   162 

   163 .. exception:: Error

   164 

   165    This exception collects exceptions that raised during a multi-file operation. For

   166    :func:`copytree`, the exception argument is a list of 3-tuples (*srcname*,

   167    *dstname*, *exception*).

   168 

   169    .. versionadded:: 2.3

   170 

   171 

   172 .. _shutil-example:

   173 

   174 Example

   175 -------

   176 

   177 This example is the implementation of the :func:`copytree` function, described

   178 above, with the docstring omitted.  It demonstrates many of the other functions

   179 provided by this module. ::

   180 

   181    def copytree(src, dst, symlinks=False, ignore=None):

   182        names = os.listdir(src)

   183        if ignore is not None:

   184            ignored_names = ignore(src, names)

   185        else:

   186            ignored_names = set()

   187 

   188        os.makedirs(dst)

   189        errors = []

   190        for name in names:

   191            if name in ignored_names:   

   192                continue

   193            srcname = os.path.join(src, name)

   194            dstname = os.path.join(dst, name)

   195            try:

   196                if symlinks and os.path.islink(srcname):

   197                    linkto = os.readlink(srcname)

   198                    os.symlink(linkto, dstname)

   199                elif os.path.isdir(srcname):

   200                    copytree(srcname, dstname, symlinks, ignore)

   201                else:

   202                    copy2(srcname, dstname)

   203                # XXX What about devices, sockets etc.?

   204            except (IOError, os.error), why:

   205                errors.append((srcname, dstname, str(why)))

   206            # catch the Error from the recursive copytree so that we can

   207            # continue with other files

   208            except Error, err:

   209                errors.extend(err.args[0])

   210        try:

   211            copystat(src, dst)

   212        except WindowsError:

   213            # can't copy file access times on Windows

   214            pass

   215        except OSError, why:

   216            errors.extend((src, dst, str(why)))

   217        if errors:

   218            raise Error, errors

   219 

   220 Another example that uses the :func:`ignore_patterns` helper::

   221 

   222    from shutil import copytree, ignore_patterns

   223    

   224    copytree(source, destination, ignore=ignore_patterns('*.pyc', 'tmp*'))

   225 

   226 This will copy everything except ``.pyc`` files and files or directories whose

   227 name starts with ``tmp``.

   228 

   229 Another example that uses the *ignore* argument to add a logging call::

   230 

   231    from shutil import copytree

   232    import logging

   233    

   234    def _logpath(path, names):

   235        logging.info('Working in %s' % path)

   236        return []   # nothing will be ignored

   237 

   238    copytree(source, destination, ignore=_logpath)

   239