[docs] shutil.copytree error interface is ambiguously docced

[Joshua Rodman]

shutil.copytree() says:

"""
shutil.copytree(src, dst[, symlinks=False[, ignore=None]])¶

    Recursively copy an entire directory tree rooted at src. The destination directory, named by dst, must not already exist; it will be created as well as missing parent directories. Permissions and times of directories are copied with copystat(), individual files are copied using copy2().

    If symlinks is true, symbolic links in the source tree are represented as symbolic links in the new tree; if false or omitted, the contents of the linked files are copied to the new tree.

    If ignore is given, it must be a callable that will receive as its arguments the directory being visited by copytree(), and a list of its contents, as returned by os.listdir(). Since copytree() is called recursively, the ignore callable will be called once for each directory that is copied. The callable must return a sequence of directory and file names relative to the current directory (i.e. a subset of the items in its second argument); these names will then be ignored in the copy process. ignore_patterns() can be used to create such a callable that ignores names based on glob-style patterns.

    If exception(s) occur, an Error is raised with a list of reasons.

    The source code for this should be considered an example rather than the ultimate tool.
"""

Naively, this reads as copytree aborting on exception. "If
exceptions(s) occur, an Error is raised with a list of reasons."
This suggests the copy operation does not complete.

I suggest changing this to:

   If exceptions(s) occur during the copy operation, an Error is raised on completion with a list of all the encountered reasons during the copy operation.

Preferably the format of the Error object or a pointer to the error
object defintion would be included as well.

-josh
-- 
scooby snacks.