Question

Coming from a Java background, I like it when I was warned that I was not catching an exception, without having to read the documentation. And if I did read the documentation about a method, the exception thrown was shown right in the documentation’s method signature.

With Python I have to often read through a paragraph of text in the documentation, to find one sentence stating what exception will be thrown.

Also, I was using a third party library in Python today, http://packages.python.org/kombu/reference/kombu.connection.html and this infuriates me. There is no standard documentation format? I was using the channel method ( http://packages.python.org/kombu/reference/kombu.connection.html#kombu.connection.BrokerConnection.channel ) and it doesnt even state that it throws an exception. I had to find this through trial and error.

Am I missing something obvious here, or are exceptions treated as an afterthought in Python and its documentation.

Answer 1

We love exceptions. They’re a pretty important language feature. Good documentation will generally state what exceptions will be thrown in which cases, and personally I found most documentation to be good in this regard. Of course there’s always some percentage of documentation that isn’t good. Either way, if you’re looking for an explicit free-standing list per function, you’re out of luck. Nobody knows this except the programmers working on the code.

Reading a paragraph doesn’t sound too bad to me, especially since the information that paragraph is usually very important either way. And then there’s <Ctrl+F>raises<Enter>…

There is no standard documentation format?

There’s Sphinx, which is used by many projects (including docs.python.org so you already know it; and also including the project you linked to although it uses a different optical style). Of course nobody can force every project to use it, just like you can’t force them to use the standard coding style. But honestly, I think all projects I’ve used so far except two (PyGame and LEPL) used Sphinx. This may be because I have to use relatively few thanks to the extensive standard library, but still.

I like it when I was warned that I was not catching an exception

Why? At a wild guess, 60% of the exceptions beginners get is because they didn’t code properly, not because of some exceptional enviromental state that needs to be handled. TypeError and ImportError, for instance, simply don’t occur in a bug-free well-written program (save metaprogramming and sections that require extreme dynamism).

In general, if you want the compiler to tell you things about your code you didn’t already knew, you’re using the wrong language. Python is dynamic, you test instead of analyzing statically. Deal with it.