This guide explains exception notes with add_note() through a focused Python example. You will learn the behavior to expect, why it matters in a real program, and how to recognize the common mistakes before applying it in your own project.
What You Will Learn
BaseException.add_note(text) attaches additional human-readable diagnostic information to an exception without changing its type or message. Notes appear in formatted tracebacks.
When and Why to Use It
The following example focuses on a practical use of Exception Notes with add_note().
Step-by-Step Example
try:
int("missing")
except ValueError as error:
error.add_note("While reading the quantity column")
print(type(error).__name__)
print(error.__notes__)Understanding the Example
The exception remains a ValueError, but its notes list includes a contextual explanation that can be displayed by traceback formatting.
Expected Output
ValueError
['While reading the quantity column']Important Behavior and Edge Cases
Do not put passwords, access tokens or private customer data into exception notes that may be logged.
Try It Yourself
Attach a filename context note to an exception and inspect the __notes__ attribute.
Common Beginner Mistakes
- Do not put passwords, access tokens or private customer data into exception notes that may be logged.
- Handling the symptom rather than identifying the failing operation, or letting a broad exception handler hide defects.
- Skipping the practice step and assuming the example covers every input. Test at least one normal case and one edge case relevant to this topic.
Key Takeaways
- BaseException.add_note(text) attaches additional human-readable diagnostic information to an exception without changing its type or message.
- The exception remains a ValueError, but its notes list includes a contextual explanation that can be displayed by traceback formatting.
- Apply the technique deliberately, checking its documented input requirements and failure behavior before integrating it into a larger project.