One thing that bothers me in my day-to-day Python work is that often libraries don’t document the errors that can be thrown by their functions. As the language lacks a “throws” statement, I found myself digging through library code on multiple occasions.
How do people approach this?
As much as I understand that checked exceptions (the general term for the 'throws' feature) can lead to a bit of a maintenance nightmare and doesn't necessarily scale well with deeper call stacks, I have found python documentation extremely lacking in this area too.
I think what I've come to understand is that you can treat errors you don't know about as non-recoverable, because that's most likely what they are anyway if they aren't readily documented. Let them bubble up basically, and handle them at the top level if necessary to prevent crashes in prod/make sure they are logged correctly and so on.
What they mean is that in Java, for example, a method has to explicitly state which exceptions it might throw as part of its signature. Note that they said "throws", not "throw".
Ah, I understand now. Well, by default Python doesn't declare a return type either yet the tools are able to infer it in many cases; I see no reason why tools like mypy couldn't similarly infer the raised exception types as well.
Plus, the typing annotations could presumably be expanded to include some notification to declare raised exception types explicitly.
Yes sure, but the raise statement is part of the implementation (like throw in Java), and not part of the signature (throws), which would presumably make it into a generated API documentation.
Comments
One thing that bothers me in my day-to-day Python work is that often libraries don’t document the errors that can be thrown by their functions. As the language lacks a “throws” statement, I found myself digging through library code on multiple occasions. How do people approach this?
As much as I understand that checked exceptions (the general term for the 'throws' feature) can lead to a bit of a maintenance nightmare and doesn't necessarily scale well with deeper call stacks, I have found python documentation extremely lacking in this area too.
I think what I've come to understand is that you can treat errors you don't know about as non-recoverable, because that's most likely what they are anyway if they aren't readily documented. Let them bubble up basically, and handle them at the top level if necessary to prevent crashes in prod/make sure they are logged correctly and so on.
I'm not sure what you mean by this? Python has the "raise" statement [0], which "throws" an error from within a function or other code.
[0] https://docs.python.org/3/reference/simple_stmts.html#raise
They're talking about Java's Checked Exceptions: https://www.baeldung.com/java-checked-unchecked-exceptions which are part of a method's declaration `void foo() throws KaboomException`
The ironic thing is that Checked Exceptions aren't particularly well-loved in Java. For example, Kotlin (which is like Java++) did away with them.
What they mean is that in Java, for example, a method has to explicitly state which exceptions it might throw as part of its signature. Note that they said "throws", not "throw".
Python does not have that.
Ah, I understand now. Well, by default Python doesn't declare a return type either yet the tools are able to infer it in many cases; I see no reason why tools like mypy couldn't similarly infer the raised exception types as well.
Plus, the typing annotations could presumably be expanded to include some notification to declare raised exception types explicitly.
Yes sure, but the raise statement is part of the implementation (like throw in Java), and not part of the signature (throws), which would presumably make it into a generated API documentation.