From 9f3e3722fc8d5043b4643ca238488fbb23b8c296 Mon Sep 17 00:00:00 2001 From: tangyuan0821 Date: Fri, 15 Aug 2025 10:58:52 +0800 Subject: [PATCH 1/2] gh-125676:clarify shutil.copy2/copy behavior and move fallback --- Doc/library/shutil.rst | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst index dde38498206c46..73e0825267cfd3 100644 --- a/Doc/library/shutil.rst +++ b/Doc/library/shutil.rst @@ -204,9 +204,13 @@ Directory and files operations *src* symbolic link to the newly created *dst* symbolic link. However, this functionality is not available on all platforms. On platforms where some or all of this functionality is - unavailable, :func:`copy2` will preserve all the metadata - it can; :func:`copy2` never raises an exception because it - cannot preserve file metadata. + unavailable, :func:`copy2` will preserve as much metadata as it + can. However, individual metadata-copy operations (for example + changing ownership or setting certain flags) may fail on some + platforms or when the current process lacks privileges; such + failures can raise exceptions. If you need to avoid metadata-related + errors, use :func:`~shutil.copy`, which copies file data and the + permission bits but does not attempt to preserve other metadata. :func:`copy2` uses :func:`copystat` to copy the file metadata. Please see :func:`copystat` for more information From 3335e89c668419e04b27d3ae24f87b9a3b1b681c Mon Sep 17 00:00:00 2001 From: tangyuan0821 Date: Tue, 19 Aug 2025 21:44:31 +0800 Subject: [PATCH 2/2] Update shutil.move documentation --- Doc/library/shutil.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst index 73e0825267cfd3..70bc7947d2b661 100644 --- a/Doc/library/shutil.rst +++ b/Doc/library/shutil.rst @@ -394,9 +394,8 @@ Directory and files operations *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 - copy the metadata, at the expense of not copying any of the metadata. + default *copy_function* is :func:`copy2`. Any copy function with a signature + compatible with copy2() can be used (for instance, :func:`~shutil.copy`). .. audit-event:: shutil.move src,dst shutil.move