Merged revisions 59774-59783 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/trunk

........
  r59774 | georg.brandl | 2008-01-06 16:41:50 +0100 (Sun, 06 Jan 2008) | 2 lines

  #1501: document that 0**0 == 1.
........
  r59775 | georg.brandl | 2008-01-06 16:48:20 +0100 (Sun, 06 Jan 2008) | 2 lines

  #759525: document that dir() doesn't return metaclass attrs when given a class as arg.
........
  r59776 | georg.brandl | 2008-01-06 16:55:26 +0100 (Sun, 06 Jan 2008) | 2 lines

  #1615275: clarify return object types of different tempfile factories.
........
  r59777 | georg.brandl | 2008-01-06 17:01:26 +0100 (Sun, 06 Jan 2008) | 2 lines

  #1727024: document that Popen.returncode is set by Popen.poll/wait.
........
  r59778 | georg.brandl | 2008-01-06 17:04:56 +0100 (Sun, 06 Jan 2008) | 2 lines

  #1686390: add example for csv.Sniffer use.
........
  r59779 | georg.brandl | 2008-01-06 17:12:39 +0100 (Sun, 06 Jan 2008) | 2 lines

  #1559684: document that shutil.copy* doesn't copy all metadata on Posix and Windows too.
........
  r59780 | georg.brandl | 2008-01-06 17:17:56 +0100 (Sun, 06 Jan 2008) | 2 lines

  #1582: document __reversed__, patch by Mark Russell.
........
  r59781 | georg.brandl | 2008-01-06 17:22:56 +0100 (Sun, 06 Jan 2008) | 2 lines

  #1499: Document compile() exceptions.
........
  r59782 | georg.brandl | 2008-01-06 17:49:50 +0100 (Sun, 06 Jan 2008) | 2 lines

  #1325: Add docs and tests for zipimporter.archive and zipimporter.prefix.
........

1 files changed, 12 insertions, 7 deletions

diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst
index 3275179..f80c893 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.
@@ -106,13 +111,13 @@ 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.
 
 
 .. 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*).