Custom Exceptions in Python: Build Meaningful Errors That Actually Help

# ── exception_hierarchy_basics.py ──────────────────────────────────────────
# Demonstrates: correct base classes and why it matters at catch-time

# ❌ Inheriting from BaseException — almost never do this for app errors
class BadBaseException(BaseException):
    pass

# ✅ Inheriting from Exception — the right default for application errors
class AppError(Exception):
    """Base class for all errors raised by this application."""
    pass

# ✅ Inheriting from a built-in subclass when semantics match
class NegativeAmountError(ValueError):
    """Raised when a monetary amount is negative where only positive is valid."""
    pass


def process_payment(amount: float) -> str:
    if amount < 0:
        # We raise NegativeAmountError, but the except block below catches ValueError
        raise NegativeAmountError(f"Payment amount cannot be negative. Got: {amount}")
    return f"Payment of £{amount:.2f} processed successfully."


# --- Scenario 1: catching the specific type ---
try:
    process_payment(-50.0)
except NegativeAmountError as error:
    print(f"[Specific catch] {error}")

# --- Scenario 2: catching the PARENT type (ValueError) still works ---
# This is why subclassing ValueError is useful in library code:
# callers don't need to know about YOUR custom type to handle it sensibly.
try:
    process_payment(-50.0)
except ValueError as error:
    print(f"[Parent catch]   {error}")

# --- Scenario 3: proving BadBaseException escapes a normal except block ---
try:
    raise BadBaseException("I escape normal except clauses!")
except Exception:
    # BaseException subclasses are NOT caught here
    print("This line will NOT print.")
except BadBaseException as error:
    print(f"[BaseException catch] Had to catch it explicitly: {error}")

# ── context_rich_exceptions.py ─────────────────────────────────────────────
# Demonstrates: exceptions as data carriers, not just message strings

from datetime import datetime


class InsufficientFundsError(Exception):
    """
    Raised when a withdrawal or payment exceeds the available account balance.

    Attributes:
        account_id      -- the account that triggered the error
        amount_requested -- the amount the caller tried to move
        available_balance -- what was actually in the account
        timestamp        -- when this error occurred (useful for audit logs)
    """

    def __init__(
        self,
        account_id: str,
        amount_requested: float,
        available_balance: float,
    ) -> None:
        self.account_id = account_id
        self.amount_requested = amount_requested
        self.available_balance = available_balance
        self.shortfall = amount_requested - available_balance
        self.timestamp = datetime.utcnow()

        # Build the human-readable message ONCE and pass it to the parent.
        # This ensures str(exception) and repr(exception) both work correctly.
        message = (
            f"Account '{account_id}' has insufficient funds. "
            f"Requested: £{amount_requested:.2f}, "
            f"Available: £{available_balance:.2f}, "
            f"Shortfall: £{self.shortfall:.2f}"
        )
        super().__init__(message)   # ← critical: always call super().__init__


def withdraw(account_id: str, amount: float, balance: float) -> float:
    """Simulate a withdrawal. Returns new balance on success."""
    if amount > balance:
        raise InsufficientFundsError(
            account_id=account_id,
            amount_requested=amount,
            available_balance=balance,
        )
    return balance - amount


# --- Happy path ---
new_balance = withdraw(account_id="ACC-001", amount=200.0, balance=500.0)
print(f"Withdrawal successful. New balance: £{new_balance:.2f}")

# --- Error path: catching and inspecting structured attributes ---
try:
    withdraw(account_id="ACC-002", amount=1500.0, balance=300.0)
except InsufficientFundsError as error:
    # We can branch on the data, not on parsing a string
    print(f"\nCaught: {error}")                          # uses __str__ via super().__init__
    print(f"Account  : {error.account_id}")
    print(f"Requested: £{error.amount_requested:.2f}")
    print(f"Available: £{error.available_balance:.2f}")
    print(f"Shortfall: £{error.shortfall:.2f}")
    print(f"At       : {error.timestamp.strftime('%Y-%m-%d %H:%M:%S')} UTC")

    # Real-world: trigger a different UX flow depending on shortfall size
    if error.shortfall < 50:
        print("Suggestion: You're just short — consider a small top-up.")
    else:
        print("Suggestion: Please review your account balance before retrying.")

# ── domain_exception_hierarchy.py ──────────────────────────────────────────
# Demonstrates: a real-world exception hierarchy for an e-commerce module
# In a real project this lives in  src/ecommerce/exceptions.py

# ── LAYER 1: Application root ───────────────────────────────────────────────
class ECommerceError(Exception):
    """Root exception for the entire e-commerce module.
    Catch this in middleware/framework handlers to guarantee a
    structured error response for ANY problem from this domain.
    """
    pass


# ── LAYER 2: Domain groupings ────────────────────────────────────────────────
class PaymentError(ECommerceError):
    """All payment-related failures."""
    pass

class InventoryError(ECommerceError):
    """All stock/inventory-related failures."""
    pass

class AuthorisationError(ECommerceError):
    """All permission/authentication failures."""
    pass


