diff options
| author | Barney Gale <barney.gale@gmail.com> | 2024-07-06 16:18:39 (GMT) |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2024-07-06 16:18:39 (GMT) |
| commit | 88fc0655d4a487233efce293277690a799706bf9 (patch) | |
| tree | d39326c16c0d1881a0ba6663ed6c132b18de9d0b /Doc/library | |
| parent | 6239d41527d5977aa5d44e4b894d719bc045860e (diff) | |
| download | cpython-88fc0655d4a487233efce293277690a799706bf9.zip cpython-88fc0655d4a487233efce293277690a799706bf9.tar.gz cpython-88fc0655d4a487233efce293277690a799706bf9.tar.bz2 | |
GH-73991: Support preserving metadata in `pathlib.Path.copy()` (#120806)
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.
Diffstat (limited to 'Doc/library')
| -rw-r--r-- | Doc/library/pathlib.rst | 12 |
1 files changed, 6 insertions, 6 deletions
diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index d7fd56f..f139abd 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -1539,7 +1539,7 @@ Creating files and directories Copying, renaming and deleting ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. method:: Path.copy(target, *, follow_symlinks=True) +.. method:: Path.copy(target, *, follow_symlinks=True, preserve_metadata=False) Copy the contents of this file to the *target* file. If *target* specifies a file that already exists, it will be replaced. @@ -1548,11 +1548,11 @@ Copying, renaming and deleting will be created as a symbolic link. If *follow_symlinks* is true and this file is a symbolic link, *target* will be a copy of the symlink target. - .. note:: - This method uses operating system functionality to copy file content - efficiently. The OS might also copy some metadata, such as file - permissions. After the copy is complete, users may wish to call - :meth:`Path.chmod` to set the permissions of the target file. + If *preserve_metadata* is false (the default), only the file data is + guaranteed to be copied. Set *preserve_metadata* to true to ensure that the + file mode (permissions), flags, last access and modification times, and + extended attributes are copied where supported. This argument has no effect + on Windows, where metadata is always preserved when copying. .. versionadded:: 3.14 |