Issue #12715: Add an optional symlinks argument to shutil functions (copyfile, copymode, copystat, copy, copy2).
When that parameter is true, symlinks aren't dereferenced and the operation
instead acts on the symlink itself (or creates one, if relevant).
Patch by Hynek Schlawack.
diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst
index bb18203..45be0e5 100644
--- a/Doc/library/shutil.rst
+++ b/Doc/library/shutil.rst
@@ -45,7 +45,7 @@
be copied.
-.. function:: copyfile(src, dst)
+.. function:: copyfile(src, dst[, symlinks=False])
Copy the contents (no metadata) of the file named *src* to a file named *dst*.
*dst* must be the complete target file name; look at :func:`copy` for a copy that
@@ -56,37 +56,56 @@
such as character or block devices and pipes cannot be copied with this
function. *src* and *dst* are path names given as strings.
+ If *symlinks* is true and *src* is a symbolic link, a new symbolic link will
+ be created instead of copying the file *src* points to.
+
.. versionchanged:: 3.3
:exc:`IOError` used to be raised instead of :exc:`OSError`.
+ Added *symlinks* argument.
-.. function:: copymode(src, dst)
+.. function:: copymode(src, dst[, symlinks=False])
Copy the permission bits from *src* to *dst*. The file contents, owner, and
- group are unaffected. *src* and *dst* are path names given as strings.
+ group are unaffected. *src* and *dst* are path names given as strings. If
+ *symlinks* is true, *src* a symbolic link and the operating system supports
+ modes for symbolic links (for example BSD-based ones), the mode of the link
+ will be copied.
+ .. versionchanged:: 3.3
+ Added *symlinks* argument.
-.. function:: copystat(src, dst)
+.. function:: copystat(src, dst[, symlinks=False])
Copy the permission bits, last access time, last modification time, and flags
from *src* to *dst*. The file contents, owner, and group are unaffected. *src*
- and *dst* are path names given as strings.
+ and *dst* are path names given as strings. If *src* and *dst* are both
+ symbolic links and *symlinks* true, the stats of the link will be copied as
+ far as the platform allows.
+ .. versionchanged:: 3.3
+ Added *symlinks* argument.
-.. function:: copy(src, dst)
+.. function:: copy(src, dst[, symlinks=False]))
Copy the file *src* to the file or directory *dst*. If *dst* is a directory, a
file with the same basename as *src* is created (or overwritten) in the
directory specified. Permission bits are copied. *src* and *dst* are path
- names given as strings.
+ names given as strings. If *symlinks* is true, symbolic links won't be
+ followed but recreated instead -- this resembles GNU's :program:`cp -P`.
+ .. versionchanged:: 3.3
+ Added *symlinks* argument.
-.. function:: copy2(src, dst)
+.. function:: copy2(src, dst[, symlinks=False])
Similar to :func:`copy`, but metadata is copied as well -- in fact, this is just
:func:`copy` followed by :func:`copystat`. This is similar to the
- Unix command :program:`cp -p`.
+ Unix command :program:`cp -p`. If *symlinks* is true, symbolic links won't
+ be followed but recreated instead -- this resembles GNU's :program:`cp -P`.
+ .. versionchanged:: 3.3
+ Added *symlinks* argument.
.. function:: ignore_patterns(\*patterns)
@@ -104,9 +123,9 @@
:func:`copy2`.
If *symlinks* is true, symbolic links in the source tree are represented as
- symbolic links in the new tree, but the metadata of the original links is NOT
- copied; if false or omitted, the contents and metadata of the linked files
- are copied to the new tree.
+ symbolic links in the new tree and the metadata of the original links will
+ be copied as far as the platform allows; if false or omitted, the contents
+ and metadata of the linked files are copied to the new tree.
When *symlinks* is false, if the file pointed by the symlink doesn't
exist, a exception will be added in the list of errors raised in
@@ -140,6 +159,9 @@
Added the *ignore_dangling_symlinks* argument to silent dangling symlinks
errors when *symlinks* is false.
+ .. versionchanged:: 3.3
+ Copy metadata when *symlinks* is false.
+
.. function:: rmtree(path, ignore_errors=False, onerror=None)