[3.11] gh-113803: Fix inaccurate documentation for shutil.move when dst is an existin...

* fix the usage of dst and destination in shutil.move doc
* update shutil.move doc
(cherry picked from commit da8f9fb2ea65cc2784c2400fc39ad8c800a67a42)

Co-authored-by: Dai Wentao <dwt136@gmail.com>

diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst
index dd656f65c18abdb5384b8cb14bcb3cc23a9c6e70..82259949670994e6f8288eef2b2f5ae0a21914c5 100644 (file)
--- a/Doc/library/shutil.rst
+++ b/Doc/library/shutil.rst
@@ -348,21 +348,24 @@ Directory and files operations
 
 .. function:: move(src, dst, copy_function=copy2)
 
-   Recursively move a file or directory (*src*) to another location (*dst*)
-   and return the destination.
+   Recursively move a file or directory (*src*) to another location and return
+   the destination.
 
-   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 *dst* is an existing directory or a symlink to a directory, then *src*
+   is moved inside that directory. The destination path in that directory must
+   not already exist.
+
+   If *dst* 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 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.
+   used. Otherwise, *src* is copied to the destination using *copy_function*
+   and then removed.  In case of symlinks, a new symlink pointing to the target
+   of *src* will be created as the destination 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 *dst* if
-   :func:`os.rename` cannot be used.  If the source is a directory,
+   If *copy_function* is given, it must be a callable that takes two arguments,
+   *src* and the destination, and will be used to copy *src* to the destination
+   if :func:`os.rename` cannot be used.  If the source is a directory,
    :func:`copytree` is called, passing it the *copy_function*. The
    default *copy_function* is :func:`copy2`.  Using :func:`~shutil.copy` as the
    *copy_function* allows the move to succeed when it is not possible to also

diff --git a/Lib/shutil.py b/Lib/shutil.py
index 185655ff2d3a15cb53a5a25e8d1c4d3f588bf33d..79b38cf45640d0fb3f0d144c00fb16601c0f6d31 100644 (file)
--- a/Lib/shutil.py
+++ b/Lib/shutil.py
@@ -813,12 +813,12 @@ def move(src, dst, copy_function=copy2):
     similar to the Unix "mv" command. Return the file or directory's
     destination.
 
-    If the destination is a directory or a symlink to a directory, the source
-    is moved inside the directory. The destination path must not already
-    exist.
+    If dst is an existing directory or a symlink to a directory, then src is
+    moved inside that directory. The destination path in that directory must
+    not already exist.
 
-    If the destination already exists but is not a directory, it may be
-    overwritten depending on os.rename() semantics.
+    If dst already exists but is not a directory, it may be overwritten
+    depending on os.rename() semantics.
 
     If the destination is on our current filesystem, then rename() is used.
     Otherwise, src is copied to the destination and then removed. Symlinks are