# ── LAYER 3: Specific errors with rich context ───────────────────────────────
class CardDeclinedError(PaymentError):
    """Raised when a payment gateway declines a card."""

    def __init__(self, card_last_four: str, decline_code: str) -> None:
        self.card_last_four = card_last_four
        self.decline_code = decline_code
        super().__init__(
            f"Card ending {card_last_four} was declined (code: {decline_code})"
        )


class OutOfStockError(InventoryError):
    """Raised when a product cannot fulfil the requested quantity."""

    def __init__(self, product_sku: str, requested: int, available: int) -> None:
        self.product_sku = product_sku
        self.requested = requested
        self.available = available
        super().__init__(
            f"SKU '{product_sku}': requested {requested}, only {available} in stock."
        )


class InsufficientPermissionsError(AuthorisationError):
    """Raised when a user attempts an action they're not allowed to perform."""

    def __init__(self, user_id: str, required_role: str) -> None:
        self.user_id = user_id
        self.required_role = required_role
        super().__init__(
            f"User '{user_id}' lacks required role '{required_role}'."
        )


# ── Simulated service functions ───────────────────────────────────────────────
def charge_card(card_last_four: str, amount: float) -> None:
    """Simulate a payment gateway call."""
    # In real life: call Stripe/Braintree SDK here
    if card_last_four == "0000":   # simulate a declined card for demo
        raise CardDeclinedError(card_last_four=card_last_four, decline_code="insufficient_funds")

def reserve_stock(product_sku: str, quantity: int) -> None:
    """Simulate an inventory reservation."""
    stock_levels = {"WIDGET-42": 3, "GADGET-7": 100}
    available = stock_levels.get(product_sku, 0)
    if quantity > available:
        raise OutOfStockError(product_sku=product_sku, requested=quantity, available=available)

def admin_action(user_id: str) -> None:
    """Simulate an action that requires admin privileges."""
    non_admin_users = {"user-123", "user-456"}
    if user_id in non_admin_users:
        raise InsufficientPermissionsError(user_id=user_id, required_role="admin")


# ── Demonstrate catching at different levels of the hierarchy ─────────────────
test_cases = [
    lambda: charge_card("0000", 99.99),
    lambda: reserve_stock("WIDGET-42", 10),
    lambda: admin_action("user-123"),
]

for test in test_cases:
    try:
        test()
    except CardDeclinedError as error:
        # Specific handler: offer the user a chance to retry with another card
        print(f"[CardDeclined]   {error} — prompt user for alternative card")
    except InventoryError as error:
        # Catches OutOfStockError AND any future InventoryError subclasses
        print(f"[InventoryError] {error} — notify warehouse team")
    except ECommerceError as error:
        # Safety net: catches everything else from this module
        print(f"[ECommerceError] {error} — log and return 400 to client")

# ── exception_chaining.py ──────────────────────────────────────────────────
# Demonstrates: raise...from to preserve root cause during exception translation

import sqlite3


class DatabaseUnavailableError(Exception):
    """Raised when the application cannot reach or query the database."""

    def __init__(self, operation: str, original: Exception) -> None:
        self.operation = operation
        super().__init__(
            f"Database operation '{operation}' failed. See cause above for details."
        )


class UserRepository:
    """Thin data-access layer that translates low-level DB errors into domain errors."""

    def __init__(self, db_path: str) -> None:
        # Using an intentionally invalid path to simulate a connection failure
        self.db_path = db_path

    def find_user(self, user_id: int) -> dict:
        try:
            # sqlite3 will raise OperationalError if the DB doesn't exist/is locked
            connection = sqlite3.connect(self.db_path)
            cursor = connection.cursor()
            cursor.execute("SELECT id, name FROM users WHERE id = ?", (user_id,))
            row = cursor.fetchone()
            if row is None:
                return {}
            return {"id": row[0], "name": row[1]}

        except sqlite3.OperationalError as db_error:
            # Translate the low-level driver error into our domain exception.
            # The 'from db_error' chain preserves the original traceback.
            raise DatabaseUnavailableError(
                operation="find_user",
                original=db_error,
            ) from db_error   # ← this is the key line


# --- Example 1: raise...from shows BOTH tracebacks ---
repo = UserRepository(db_path="/nonexistent/path/app.db")

try:
    repo.find_user(user_id=42)
except DatabaseUnavailableError as error:
    print(f"Domain error caught: {error}")
    # In a real app you'd log the full traceback with logging.exception()
    # which automatically includes the chained cause
    print(f"Root cause type : {type(error.__cause__).__name__}")
    print(f"Root cause msg  : {error.__cause__}")

print()

# --- Example 2: raise...from None hides sensitive internals ---
class UserFetchError(Exception):
    """Sanitised error safe to return to an API client."""
    pass

try:
    try:
        # Simulate an internal error with sensitive details
        raise sqlite3.OperationalError("no such table: internal_user_pii")
    except sqlite3.OperationalError:
        # We don't want 'internal_user_pii' leaking to the client
        raise UserFetchError("Unable to retrieve user. Please try again.") from None
except UserFetchError as error:
    print(f"Safe client error : {error}")
    print(f"Hidden cause      : {error.__cause__}")   # None — original is suppressed