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
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
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
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 InsufficientFundsError6. 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 originalto 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.
Practice what you learned
1. Which class should a custom exception subclass?
2. What is the risk of subclassing BaseException directly for a custom exception?
3. What does `raise RuntimeError("...") from original_error` accomplish?
4. If InsufficientFundsError subclasses AppError, and AppError subclasses Exception, which except clause will catch an InsufficientFundsError?
5. Why might you give a custom exception extra attributes like `self.balance` and `self.amount`?
Was this page helpful?
You May Also Like
Exceptions in Python
What exceptions are, how Python's built-in exception hierarchy is structured, and how errors propagate through a program.
try-except in Python
How to use try-except blocks to catch and handle exceptions gracefully, including catching multiple exception types.
finally Block in Python
How the finally clause guarantees cleanup code runs no matter what happens in a try block, including with return and break.
else Clause in Exception Handling
How the try/except/else clause runs code only when no exception occurred, and how it differs from finally.
Related Reading
Related Study Notes in Programming
Browse all study notesApache Spark Study Notes
Programming · 30 topics
ProgrammingApache Flink Study Notes
Programming · 30 topics
ProgrammingHadoop Study Notes
Programming · 30 topics
ProgrammingSnowflake Study Notes
Programming · 30 topics
ProgrammingApache Airflow Study Notes
Programming · 30 topics
Programmingdbt (Data Build Tool) Study Notes
Programming · 30 topics