classification
Title: shutil.copytree error handling non-standard and partially broken
Type: behavior Stage:
Components: Library (Lib) Versions: Python 3.2, Python 3.3, Python 2.7
process
Status: open Resolution: accepted
Dependencies: Superseder:
Assigned To: eric.araujo Nosy List: dhduvall, eric.araujo, lokare.ameya, swalker, tarek, terry.reedy
Priority: normal Keywords: patch

Created on 2010-02-19 22:04 by swalker, last changed 2011-06-15 13:40 by eric.araujo.

Files
File name Uploaded Description Edit
shutil_copytree_doc.patch lokare.ameya, 2011-05-19 07:45 review
Messages (8)
msg99597 - (view) Author: Shawn (swalker) Date: 2010-02-19 22:04
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
msg103685 - (view) Author: Tarek Ziadé (tarek) * (Python committer) Date: 2010-04-20 09:20
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)
msg136061 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-05-16 02:38
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.
msg136268 - (view) Author: Ameya Lokare (lokare.ameya) Date: 2011-05-19 07:45
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).
msg138083 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-06-10 15:37
Thanks for the patch.  Have you had a chance to investigate Terry’s question?
msg138225 - (view) Author: Ameya Lokare (lokare.ameya) Date: 2011-06-13 00:03
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?
msg138325 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-06-14 15:11
I think it would be good.
msg138367 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-06-15 13:40
See also http://mail.python.org/pipermail/docs/2010-August/001207.html for a similar report.
History
Date User Action Args
2011-06-15 13:40:35eric.araujosetmessages: + msg138367
2011-06-14 15:11:50eric.araujosetassignee: tarek -> eric.araujo
messages: + msg138325
versions: - Python 3.1
2011-06-13 00:03:18lokare.ameyasetmessages: + msg138225
2011-06-10 15:37:59eric.araujosetmessages: + msg138083
2011-05-19 07:45:59lokare.ameyasetfiles: + shutil_copytree_doc.patch

nosy: + lokare.ameya
messages: + msg136268

keywords: + patch
2011-05-16 02:38:17terry.reedysetnosy: + terry.reedy

messages: + msg136061
versions: - Python 2.6
2010-05-16 18:28:32eric.araujosetnosy: + eric.araujo
2010-04-20 09:20:59tareksetpriority: normal

assignee: tarek
versions: + Python 3.1, Python 2.7, Python 3.2, Python 3.3
nosy: + tarek

messages: + msg103685
resolution: accepted
2010-02-19 22:12:22dhduvallsetnosy: + dhduvall
2010-02-19 22:04:16swalkercreate