Custom exceptions are a great way to enhance your projects and make it easy for others to work with your code! In this article, I delve into how I make and organize custom exceptions for my projects.

Why Make Custom Exceptions?

Python has many built-in exceptions, such as ValueError, TypeError, IndexError, and about 64 others, but they are all very general. Many times, it can be much better to make tailored exceptions for specific scenarios in your projects. For example, let's say you're building a social media bot that posts tweets on Twitter/X for you. There's no built-in exception that can accurately describe an error such as not being able to click on the “Post Tweet” button or an error involving the Twitter website being down.

Creating a Basic Custom Exception

To make a basic custom exception, all we really want to do is make a different name for the “default” exception that accurately describes a potential error in a project.

To do this, all we need to do is make a class with a descriptive name, inherit from the Exception class and either add a pass statement or a docstring explaining the exception. By adding no code in our custom exception, we can let the built-in Exception class handle all of the functionality, which means we can raise and catch our custom exception like any other built-in one!

class CustomError(Exception):
    """ Some documentation about what this custom exception is for. """

Raising & Catching Custom Exceptions

Because we’re inheriting from the Exception class, we can raise and catch our custom exception like any standard one. Just ensure it’s imported into the file you’re using!

try:
    raise CustomError('Message goes here')
except CustomError as e:
    print(f'Error: {e}')

Output:

Error: Message goes here

Add a Default Message to Your Exceptions

When raising built-in exceptions in Python, you can add a message to your exception, but who really remembers to add a unique message every time?

When making custom exceptions, you can add all sorts of custom variables, including a default exception message! In the example below, if the user of the custom exception doesn’t add a unique message, the default message is used instead.

class CustomError(Exception):
    default_message = 'A custom exception for ___ class'
    
    def __init__(self, message = None):
        super().__init__(message or default_message)

Exception Class Hierarchy

In Python, exceptions are structured using class hierarchies. When creating custom exceptions, it's crucial to inherit from the appropriate exception class to maintain clarity and correctness.

Below is a list of all the built-in Python exceptions and their hierarchies, from https://docs.python.org/3/library/exceptions.html.

BaseException
├── BaseExceptionGroup
├── GeneratorExit
├── KeyboardInterrupt
├── SystemExit
└── Exception
├── ArithmeticError
│ ├── FloatingPointError
│ ├── OverflowError
│ └── ZeroDivisionError
├── AssertionError
├── AttributeError
├── BufferError
├── EOFError
├── ExceptionGroup [BaseExceptionGroup]
├── ImportError
│ └── ModuleNotFoundError
├── LookupError
│ ├── IndexError
│ └── KeyError
├── MemoryError
├── NameError
│ └── UnboundLocalError
├── OSError
│ ├── BlockingIOError
│ ├── ChildProcessError
│ ├── ConnectionError
│ │ ├── BrokenPipeError
│ │ ├── ConnectionAbortedError
│ │ ├── ConnectionRefusedError
│ │ └── ConnectionResetError
│ ├── FileExistsError
│ ├── FileNotFoundError
│ ├── InterruptedError
│ ├── IsADirectoryError
│ ├── NotADirectoryError
│ ├── PermissionError
│ ├── ProcessLookupError
│ └── TimeoutError
├── ReferenceError
├── RuntimeError
│ ├── NotImplementedError
│ └── RecursionError
├── StopAsyncIteration
├── StopIteration
├── SyntaxError
│ └── IndentationError
│ └── TabError
├── SystemError
├── TypeError
├── ValueError
│ └── UnicodeError
│ ├── UnicodeDecodeError
│ ├── UnicodeEncodeError
│ └── UnicodeTranslateError
└── Warning
├── BytesWarning
├── DeprecationWarning
├── EncodingWarning
├── FutureWarning
├── ImportWarning
├── PendingDeprecationWarning
├── ResourceWarning
├── RuntimeWarning
├── SyntaxWarning
├── UnicodeWarning
└── UserWarning

As you can see from above, all exceptions derive from the BaseException. However, I wouldn't recommend having your custom exceptions directly inherit from the BaseException since KeyboardInterrupt and SystemExit are subclasses of BaseException.

Suppose you inherit from BaseException and use a try-except blocks to catch your custom exception. In that case, Python might inadvertently handle your custom exception when you are actually trying to stop your code using ctrl-c (which raises KeyboardInterrupt) or triggering a SystemExit. This is why it’s usually best to inherit from the Exception class, which is a subclass of BaseException.

For bigger projects with many exceptions, making your own parent exception class can sometimes be a good idea.

For example, let’s say you’re making some sort of bot; you may have 25 different types of exceptions related to clicking on different parts of a website. So logically, it would make sense to first have a WebsiteClickException class that inherits from Exception and then have all of your clicking exceptions inert from WebsiteClickException. The benefit of this is that you, or the people using your code, can choose to either handle specific clicking exceptions in particular ways or have a catch-all handler for every type of clicking exception.

class ClickException(Exception):
    """Base exception for all clicking related errors."""
    default_message = 'A click-related error occurred.'

    def __init__(self, message = None):
        super().__init__(message or self.default_message)

class ElementNotFoundException(ClickException):
    """Raised when the element to be clicked is not found."""

class ElementNotClickableException(ClickException):
    """Raised when the element is present but not clickable."""

class PageNotLoadedException(ClickException):
    """Raised when the page hasn't loaded properly."""


# Example usage:
try:
    # Simulated logic: Let's assume we couldn't find an element
    raise ElementNotFoundException()

except ElementNotClickableException as e:
    # Handle ElementNotClickableException differently
    print(f"ElementNotClickableException Error: {e}")

except ClickException as e:
    # Catch all other click exceptions
    print(f"Error: {e}")

Output:

Error: A click-related error occurred.

See how easy it is to catch all “clicking” exceptions or just a specific one!?

Organizing Multiple Custom Exceptions

If you’re making one or two custom exceptions for a Python class, it makes sense to put the exception classes in the same file as the Python class that they are made for. However, once you have many custom exceptions, I recommend putting them in a file called exceptions.py to both stay organized and maintain code that is intuitive to import into other modules.

Best Practices & Conclusion

Thanks for reading my article about custom exceptions in Python!

I’ll leave you with a few tips to think about when making your own:

• Meaningful Naming: Always name your exceptions in a way that they convey their purpose clearly. Typically, names ending in Error or Exception are a good idea.
• Documentation: Always document your custom exceptions, explaining the scenarios where they might be raised.
• Avoid Overuse: Don't create custom exceptions for every possible error. Only create them when they offer more clarity or handle specific scenarios that built-in exceptions can't cover effectively.

To sum up, custom exceptions offer an enhanced way to represent errors in your Python programs. They not only make your code more readable but also allow for more granular error handling.