From 4a59c9699ca8688359c460f98127a12e2db6e63b Mon Sep 17 00:00:00 2001 From: Zsolt Cserna Date: Wed, 24 Oct 2018 23:22:27 +0200 Subject: [2.7] bpo-34260, shutil: fix copy2 and copystat documentation (GH-8523) (GH-10071) Fix the documentation of copy2, as it does not copy file ownership (user and group), only mode, mtime, atime and flags. The original text was confusing to developers as it suggested that this command is the same as 'cp -p', but according to cp(1), '-p' copies file ownership as well. Clarify which metadata is copied by shutil.copystat in its docstring. (cherry picked from commit 4f399be0e70d8b5516b6213568b7665765bb3114) --- Doc/library/shutil.rst | 8 +++++--- Lib/shutil.py | 13 +++++++++++-- 2 files changed, 16 insertions(+), 5 deletions(-) diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst index 6bd8f05..7e9af1a 100644 --- a/Doc/library/shutil.rst +++ b/Doc/library/shutil.rst @@ -82,9 +82,11 @@ Directory and files operations .. function:: copy2(src, dst) - Similar to :func:`shutil.copy`, but metadata is copied as well -- in fact, - this is just :func:`shutil.copy` followed by :func:`copystat`. This is - similar to the Unix command :program:`cp -p`. + Identical to :func:`~shutil.copy` except that :func:`copy2` + also attempts to preserve file metadata. + + :func:`copy2` uses :func:`copystat` to copy the file metadata. + Please see :func:`copystat` for more information. .. function:: ignore_patterns(\*patterns) diff --git a/Lib/shutil.py b/Lib/shutil.py index 0ab1a06..a45436c 100644 --- a/Lib/shutil.py +++ b/Lib/shutil.py @@ -105,7 +105,13 @@ def copymode(src, dst): os.chmod(dst, mode) def copystat(src, dst): - """Copy all stat info (mode bits, atime, mtime, flags) from src to dst""" + """Copy file metadata + + Copy the permission bits, last access time, last modification time, and + flags from `src` to `dst`. On Linux, copystat() also copies the "extended + attributes" where possible. The file contents, owner, and group are + unaffected. `src` and `dst` are path names given as strings. + """ st = os.stat(src) mode = stat.S_IMODE(st.st_mode) if hasattr(os, 'utime'): @@ -134,7 +140,10 @@ def copy(src, dst): copymode(src, dst) def copy2(src, dst): - """Copy data and all stat info ("cp -p src dst"). + """Copy data and metadata. Return the file's destination. + + Metadata is copied with copystat(). Please see the copystat function + for more information. The destination may be a directory. -- cgit v0.12