Will Python exceptions be documented?

[Vegard Bakke]

>From whet I can see, Python documentation is lacking a very important
piece of information.  Very few functions have documented what
exceptions they raise, and under what cicumstances.  Is this a task on
the schedule?


In my opinion, every function that might raise an exception should
state so explicitly in the documentation, even uncaught exceptions
from a subfunction.

I have seen many different examples for catching exceptions from
open(). Which is the right one?

The error from function math.log(0) is a by unpredictable, but at
least that is documentet.  What about all the others? math.asin(2),
shutil, os, sys?

All know that asin(2) is wrong, but how do I know that ValueError is
the exception I should catch, and how do I know that is the only one?
(Sorry, try it is the wrong answere here.)


My other issue with is concerning the documentation of the exceptions
themselves. How can I find out that I can use 'filename', 'errno' and
'strerror' for the exception IOError without having to use
dir(IOError())?  And is it valid in all versions/platforms?



Since I'm critisising the lack of work, I will voulunteer to help out
with the process. But I will need some guidance and pointers in the
beginning.


Python is too good to have a B+ documentation.  We can do better.


Cheers,
Vegard


-- 
Vegard Bakke

My spelling is wobbly. It's good spelling, but it 
wobbles, and the letters get it the wrong places.
                                  Winnie the Pooh
:wq