Creating Custom Exceptions

Why Not Just Use Built-in Exceptions?

Python offers a rich set of built-in exceptions like ValueError, TypeError, and KeyError. They are excellent for signaling low-level problems: a function received the wrong type of argument, or a dictionary key was not found.

However, they often fail to describe problems at a higher, more conceptual level—the level of your application's domain.

Imagine you are building an e-commerce application with a function to process payments. What happens if the user's credit card is declined?

• Is it a ValueError because the card number was invalid?
• Is it a RuntimeError because an external service failed?

Neither is very descriptive. Code that calls your payment function would have to catch a generic error and guess the real meaning. A much better approach is to raise a domain-specific exception.

class InsufficientFundsError(Exception):
    """Raised when a payment fails due to insufficient funds."""
    pass

class PaymentGatewayError(Exception):
    """Raised when the payment gateway service is unavailable."""
    pass

Now, the calling code can handle these specific scenarios explicitly:

try:
    process_payment(order, credit_card_details)
except InsufficientFundsError:



    # Handle insufficient funds (e.g., notify user)
except PaymentGatewayError:



    # Handle gateway failure (e.g., retry later)

This is the core idea: custom exceptions communicate what went wrong in the language of your application's business logic, not just in terms of Python's internal types and values.

This best practice is crucial for building clean APIs.

Defining Custom Exception Classes

At its simplest, a custom exception is just an empty class that inherits from the base Exception class.

By inheriting from Exception, your new class becomes part of Python's standard exception hierarchy, allowing it to be caught by a generic except Exception: block if needed, while still being catchable by its specific name.

Adding Context to Your Exceptions

While a name is often enough, the true power of custom exceptions is their ability to carry rich, contextual information about the error. The code that catches the exception can then use this data to log detailed diagnostics or make smarter decisions.

To do this, you implement a custom __init__ method for your exception class.

Let's break down the pattern shown in the video.

class InsufficientStockError(Exception):
    """Raised when an item's stock is not enough to fulfill an order."""
    
    def __init__(self, item_id: str, requested: int, available: int):
        self.item_id = item_id
        self.requested = requested
        self.available = available
        



        # Create a detailed message for logging and debugging
        message = (
            f"Cannot fulfill order for item '{item_id}'. "
            f"Requested: {requested}, Available: {available}"
        )
        



        # Call the parent class's __init__ with the message
        super().__init__(message)




# Example usage
def place_order(item_id: str, quantity: int):
    stock_level = get_stock_for_item(item_id)  # Pretend this function exists
    if quantity > stock_level:
        raise InsufficientStockError(
            item_id=item_id, 
            requested=quantity, 
            available=stock_level
        )



    # ... proceed with order

try:
    place_order(item_id="PROD-123", quantity=10)
except InsufficientStockError as e:
    print(f"Error: {e}")



    # The 'except' block can now access the context
    print(f"Item ID: {e.item_id}")
    print(f"We can only supply {e.available} units.")



    # We could now suggest ordering the available amount instead.

Key components of this pattern:

1. Inherit from Exception: This is mandatory.
2. Define __init__: It should accept arguments that provide context about the error.
3. Store Context: Assign the arguments to self attributes (e.g., self.item_id). This makes them accessible to the code that catches the exception.
4. Call super().__init__(message): This is a crucial step. It ensures the base Exception class is properly initialized with a descriptive error message. This message is what gets printed by default and is stored in the .args tuple of the exception instance.

Customizing the String Representation

By default, when you print() an exception object, it displays the message you passed to super().__init__(). You can override this behavior by implementing the __str__ dunder method for more control over the user-facing output.

While defining __str__ can be useful, for most cases, passing a well-formatted message to super().__init__ is sufficient and simpler. Use __str__ when you need the string representation to be fundamentally different from the message intended for logging.

Example: A Domain-Specific ConfigError

Let's tie this all together with a practical example. Imagine a function that loads a configuration from a JSON file. This process can fail in two ways: the file might not exist (FileNotFoundError), or it might contain invalid JSON (json.JSONDecodeError).

A consumer of this function shouldn't have to worry about these implementation details. They only care about one domain-specific problem: "The configuration could not be loaded."

We can create a ConfigError to abstract away the underlying causes.

This pattern of catching specific technical exceptions and re-raising them as a single, meaningful domain exception is fundamental to good API design. It decouples the interface of your function from its internal implementation. If you later decide to switch from JSON to YAML, the caller of load_config doesn't need to change; it still just needs to handle ConfigError.

Conclusion

In this lesson, you learned how to move beyond Python's built-in exceptions to create custom, domain-specific errors that make your code more readable, maintainable, and robust.

Key Takeaways:

• Use custom exceptions for domain-specific errors: Raise exceptions that describe problems in the context of your application's logic (e.g., InsufficientStockError), not just generic programming errors (ValueError).
• Define custom exceptions by inheriting from Exception: This integrates them into Python's standard error-handling mechanisms.
• Add a custom __init__ to capture context: Store relevant data (like IDs, values, or limits) as attributes on your exception object to aid in debugging and recovery.
• Always call super().__init__(message): This initializes the base class with a descriptive message, which is crucial for logging and debugging.
• Custom exceptions create clean API boundaries: They hide implementation details from the calling code, leading to more decoupled and maintainable software.

In our next lesson, we will shift our focus back to the built-in exceptions. Now that you know how to create your own, we will explore the best practices for raising the right built-in exceptions like ValueError, TypeError, and KeyError to signal specific pre-conditions and contract violations within your functions.