Best practices for custom exceptions in Python

Introduction

Custom exceptions help you handle specific errors clearly in your programs. They make your code easier to understand and fix.

When you want to show a clear error message for a special problem in your program.

When you need to catch and handle a specific error differently from others.

When you want to organize your error handling by creating meaningful error types.

When you want to add extra information to an error to help debugging.

When you want your program to be easier to maintain and extend by using clear error types.

Syntax

Python

class MyCustomError(Exception):
    """Optional docstring explaining this error."""
    pass

Custom exceptions usually inherit from Exception or one of its subclasses.

Use a clear and descriptive name ending with Error to show it is an exception.

Examples

A simple custom exception for validation errors.

Python

class ValidationError(Exception):
    pass

A custom exception that stores extra info about the database name.

Python

class DatabaseConnectionError(Exception):
    def __init__(self, message, db_name):
        super().__init__(message)
        self.db_name = db_name

Inheriting from ValueError to be more specific about the error type.

Python

class FileFormatError(ValueError):
    """Raised when a file has wrong format."""
    pass

Sample Program

This program defines a custom exception NegativeNumberError. It raises this error if the number is negative. The try-except block catches and prints the error message.

Python

class NegativeNumberError(Exception):
    """Raised when a negative number is not allowed."""
    pass

def check_positive(number):
    if number < 0:
        raise NegativeNumberError(f"Negative number not allowed: {number}")
    return True

try:
    check_positive(-5)
except NegativeNumberError as e:
    print(f"Caught an error: {e}")

Important Notes

Always give your custom exceptions clear and meaningful names.

Include helpful messages or extra data to make debugging easier.

Use inheritance to group related exceptions together.

Summary

Custom exceptions make error handling clearer and more specific.

Name exceptions clearly and inherit from Exception or related classes.

Add messages or extra info to help understand the error.