From 78e2438e2cd8ef865e20e30dcec7acd7d1b6b2b1 Mon Sep 17 00:00:00 2001 From: Dai Wentao Date: Tue, 9 Jan 2024 10:10:02 +0800 Subject: [PATCH 1/3] gh-113803: Fix inaccurate documentation for shutil.move when dst is an existing directory #113803 --- Doc/library/shutil.rst | 13 ++++++++----- Lib/shutil.py | 6 +++--- 2 files changed, 11 insertions(+), 8 deletions(-) diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst index d9ec2cbc47e611..f830096a95629b 100644 --- a/Doc/library/shutil.rst +++ b/Doc/library/shutil.rst @@ -360,12 +360,15 @@ 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 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 to *dst* using *copy_function* and then diff --git a/Lib/shutil.py b/Lib/shutil.py index acc9419be4dfca..f5d54295c542ae 100644 --- a/Lib/shutil.py +++ b/Lib/shutil.py @@ -861,9 +861,9 @@ 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. From 36485b5dab92e82d4a1debc20e4f18747dbb6308 Mon Sep 17 00:00:00 2001 From: daiwt Date: Sat, 27 Jan 2024 22:43:19 +0800 Subject: [PATCH 2/3] fix the usage of dst and destination in shutil.move doc --- Doc/library/shutil.rst | 16 ++++++++-------- Lib/shutil.py | 4 ++-- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst index f830096a95629b..7e3223a99b0dfc 100644 --- a/Doc/library/shutil.rst +++ b/Doc/library/shutil.rst @@ -367,17 +367,17 @@ Directory and files operations 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 :func:`os.rename` semantics. + 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 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 *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 f5d54295c542ae..c19ea0607208af 100644 --- a/Lib/shutil.py +++ b/Lib/shutil.py @@ -865,8 +865,8 @@ def move(src, dst, copy_function=copy2): 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 From 351327eee83326fba223122ffa50ced700ed3b8a Mon Sep 17 00:00:00 2001 From: daiwt Date: Thu, 1 Feb 2024 20:49:34 +0800 Subject: [PATCH 3/3] update shutil.move doc --- Doc/library/shutil.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst index 7e3223a99b0dfc..c370ad9ebc5035 100644 --- a/Doc/library/shutil.rst +++ b/Doc/library/shutil.rst @@ -373,7 +373,7 @@ Directory and files operations If the destination is on the current filesystem, then :func:`os.rename` is 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 in or as *dst* and *src* will be removed. + 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 the destination, and will be used to copy *src* to the destination