The error handling present in the implementation of shutil.copytree in python 2.6.4 (and perhaps other versions) is non-standard and partially broken.

In particular, I'm unable to find any pydoc documentation that indicates that when copytree raises shutil.Error, that the error instead of the standard 2-tuple or 3-tuple was initialised with a list of entries.

This means that callers catching EnvironmentError will be in for a surprise whenever they check e.args and find a tuple containing a list instead of just a tuple.

Callers will also be disappointed to find that the entries in the list may be tuples or strings due to what looks like a bug in copystat error handling (it's using extend instead of append).

I could possibly live with this behaviour somewhat if it was actually documented and consistent since shutil.Error can be caught specifically instead.

It's also really unfortunate that the tuples that are stored here aren't the actual exception objects of the errors encountered so callers cannot perform more granular error handling (permissions exceptions, etc.).

I'd like to request that this function:

* be fixed to append copystat errors correctly

* have shutil.Error documentation indicate the special args format and explain how it might be parsed

* consider having it record the exception objects instead of the exception message

* suggest that the default str() output for shutil.Error be improved

I agree with all your points. 

The copystat error can be fixed right away and applied for 2.6 to 3.x

For other points, I'll change the way the Error works but this will require an heavy deprecation process.

In the meantime I can document the behavior, and provide some examples in the documentation (eg how to catch and manage the errors that were raised)

I also found the doc confusing. Does "This exception collects exceptions that raised during a multi-file operation." that Error is used for .rmtree or .move? If so, what format. If not, revise. And I also wondered how to access and use an Error.

I've attached a proposed doc patch. I figured I'd move the Error argument format in the description of shutil.copytree, since the format is different for other functions (shutil.move, for example).

Thanks for the patch.  Have you had a chance to investigate Terry’s question?

shutil.Error is raised in copytree, copyfile and move, with a different format in each case. I was thinking the Error argument format could be documented in the descriptions of these functions (possibly with some examples). What do you think?

I think it would be good.

See also http://mail.python.org/pipermail/docs/2010-August/001207.html for a similar report.