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

NewUserHa · web-flow · commit d9a2e587fca4 · 2026-02-05T17:45:14.000Z
diff --git 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
