Summary
Fix documentation in shutil.rst that contained two conflicting descriptions about shutil.copy2 and shutil.move. Clarify that copy2 attempts to preserve metadata but that individual metadata-copy operations may raise exceptions on some platforms or when privileges are insufficient; recommend using shutil.copy as the copy_function when higher robustness (avoiding metadata-related failures) is desired.

Related issue
Fixes: #125676

Motivation
The original text contained two mutually contradictory statements: one suggested that copy2 "never raises an exception because it cannot preserve file metadata", while another said that using copy as the fallback copy_function for move allows the move to succeed when it is not possible to also copy metadata. After inspecting Lib/shutil.py, copy2 calls copystat(), and copystat() may raise OSError for some metadata operations (for example, due to lack of privileges or platform limitations). The documentation should therefore state the behavior more precisely to avoid misleading users.

Files changed

• Doc/library/shutil.rst — modify a few lines to make the descriptions of copy2 and copy consistent and clear:
  • State that copy2 attempts to preserve additional metadata but that individual metadata-copy operations may fail and raise exceptions on certain platforms or when privileges are insufficient.
  • Recommend shutil.copy when callers want to avoid metadata-related errors (it copies only the file data and permission bits).

• Issue: shutil.move documentation conflicts with shutil.copy2 documentation #125676

📚 Documentation preview 📚: https://cpython-previews--137792.org.readthedocs.build/