[SciPy-dev] How to handle exceptional cases in algorithms ? Exception vs Warning

[Robert Kern]

David Cournapeau wrote:
> Hi,
> 
>     I have a general question regarding the implementation of algorithm 
> in python. When something unusual, but possible (that is it is a 
> limitation of the algorithm, not a bug), is there a global policy which 
> is better than another one: emitting a warning vs exception.
>     For example, I recently reworked a bit the internal of 
> scipy.cluster, which implements Vector Quantization and kmean algorithm. 
> For those not familiar with those algorithms, the goal of kmeans is to 
> separate a dataset into k clusters according to a criteria generally 
> based on euclidian distance. Sometimes, it may happens during 
> computation that one of the cluster has no data attached to it, which 
> means that the algorithm won't returns k clusters at the end. Emitting a 
> warning means that the computation can continue anyway, but those cases 
> cannot be caught programmatically. On the contrary, raising an exception 
> can be caught, but needs to be handled, and may break running code.
>     Is there really one choice better then the other, or is it a matter 
> of taste ?

A problem with exceptions in expensive calculations is that they stop the
calculation outright. Unless if the calculation is carefully coded, it can't be
restarted at the point of the exception. This is why we trap hardware floating
point exceptions and uses NaNs and infs by default in numpy. Parts of the answer
may be nonsensical, but you get the rest of your data which might be critical to
debugging the issue.

I like to reserve exceptions for things that are fatal to the calculation as a
whole. If the calculation *can't* continue because an assumption gets violated
in the middle, go ahead and raise an exception. If you can, use a custom
exception that stores information that can be used to debug the problem.
Exceptions don't have to just contain a string message.

However, if you are just running into something unusual, or only technically a
violation of assumptions (i.e. the results don't really make sense according to
the algorithm, but the code will still work), issue a custom warning instead.
Using the warnings module, the user can set things up to raise an exception when
the warning is issued if he really wants that.

-- 
Robert Kern

"I have come to believe that the whole world is an enigma, a harmless enigma
 that is made terrible by our own mad attempt to interpret it as though it had
 an underlying truth."
  -- Umberto Eco