GH-73991: Support preserving metadata in pathlib.Path.copy()

[barneygale]

Add preserve_metadata keyword-only argument to pathlib.Path.copy(), defaulting to false. When set to true, we copy timestamps, permissions, extended attributes and flags where available, like shutil.copystat(). The argument has no effect on Windows, where metadata is always copied.

Internally (in the pathlib ABCs), path types gain _readable_metadata and _writable_metadata attributes. These sets of strings describe what kinds of metadata can be retrieved and stored. We take an intersection of source._readable_metadata and target._writable_metadata to minimise reads/writes. A new _read_metadata() method accepts a set of metadata keys and returns a dict with those keys, and a new _write_metadata() method accepts a dict of metadata. We might make these public in future, but it's hard to justify while the ABCs are still private.

• Issue: Support moving across filesystems in pathlib.Path, as shutil.move() does #73991

---

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

[bedevere-bot]

⚠️⚠️⚠️ Buildbot failure ⚠️⚠️⚠️

Hi! The buildbot PPC64LE Fedora Stable Clang Installed 3.x has failed when building commit 88fc065.

What do you need to do:

1. Don't panic.
2. Check the buildbot page in the devguide if you don't know what the buildbots are or how they work.
3. Go to the page of the buildbot that failed (https://buildbot.python.org/all/#builders/451/builds/4646) and take a look at the build logs.
4. Check if the failure is related to this commit (88fc065) or if it is a false positive.
5. If the failure is related to this commit, please, reflect that on the issue and make a new Pull Request with a fix.

You can take a look at the buildbot page here:

https://buildbot.python.org/all/#builders/451/builds/4646

Failed tests:

• test_pathlib

Failed subtests:

• test_copy_file_preserve_metadata - test.test_pathlib.test_pathlib.PathSubclassTest.test_copy_file_preserve_metadata
• test_copy_file_preserve_metadata - test.test_pathlib.test_pathlib.PathTest.test_copy_file_preserve_metadata
• test_copy_file_preserve_metadata - test.test_pathlib.test_pathlib.PosixPathTest.test_copy_file_preserve_metadata

Summary of the results of the build (if available):

==

Click to see traceback logs

Traceback (most recent call last):
  File "/home/buildbot/buildarea/3.x.cstratak-fedora-stable-ppc64le.clang-installed/build/target/lib/python3.14/test/test_pathlib/test_pathlib.py", line 660, in test_copy_file_preserve_metadata
    os.setxattr(source, b'user.foo', b'42')
    ~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^
OSError: [Errno 95] Operation not supported: '/tmp/test_python_pfjupu1y/test_python_2060648æ/@test_2060648_tmpæ/fileA'


Traceback (most recent call last):
  File "/home/buildbot/buildarea/3.x.cstratak-fedora-stable-ppc64le.clang-installed/build/target/lib/python3.14/test/test_pathlib/test_pathlib.py", line 660, in test_copy_file_preserve_metadata
    os.setxattr(source, b'user.foo', b'42')
    ~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^
OSError: [Errno 95] Operation not supported: '/tmp/test_python__riczf75/test_python_2046711æ/@test_2046711_tmpæ/fileA'