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

Wed Oct 24 17:22:34 EDT 2018

https://github.com/python/cpython/commit/4a59c9699ca8688359c460f98127a12e2db6e63b
commit: 4a59c9699ca8688359c460f98127a12e2db6e63b
branch: 2.7
author: Zsolt Cserna <cserna.zsolt at gmail.com>
committer: Victor Stinner <vstinner at redhat.com>
date: 2018年10月24日T23:22:27+02:00
summary:
[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)
files:
M Doc/library/shutil.rst
M Lib/shutil.py

diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst
index 6bd8f0585d77..7e9af1ad5a93 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 0ab1a06f5260..a45436cebccc 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.
 
