From: Benjamin Peterson <benjamin@python.org>
Date: Sun, 22 Mar 2015 14:15:12 +0000 (-0400)
Subject: merge 3.4 (#22933)
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=67057ab57cd7e4872d9483cf259f7c26c992adcc;p=python

merge 3.4 (#22933)
---

67057ab57cd7e4872d9483cf259f7c26c992adcc
diff --cc Doc/library/shutil.rst
index 82974ade22,cd86e92944..3b467e01c2
--- a/Doc/library/shutil.rst
+++ b/Doc/library/shutil.rst
@@@ -288,25 -287,14 +288,22 @@@ Directory and files operation
     Recursively move a file or directory (*src*) to another location (*dst*)
     and return the destination.
  
-    If the destination is a directory or a symlink to a directory, then *src* is
-    moved inside that directory.
- 
-    The destination directory must not already exist.  If the destination already
-    exists but is not a directory, it may be overwritten depending on
-    :func:`os.rename` semantics.
+    If the destination is an existing directory, then *src* is moved inside that
+    directory. If the destination already exists but is not a directory, it may
+    be overwritten depending on :func:`os.rename` semantics.
  
     If the destination is on the current filesystem, then :func:`os.rename` is
 -   used.  Otherwise, *src* is copied (using :func:`shutil.copy2`) to *dst* and
 -   then removed. In case of symlinks, a new symlink pointing to the target of
 -   *src* will be created in or as *dst* and *src* will be removed.
 +   used. Otherwise, *src* is copied to *dst* using *copy_function* and then
 +   removed.  In case of symlinks, a new symlink pointing to the target of *src*
 +   will be created in or as *dst* and *src* will be removed.
 +
 +   If *copy_function* is given, it must be a callable that takes two arguments
 +   *src* and *dst*, and will be used to copy *src* to *dest* if
 +   :func:`os.rename` cannot be used.  If the source is a directory,
 +   :func:`copytree` is called, passing it the :func:`copy_function`. The
 +   default *copy_function* is :func:`copy2`.  Using :func:`copy` as the
 +   *copy_function* allows the move to succeed when it is not possible to also
 +   copy the metadata, at the expense of not copying any of the metadata.
  
     .. versionchanged:: 3.3
        Added explicit symlink handling for foreign filesystems, thus adapting