[Python-checkins] [3.7] bpo-34260, shutil: fix copy2 and copystat documentation (GH-8523) (GH-10065)

[Victor Stinner]

https://github.com/python/cpython/commit/861f61b5a93d178e913ad3c760d529ee3155e66d
commit: 861f61b5a93d178e913ad3c760d529ee3155e66d
branch: 3.7
author: Zsolt Cserna <cserna.zsolt at gmail.com>
committer: Victor Stinner <vstinner at redhat.com>
date: 2018-10-23T23:57:55+02:00
summary:

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

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)

files:
M Doc/library/shutil.rst
M Lib/shutil.py

diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst
index 382f75d04f71..12e69a4ea040 100644
--- a/Doc/library/shutil.rst
+++ b/Doc/library/shutil.rst
@@ -166,7 +166,7 @@ Directory and files operations
 .. function:: copy2(src, dst, *, follow_symlinks=True)
 
    Identical to :func:`~shutil.copy` except that :func:`copy2`
-   also attempts to preserve all file metadata.
+   also attempts to preserve file metadata.
 
    When *follow_symlinks* is false, and *src* is a symbolic
    link, :func:`copy2` attempts to copy all metadata from the
diff --git a/Lib/shutil.py b/Lib/shutil.py
index 3c02776a4065..f32c66b3550c 100644
--- a/Lib/shutil.py
+++ b/Lib/shutil.py
@@ -171,11 +171,15 @@ def _copyxattr(*args, **kwargs):
         pass
 
 def copystat(src, dst, *, follow_symlinks=True):
-    """Copy all stat info (mode bits, atime, mtime, flags) from src to dst.
+    """Copy file metadata
 
-    If the optional flag `follow_symlinks` is not set, symlinks aren't followed if and
-    only if both `src` and `dst` are symlinks.
+    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.
 
+    If the optional flag `follow_symlinks` is not set, symlinks aren't
+    followed if and only if both `src` and `dst` are symlinks.
     """
     def _nop(*args, ns=None, follow_symlinks=None):
         pass
@@ -243,8 +247,10 @@ def copy(src, dst, *, follow_symlinks=True):
     return dst
 
 def copy2(src, dst, *, follow_symlinks=True):
-    """Copy data and all stat info ("cp -p src dst"). Return the file's
-    destination."
+    """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.