Handling Python Exceptions

Python
def get_item(container, key, index):
    if not isinstance(key, str):
        raise TypeError(f"key must be str, got {type(key).__name__}")
    if index < 0 or index >= len(container):
        raise IndexError(f"index {index} out of range")
    try:
        return container[key][index]
    except KeyError as e:
        raise LookupError(f"key {key!r} not found") from e

Pick the exception based on the nature of the error, not convenience. Always raise the most specific applicable built-in before inventing a custom one.

Progress:

• Identify the failure category (bad value, bad type, missing resource, bad state, environment/system failure)
• Match to the most specific built-in exception
• Add a clear, actionable message with relevant values
• Chain exceptions with from when translating one error into another
• Only subclass a built-in when the built-ins genuinely don't fit
• Catch narrowly; never bare except: unless re-raising or at a top-level boundary

Step 1: Classify the failure

Step 2: Write the raise site

• Include the offending value(s) in the message: f"expected positive int, got {n}".
• Never raise a bare string or non-exception object.
• Use raise X(...) from original when converting one exception into another to preserve the causal chain; use from None to deliberately suppress chaining noise.

Step 3: Catch precisely

• Catch the narrowest exception(s) that a caller can meaningfully recover from.
• Catch tuples explicitly rather than broad supertypes: except (KeyError, IndexError):
• Never swallow KeyboardInterrupt or SystemExit (they subclass BaseException, not Exception) — don't use bare except: for that reason.
• Use except* SomeError: (3.11+) when handling ExceptionGroups from concurrent tasks.

Step 4: Custom exceptions only when needed

Subclass the closest matching built-in (e.g. class ConfigError(ValueError):) rather than Exception directly, so existing except ValueError handlers still work.

Example 1: Input: Function receives a negative value for a "count" parameter that must be non-negative. Output:

Python
if count < 0:
    raise ValueError(f"count must be non-negative, got {count}")

Example 2: Input: A dict lookup fails inside a function that's translating a public-facing API error. Output:

Python
try:
    config = registry[name]
except KeyError as e:
    raise LookupError(f"no config registered under {name!r}") from e

Example 3: Input: Opening a file that may not exist. Output:

Python
try:
    with open(path) as f:
        data = f.read()
except FileNotFoundError:
    data = default_data
except PermissionError as e:
    raise RuntimeError(f"cannot read {path}: insufficient permissions") from e

Example 4: Input: An abstract base class method that subclasses must override. Output:

Python
class Shape:
    def area(self):
        raise NotImplementedError("subclasses must implement area()")