(Danny, please preserve attribution lines for the quoted text.) Danny Yoo <d...@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 _______________________________________________ Tutor maillist - Tutor@python.org To unsubscribe or change subscription options: https://mail.python.org/mailman/listinfo/tutor