[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)

diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst
index 6bd8f0585d776c22998a56546066f5133aa45f26..7e9af1ad5a9373407a958080c506b241d52fe939 100644 (file)
--- 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 0ab1a06f5260ed032a24709575a72367f3284732..a45436cebccc7b694a092b350f36395c495ce960 100644 (file)
--- 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.