How to set up your module exceptions to be useful

Suppose that you are writing a Python module that has exceptions as part of its interface, and you want them to actually be useful to people. From the perspective of a sometimes grumpy user of module exceptions, here is my opinions on what you should do:

• all exceptions that you expect people to actually catch should descend from a common ancestor class, so that people can just do 'except YourException, e:' and be done with it.

  If you have an exception you raise for internal errors and other impossible situations, do not make it part of this hierarchy; otherwise people will catch it when you don't want them to.

• people will mostly use your error exceptions by turning them into strings (and printing them out). Make sure that this gives useful information.

• you need to document what fields your exceptions have. If you do not, people will just str() your exceptions and ignore any information that this misses.
• if you have multiple exception classes, try to have as many common fields in them as possible. As a pragmatic thing, expect people to mostly ignore unique fields unless they have important information that people need to act on.

• do not ever reuse or subclass standard exceptions, especially IOError and OSError.

  (If you are ever tempted to break this rule, make absolutely sure that your versions of these exceptions are exactly identical to the real ones.)

• if you call code from other modules, you should capture and wrap up their exceptions, turning them into exceptions of your own. This is much easier for your callers to deal with, since they don't have to know what other modules you use (or care if you change what modules you use).

In general, I would say that you should avoid the temptation to get too complex in error handling. Put yourself in the shoes of the typical person using your module; are you going to care about anything beyond the fact that some sort of an error happened? Generally not. Then you just need a single exception class with a useful string error message, and you're done.

(I admit that I don't always stick to this simple model for my own code; I sometimes have an irrepressible urge to subclass my overall module error class so that I can distinguish this sort of error from that sort of error and so on. Then I never use any of these features.)