Velocity Reviews - Computer Hardware Reviews

Velocity Reviews > Newsgroups > Programming > Python > Will Python exceptions be documented?

Reply
Thread Tools

Will Python exceptions be documented?

 
 
Vegard Bakke
Guest
Posts: n/a
 
      07-07-2003
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
 
Reply With Quote
 
 
 
 
John J. Lee
Guest
Posts: n/a
 
      07-07-2003
http://www.velocityreviews.com/forums/(E-Mail Removed) (Vegard Bakke) writes:

> 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?


IIRC, yes.


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


What examples, specifically? The docs say IOError can be raised.
Just about everything can raise ValueError, TypeError,
KeyboardInterrupt and MemoryError, so they aren't typically
documented. I'm not sure exactly when WindowsError (rather than
something more specific) gets raised.

Not answering your question, but as a BTW: in that particular case, if
you're getting uncontrolled input you might sometimes want to
normalise the exceptions raised by catching everything but a few
exceptions. This is useful because you might not have anticipated
every way that weird input might trip up your code (ie. your code may
be buggy). See this recipe and my comment

http://aspn.activestate.com/ASPN/Coo.../Recipe/101853


In fact, I didn't show the try / finally needed to close the file
there, so it should really be:

import traceback
from cStringIO import StringIO

DEBUG = True

def debug(msg):
print msg

def load(filename):
f = open(filename)
try:
try:
# Some code that might raise IOError, or another exception that you
# weren't expecting, if the user is imaginitive enough...
except (AssertionError, KeyboardInterrupt, IOError):
# NOTE WELL the brackets around the exception classes -- an except
# with two arguments means something quite different!
raise
except:
if DEBUG:
f = StringIO()
traceback.print_exc(None, f)
debug("uncaught exception:\n%s" % f.getvalue())
raise IOError, "invalid file '%s'" % filename
finally:
f.close()

load("/some/nonsense/file.txt")


> 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.)


For the math module, the log(0) situation applies. From the 2.3
library docs for the math module:

Note: The math module consists mostly of thin wrappers around the
platform C math library functions. Behavior in exceptional cases is
loosely specified by the C standards, and Python inherits much of
its math-function error-reporting behavior from the platform C
implementation. As a result, the specific exceptions raised in
error cases (and even whether some arguments are considered to be
exceptional at all) are not defined in any useful cross-platform or
cross-release way. For example, whether math.log(0) returns -Inf or
raises ValueError or OverflowError isn't defined, and in cases
where math.log(0) raises OverflowError, math.log(0L) may raise
ValueError instead.


> 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?


That's documented under the base class, EnvironmentError.


> 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

[...]

Great. I'd say just submit some specific doc patches with the
knowledge you already have (as long as you make it clear where you're
unsure). Since that shows you're prepared to do some work on it, it's
likely to get you feedback from the people who know all the details
but don't have time to work on it themselves. Of course, the core
people are probably particularly busy with 2.3 ATM, so don't expect a
rapid response.


John
 
Reply With Quote
 
 
 
Reply

Thread Tools

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off
Trackbacks are On
Pingbacks are On
Refbacks are Off


Similar Threads
Thread Thread Starter Forum Replies Last Post
Exceptions - How do you make it work like built-in exceptions? Lie Python 3 01-14-2008 06:45 PM
Fatal Python error using ctypes & python exceptions mmacrobert Python 1 08-31-2007 03:55 PM
Exceptions + Performance on path without exceptions gratch06@gmail.com C++ 3 04-16-2007 08:52 PM
Checked exceptions vs unchecked exceptions Ahmed Moustafa Java 5 07-14-2004 01:46 PM
Custom exceptions -- inherit from exceptions.Exception? Paul Miller Python 3 11-12-2003 09:24 AM



Advertisments