gh-142407: Clarify copy performance on Windows in shutil docs (GH-142408)

diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst
index 2c15fed8dd5e4d7198b053e78658865cbe31f7cb..ec3c8d600ad17150ac6943a9f4449410a17d5cb0 100644 (file)
--- a/Doc/library/shutil.rst
+++ b/Doc/library/shutil.rst
@@ -540,7 +540,9 @@ On Solaris :func:`os.sendfile` is used.
 
 On Windows :func:`shutil.copyfile` uses a bigger default buffer size (1 MiB
 instead of 64 KiB) and a :func:`memoryview`-based variant of
-:func:`shutil.copyfileobj` is used.
+:func:`shutil.copyfileobj` is used, which is still reads and writes in a loop.
+:func:`shutil.copy2` uses the native ``CopyFile2`` call on Windows, which is the most
+efficient method, supports copy-on-write, and preserves metadata.
 
 If the fast-copy operation fails and no data was written in the destination
 file then shutil will silently fallback on using less efficient