Designing exceptions in a Python library

Goal

Let callers distinguish the failures they can handle from the ones they cannot, without parsing messages, and preserve the original cause when translating errors across layers.

Prerequisites

A clear picture of the failure classes of the library: invalid input, missing object, conflict, unavailable dependency.

Steps

1. Define class LibraryError(Exception) as the base and one subclass per failure class a caller might handle differently (NotFound, Conflict, Unavailable).
2. Raise the most specific class with a message that states what was expected and what was found, without secrets.
3. When wrapping a lower-level error, use raise Specific(...) from original so that __cause__ is set and the traceback shows both.
4. Catch exceptions only where you can recover, retry or translate them (for example, into an HTTP status at the API boundary); let the rest propagate.
5. Never catch BaseException or bare except: in library code; KeyboardInterrupt and SystemExit must pass through.
6. Document the raised exceptions in the docstring of the public function.

Expected result

Callers write except NotFound: instead of matching strings; logs show the full causal chain; unexpected errors are visible rather than silently swallowed.

Limits and test basis

Overly fine hierarchies become noise; three to six classes cover most libraries. Exceptions are not a substitute for return values in hot paths where failure is the common case. The mechanics follow the cited documentation.