[2.7] bpo-34260, shutil: fix copy2 and copystat documentation (GH-8523)

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)

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.