== 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 LeaveIOErrorAlone]].

  (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 WrappingExceptions]], 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.)