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