Custom Exceptions in Python

Analogy categoryAnalogies

1. Introduction

Built-in exceptions like ValueError or KeyError are generic; they don't tell a caller which specific business rule was violated. Custom exceptions let you define new exception types tailored to your application's domain, such as InsufficientFundsError or InvalidOrderError, making error handling code more expressive and precise.

🏏

Cricket analogy: A generic "not out" call doesn't tell you if it was LBW, caught behind, or a no-ball; a custom exception like InsufficientFundsError is like the umpire naming the exact dismissal, e.g. "stumped by MS Dhoni," so everyone knows precisely what happened.

Defining a custom exception is straightforward: create a class that inherits from Exception (or one of its subclasses), optionally adding extra attributes or overriding __init__ to carry structured error details.

🏏

Cricket analogy: Defining a custom exception is like Cricket Australia creating a new "DRS Overturned" rule card that inherits from the general "Umpire's Decision" rulebook but adds its own extra field for which camera angle triggered it.

2. Syntax

python

class InsufficientFundsError(Exception):
    """Raised when a withdrawal exceeds the available balance."""
    def __init__(self, balance, amount):
        self.balance = balance
        self.amount = amount
        super().__init__(f"Cannot withdraw {amount}; balance is {balance}")

raise InsufficientFundsError(100, 250)

3. Explanation

Custom exceptions should subclass Exception, not BaseException. Subclassing BaseException directly would place the custom error outside the normal Exception hierarchy, meaning common handlers written as except Exception: would fail to catch it, and it could unintentionally behave like a control-flow signal similar to SystemExit or KeyboardInterrupt.

🏏

Cricket analogy: Subclassing BaseException instead of Exception is like a bowler being classified outside the normal "dismissal" category, so a standard "except run out" appeal handler wouldn't catch it — it would behave more like the match itself being abandoned, akin to rain stopping play.

Do not subclass BaseException for custom application errors. Always subclass Exception (directly or through another Exception subclass) so your custom error integrates correctly with normal exception handling and is caught by except Exception:.

It is common to build a small hierarchy of custom exceptions with a shared base, e.g. class AppError(Exception): pass, then class InsufficientFundsError(AppError): pass, so callers can catch either the specific error or the whole family via the base class.

🏏

Cricket analogy: Building AppError as a base with InsufficientFundsError beneath it is like the ICC having a general "Code of Conduct Violation" category under which "Ball Tampering" sits, so umpires can penalize the specific act or cite the whole category.

When raising a custom exception in response to catching another one, use raise NewError(...) from original_exception to preserve the original traceback as the cause, rather than raising the new exception as if it appeared out of nowhere. This is called exception chaining, and it appears as 'The above exception was the direct cause of the following exception' in tracebacks.

🏏

Cricket analogy: Using "raise NewError from original_exception" is like a match report noting the run-out happened "as a direct result of" a misfield, preserving the causal chain instead of describing the dismissal in isolation.

4. Example

python

class AppError(Exception):
    """Base class for all application-specific errors."""
    pass

class InsufficientFundsError(AppError):
    def __init__(self, balance, amount):
        self.balance = balance
        self.amount = amount
        super().__init__(f"Cannot withdraw {amount}; balance is {balance}")

def withdraw(balance, amount):
    if amount > balance:
        raise InsufficientFundsError(balance, amount)
    return balance - amount

try:
    withdraw(100, 250)
except InsufficientFundsError as e:
    print(f"Specific catch: {e}")
    print("balance attr:", e.balance, "amount attr:", e.amount)

try:
    withdraw(50, 500)
except AppError as e:
    print(f"Caught via base class AppError: {type(e).__name__}: {e}")

try:
    try:
        withdraw(10, 999)
    except InsufficientFundsError as original:
        raise RuntimeError("Transaction failed") from original
except RuntimeError as e:
    print(f"Chained: {e}, caused by {type(e.__cause__).__name__}")

5. Output

text

Specific catch: Cannot withdraw 250; balance is 100
balance attr: 100 amount attr: 250
Caught via base class AppError: InsufficientFundsError: Cannot withdraw 500; balance is 50
Chained: Transaction failed, caused by InsufficientFundsError

6. Key Takeaways

Define custom exceptions by subclassing Exception, never BaseException.
Custom exceptions can carry extra attributes via a custom __init__.
A shared base custom exception class lets callers catch a whole family of related errors.
Use raise NewError(...) from original to chain exceptions and preserve context.
Catching the base custom exception class also catches its subclasses, just like built-in exceptions.
Custom exceptions make error handling code self-documenting and domain-specific.