[Tutor] Is there a convenient table of Python 3.4 exceptions?

[Ben Finney]

(Danny, please preserve attribution lines for the quoted text.)

Danny Yoo <dyoo at hashcollision.org> writes:

> > Of course I can force an error to occur in the interpreter and see
> > what comes up for each type of error I wish to catch. Is there such
> > a table or list?
>
> […]
> Usually the documentation should say what kinds of exceptions to
> expect. If you find an exception to this, please bring it up, and one
> of us can investigate: maybe the documentation can be improved.

That's rather too sweeping a statement, and it's definitely not true for
Python's standard library documentation::

    >>> import signal

    >>> signal.getsignal(None)
    Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
    TypeError: an integer is required (got type NoneType)

    >>> signal.getsignal(500000)
    Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
    ValueError: signal number out of range

There's nothing in the documentation of ‘signal.getsignal’ which says it
will raise either of those exceptions. I'd say it's a safe bet there are
numerous other exception classes that will be raised calling that
function, too. That's just one, chosen quickly and arbitrarily to prove
the point.

The same goes for the vast majority of functions in the standard
library; most possible exception classes go unmentioned in the
documentation for that function1, because exceptions are a normal part
of operating on Python values (think of the wealth of possible exception
classes that can come from passing in a file-like object to many
functions).

Indeed, most functions can't possibly have exhaustive documentation for
what exception classes might be raised, because most of those possible
exceptions are to be raised by the code implementing the *parameter*
values, not raised by the code implementing that function.

Should every function in every module of the standard library document
every exception class that could be raised by that function? I'd say
clearly not; the result would be uselessly cluttered.

Where should the line be drawn? I think, in the case of the standard
library, the line is already drawn at the right place. The documentation
should describe situations that *someone already familiar with Python* –
and with the types of objects they're passing to a function – would not
know exactly what exception class might be raised. But for most
functions, most of the exception classes they might raise are not
documented, because when they are raised it's obvious.

Is this a hurdle for newcomers? Yes, and that's why the standard library
API documentation is not a tutorial. We have separate tutorial
documentation for that.

It's not a problem with the documentation of ‘signal.getsignal’ that it
doesn't have an exhaustive list of all exception classes that might be
raised. This is Python, not Java; exceptions are used prolifically as a
flow control method, for code to let its call stack know something
unusual occurred.

-- 
 \     “I went camping and borrowed a circus tent by mistake. I didn't |
  `\      notice until I got it set up. People complained because they |
_o__)                           couldn't see the lake.” —Steven Wright |
Ben Finney