Question

Sorry for the long title, but it seems most descriptive for my question.

Basically, I’m having a difficult time finding exception information in the official python documentation. For example, in one program I’m currently writing, I’m using the shutil libary’s move function:

from shutil import move
move('somefile.txt', '/tmp/somefile.txt')

That works fine, as long as I have write access to /tmp/, there is enough diskspace, and if all other requirements are satisfied.

However, when writing generic code, it is often difficult to guarantee those factors, so one usually uses exceptions:

from shutil import move
try:
    move('somefile.txt', '/tmp/somefile.txt')
except:
    print 'Move failed for some reason.'

I’d like to actually catch the appropriate exceptions thrown instead of just catching everything, but I simply can’t find a list of exceptions thrown for most python modules. Is there a way for me to see which exceptions a given function can throw, and why? This way I can make appropriate cases for each exception, eg:

from shutil import move
try:
    move('somefile.txt', '/tmp/somefile.txt')
except PermissionDenied:
    print 'No permission.'
except DestinationDoesNotExist:
    print "/tmp/ doesn't exist"
except NoDiskSpace:
    print 'No diskspace available.'

Answer points go to whoever can either link me to some relevant documentation that I’ve somehow overlooked in the official docs, or provide a sure-fire way to figure out exactly which exceptions are thrown by which functions, and why.

Thanks!

UPDATE: It seems from the answers given that there really isn’t a 100% straight-forward way to figure out which errors are thrown by specific functions. With meta programming, it seems that I can figure out simple cases and list some exceptions, but this is not a particularly useful or convenient method.

I’d like to think that eventually there will be some standard for defining which exceptions are raised by each python function, and that this information will be included in the official documentation. Until then I think I will just allow those exceptions to pass through and error out for my users as it seems like the most sane thing to do.

Answer 1

To amplify Messa, catch what you expect are failure modes that you know how to recover from. Ian Bicking wrote an article that addresses some of the overarching principles as does Eli Bendersky’s note.

The problem with the sample code is that it is not handling errors, just prettifying them and discarding them. Your code does not “know” what to do with a NameError and there isn’t much it should do other than pass it up, look at Bicking’s re-raise if you feel you must add detail.

IOError and OSError are reasonably “expectable” for a shutil.move but not necessarily handleable. And the caller of your function wanted it to move a file and may itself break if that “contract” that Eli writes of is broken.

Catch what you can fix, adorn and re-raise what you expect but can’t fix, and let the caller deal with what you didn’t expect, even if the code that “deals” is seven levels up the stack in main.