4

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.

Improve this question
3
  • 2
    Well, go complain to the author of that documentation, then. It's not a problem with the language. Commented Jun 8, 2011 at 19:15
  • 1
    I don't have enough to add that's not present in the answers already, but just so you know the terminology -- Java uses checked exceptions, which means you can always know what a method will throw. There are varying views on if this is a good thing or not... Commented Jun 8, 2011 at 19:16
  • 1
    @DanielDiPaolo: Not all exceptions in Java are checked, though. Commented Jun 8, 2011 at 19:21

5 Answers 5

Reset to default
14

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.

Improve this answer
Sign up to request clarification or add additional context in comments.

12 Comments

I was curious about that myself. Granted, it is a bit... aggressive.
But are there any factual errors or highly dubious claims? If so, I'd prefer to be corrected. Or am I being offensive? If so, I am sorry, but you have to tell me. (And no, presenting a point of view that isn't accepted in another ecosystem is not an offence.)
Your reply was that the programmers working the code were the only ones that could tell you the exception list. How is that possible without an automated check? I could call multiple modules in the standard library and almost right away have no idea what exceptions are thrown because I didn't program those, the interpreter can't tell me, and the docs may not be complete. This IS a problem with the language when you can never tell when you have dealt properly with all exceptions that could be thrown from your method + all libraries it uses. "Deal with it" is just a poor response IMO.
@Brandon: The documentation only needs to tell you about those exceptions that you should catch, e.g., KeyError when indexing. These exceptions act as sentinel return values. If some library that is called raises some exception in an exceptional circumstance, then you probably shouldn't catch that. "Deal with it" was a poor way to put it. In fact, you shouldn't do anything about it. Your first point is right that it's impossible to know what exceptions are raised, but it's not a problem with the language.
Its kinda gross that you say "we love exceptions" as if you are a physical embodyment of the python community. Please speak for yourself. Also, I have a very hard time figuring out how to get information out of exceptions in python. If you love them so much, why are they so hard to use properly? Where are my stack traces that tell me something went wrong? Where are useful exception messages?
|
6

Bruce Eckel discusses Java checked exceptions vs Python exceptions at length. Key quote:

When I started using Python, all the exceptions appeared, none were accidentally "disappeared." If you want to catch an exception, you can, but you aren't forced to write reams of code all the time just to be passing the exceptions around. They go up to where you want to catch them, or they go all the way out if you forget (and thus they remind you) but they don't vanish, which is the worst of all possible cases. I now believe that checked exceptions encourage people to make them vanish. Plus they make much less readable code.

It's worth reading the whole article.

Regarding documentation I say that yes, some documentation is bad.

Improve this answer

Comments

5

Python does not have the same requirements for declaring exceptions that Java does. Most languages don't. For that matter, Java will often throw exceptions which are not immediately declared (NullPointerException anyone?). It is polite to document exceptions in all languages, but in a world where we can't even guarantee that a public method will even be documented at all, is this really that surprising?

Looking at the library you're using, it seems like you needed to instantiate a Transport object (the thing which really raised the Exception) does have a list of exceptions which are thrown. That's the real object throwing the exceptions, not the BrokerConnection.

Do you know about the traceback module? It might help you track down these issues in the future.

Improve this answer

2 Comments

You don't even need traceback. Just don't swallow exceptions brainlessly and you'll get a nice crash including complete traceback and source lines.
He said that he was using trial and error. I was assuming he had a good reason for having an except clause wrapping this block of code.
0

I think it's a matter of perspective. The Java system has it's own faults. For example, most of the time in Java I found that I was just writing a printStackTrace. Sometimes, I needed to do something more complicated. For example, the system needed to print error messages to the user that was connected via telnet. Again, there was a huge amount of boilerplate.

This is why liked that python has it's way of letting you define a single function to catch all uncaught exceptions: sys.excepthook. Granted, that comes with it's own set of problems, but I like that the functionality is there if I need it.

Improve this answer

Comments

0

While I can't vouch for your experience with the 3rd party library you referred to, I'd say that at least documentation of the Exceptions is expected. Take the built-in smtplib for example. The Exceptions that can be throw are explained, and the methods include information about which ones they'll throw and why.

As far as knowing ahead of time what exceptions could be thrown, whether you're failing to account for one, etc - you may find some code introspection in an IDE that will give you what you're after.

In my experience, exceptions are either things you know know ahead of time are coming up because you've got uncontrollable setup conditions (dealing with user input, etc) or you operate using methods that encapsulate the behavior in a way that rules them out. For example, in Python, if you were working with an Object that should have a given attribute, but you're uncertain that you can guarantee that it will have this attribute, instead of making a call to Object.method() you do this instead:

# getattr uses the arguments (object, 'attribute', default)
toCall = getattr(MyInstance, 'methodName', None)

if toCall is not None:
  toCall(args)

# or if you prefer
if toCall is None:
  myDialogClass.NotifyUser('Object does not contain necessary method.')

When working with collections like dictionaries it's even easier:

nums = dict((i, i) for i in range(30))

# Here the .get() method takes the form (key, default)
# No such thing as a KeyError 
nums.get('50', None)

So, generally, when you discuss python programming, the idea is not that you need to make sure every exception is accounted for. Quite the opposite. Account for the ones you must, but program using idioms that minimize the number of them you have to deal with.

Improve this answer

3 Comments

You don't need to code that defensively. If the attribute's not there, that usually means the caller passed bogus parameters. Tell him by crashing the process and shouting at him, and the fix should be there in an instant ;)
@delnan - Except that what if the "caller" is actually a "customer" who wasn't in a ton of control over what was being passed, and isn't technical enough to necessarily correct it? Crashing makes a lot of sense a lot of the time, but sometimes the situation presents itself where this type of defensive coding is required in order to ensure stability of other things. :)
If it's coming from a user (or any other input), sure, be as liberal and defensive as reasonably possible. But if you write a function which doesn't interact with the outside world but is called by other code (be it in the same project or in another one), it the job of those callers to either pass usable data or try anyway and recover if the callee takes offense. Biting the bullet and applying some abritary default when given unusable input is like catching exceptions you can't handle just so the error goes away.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.