https://github.com/python/cpython/commit/da8f9fb2ea65cc2784c2400fc39ad8c800a67a42
commit: da8f9fb2ea65cc2784c2400fc39ad8c800a67a42
branch: main
author: Dai Wentao <[email protected]>
committer: terryjreedy <[email protected]>
date: 2024-02-04T13:42:58-05:00
summary:
gh-113803: Fix inaccurate documentation for shutil.move when dst is an existing
directory (#113837)
* fix the usage of dst and destination in shutil.move doc
* update shutil.move doc
files:
M Doc/library/shutil.rst
M Lib/shutil.py
diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst
index 7a7dd23177e672..ff8c9a189ab3de 100644
--- a/Doc/library/shutil.rst
+++ b/Doc/library/shutil.rst
@@ -360,21 +360,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 acc9419be4dfca..c19ea0607208af 100644
--- a/Lib/shutil.py
+++ b/Lib/shutil.py
@@ -861,12 +861,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
_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3/lists/python-checkins.python.org/
Member address: [email protected]
