diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst index dde38498206c46..70bc7947d2b661 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 @@ -390,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