Will Python exceptions be documented?

Discussion in 'Python' started by Vegard Bakke, Jul 7, 2003.

  1. Vegard Bakke

    Vegard Bakke Guest

    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
    Vegard Bakke, Jul 7, 2003
    #1
    1. Advertising

  2. Vegard Bakke

    John J. Lee Guest

    (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/Cookbook/Python/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
    John J. Lee, Jul 7, 2003
    #2
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. clintonG

    Where are error messages documented?

    clintonG, Feb 10, 2004, in forum: ASP .Net
    Replies:
    1
    Views:
    450
    nfedin
    Feb 10, 2004
  2. Replies:
    4
    Views:
    373
    Peter Flynn
    May 27, 2005
  3. mzo
    Replies:
    3
    Views:
    251
    Michael Hudson
    Feb 24, 2004
  4. Robert Brewer
    Replies:
    1
    Views:
    338
  5. Grant Edwards

    Where are list methods documented?

    Grant Edwards, Feb 1, 2005, in forum: Python
    Replies:
    20
    Views:
    599
    Dennis Lee Bieber
    Feb 4, 2005
Loading...

Share This Page