Translating Exceptions Across Layers

## The raised type is part of the signature Python has no checked exceptions and no `throws` clause, so it is easy to forget that the exception types a function lets escape are part of what its callers must code against. If a helper called `load_rows(conn)` allows a database driver's `sqlite3.DatabaseError` to propagate, then every caller that wants to handle a storage failure has to `import sqlite3` and name that class in an `except` clause. The dependency you believed was encapsulated behind a function is now in the caller's import list - not because the caller talks to the database, but because it has to catch the database's errors. That is the concrete harm. Everything else follows from it: * **Replacing the library becomes a breaking change.** Swap the driver and every `except` clause across the codebase names a class that no longer gets raised. The failures are silent: the code still imports, still runs, and simply stops catching. * **Callers are pushed to over-catch.** Faced with an unnameable error surface, people write `except Exception` and lose every distinction that mattered. * **Layers above learn vocabulary they should not have.** A report-building routine that mentions a driver's error class has quietly become a database-aware module. ## What translation looks like Catch the library's type in the single module that owns it, and raise your own: ```python class StorageError(Exception): pass def load_rows(conn): try: return conn.execute("SELECT body FROM reports").fetchall() except sqlite3.DatabaseError as exc: raise StorageError("could not read report rows") from exc ``` Two details carry most of the value. First, the `except` clause names the driver's **base** error class, not one leaf type, so a new failure mode in the driver still comes out as a domain error rather than escaping raw. Second, `from exc` sets the new exception's `__cause__` to the original, so nothing is destroyed: the traceback shows both errors, and an operator reading the log still sees the driver's message underneath yours. ## Translation is a mapping, not a rename The common failure is collapsing everything into one type. If `StorageError` is raised for a missing row, a bad credential, a syntax error in your own SQL and a dead network link alike, the caller can do nothing with it except log and give up - which is exactly what it could have done with `except Exception`. A useful translation preserves the distinctions the caller can act on, and only those. A missing report is worth its own type because a caller can substitute a default; a corrupt store is worth its own type because a caller should abort. Anything the caller cannot act on differently belongs under one shared type. That is also the test for how many domain types to invent: not "how many error classes does the library have", but "how many different reactions does my caller have". ## When *not* to wrap Wrapping is a cost, and there are cases where it buys nothing: * **Errors your own code raised for the caller's benefit.** If you validate an argument and raise `ValueError`, wrapping it in `ConfigError` adds a layer without adding information. * **Well-known stdlib types the caller already handles sensibly.** `OSError`, `TimeoutError` and `KeyError` are shared vocabulary; hiding them behind a domain type is sometimes right at a hard boundary and often just noise inside one application. * **Bugs.** A `TypeError` or `AttributeError` from your own module is a defect, not a domain condition. Wrapping it disguises a stack trace you want to see intact. * **Every layer.** Translating once at the boundary that owns the abstraction is the point; translating again one call up produces nested wrappers whose innermost useful message is three `__cause__` links away. ## The shape of the wrapper class Keep the domain exception cheap: a class inheriting from `Exception` with a readable message. If a caller needs a fact to make a decision - which report was missing, which key failed - put it in an attribute rather than forcing the caller to parse the message string. Resist putting driver-specific fields on it (a vendor error number, a cursor object): the moment the wrapper carries the library's vocabulary in its attributes, callers start depending on that, and the abstraction has leaked through the class you invented to protect it. ## Why interviewers ask this It is a compact test of whether a candidate thinks about a function's public surface at all. The weak answer is "so the error message is nicer". The strong answer names the caller: who has to import what in order to catch this, and what breaks when the library underneath changes.