From ec32b6bce7a9d2c58d1ad040c2cdca34de819634 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 6 Jan 2008 16:12:39 +0000 Subject: #1559684: document that shutil.copy* doesn't copy all metadata on Posix and Windows too. --- Doc/library/shutil.rst | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst index 5bd69cd..9f79c0f 100644 --- a/Doc/library/shutil.rst +++ b/Doc/library/shutil.rst @@ -17,16 +17,21 @@ copying and removal. For operations on individual files, see also the :mod:`os` module. .. warning:: + + Even the higher-level file copying functions (:func:`copy`, :func:`copy2`) + can't copy all file metadata. - On MacOS, the resource fork and other metadata are not used. For file copies, - this means that resources will be lost and file type and creator codes will - not be correct. + On POSIX platforms, this means that file owner and group are lost as well + as ACLs. On MacOS, the resource fork and other metadata are not used. + This means that resources will be lost and file type and creator codes will + not be correct. On Windows, file owners, ACLs and alternate data streams + are not copied. .. function:: copyfile(src, dst) - Copy the contents of the file named *src* to a file named *dst*. The - destination location must be writable; otherwise, an :exc:`IOError` exception + Copy the contents (no metadata) of the file named *src* to a file named *dst*. + The destination location must be writable; otherwise, an :exc:`IOError` exception will be raised. If *dst* already exists, it will be replaced. Special files such as character or block devices and pipes cannot be copied with this function. *src* and *dst* are path names given as strings. @@ -81,7 +86,7 @@ copying and removal. For operations on individual files, see also the files are copied to the new tree. If exception(s) occur, an :exc:`Error` is raised with a list of reasons. - The source code for this should be considered an example rather than a tool. + The source code for this should be considered an example rather than a tool. .. versionchanged:: 2.3 :exc:`Error` is raised if any exceptions occur during copying, rather than @@ -114,7 +119,7 @@ copying and removal. For operations on individual files, see also the Recursively move a file or directory to another location. - If the destination is on our current filesystem, then simply use rename. + If the destination is on the current filesystem, then simply use rename. Otherwise, copy src to the dst and then remove src. .. versionadded:: 2.3 @@ -122,7 +127,7 @@ copying and removal. For operations on individual files, see also the .. exception:: Error - This exception collects exceptions that raised during a mult-file operation. For + This exception collects exceptions that raised during a multi-file operation. For :func:`copytree`, the exception argument is a list of 3-tuples (*srcname*, *dstname*, *exception*). -- cgit v0.12