Improve the default excepthook formatting for multi-line and exception notes
Open
Nobody has claimed this yet.
interpreter-core
type-feature
- Dominant language
- Python
- Stars
- 77.2k
- Forks
- 35.9k
- PR merge metrics
- PR metrics pending
Description
Proposal:
Currently, it is possible to add notes to exceptions, see BaseException.add_note, but this feature is underutilized.
One of the reasons for that, I believe, is the poor formatting in the default excepthook:
Current Output
(single note)
$ ./python
Python 3.14.0a2+ experimental free-threading build (heads/gh-127429-dirty:cc4f57a74d0, Dec 1 2024, 07:06:51) [GCC 14.2.1 20240910] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> try:
... raise Exception('error')
... except Exception as e:
... e.add_note('some context')
... raise
...
Traceback (most recent call last):
File "<python-input-0>", line 2, in <module>
raise Exception('error')
Exception: error
some context
(with multiple notes)
$ ./python
Python 3.14.0a2+ experimental free-threading build (heads/gh-127429-dirty:cc4f57a74d0, Dec 1 2024, 07:06:51) [GCC 14.2.1 20240910] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> try:
... raise Exception('error')
... except Exception as e:
... e.add_note('some context')
... e.add_note('some context 2')
... e.add_note('some context 3')
... raise
...
Traceback (most recent call last):
File "<python-input-0>", line 2, in <module>
raise Exception('error')
Exception: error
some context
some context 2
some context 3
I think if we formatted it better, making the output easier to understand, we could start seeing better adoption of this feature.
(with multiple notes)
$ ./python
Python 3.14.0a2+ experimental free-threading build (heads/gh-127429-dirty:cc4f57a74d0, Dec 1 2024, 07:06:51) [GCC 14.2.1 20240910] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> try:
... raise Exception('error')
... except Exception as e:
... e.add_note('some context')
... e.add_note('some context 2')
... e.add_note('some context 3')
... raise
...
Traceback (most recent call last):
File "<python-input-0>", line 2, in <module>
raise Exception('error')
Exception: error
├── Note: some context
├── Note: some context 2
└── Note: some context 3
In addition to this, multiline exception messages could also be improved.
Current Output
(multi-line string, with no notes)
$./python
Python 3.14.0a2+ experimental free-threading build (heads/gh-127429-dirty:cc4f57a74d0, Dec 1 2024, 07:06:51) [GCC 14.2.1 20240910] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> raise Exception('some error\n\nsome context\nsome context (cont.)\n\nsome extra context')
Traceback (most recent call last):
File "<python-input-0>", line 1, in <module>
raise Exception('some error\n\nsome context\nsome context (cont.)\n\nsome extra context')
Exception: some error
some context
some context (cont.)
some extra context
(multi-line string, with multi-line notes)
$ ./python
Python 3.14.0a2+ experimental free-threading build (heads/gh-127429-dirty:cc4f57a74d0, Dec 1 2024, 07:06:51) [GCC 14.2.1 20240910] on linux
>>> try:
... raise Exception('some error\n\nsome error text\nsome error text (cont.)\n\nsome more error text')
... except Exception as e:
... e.add_note('some context\nsome context (cont.)')
... e.add_note('some context 2\n\nsome extra context 2')
... e.add_note('some context 3\nsome context 3 (cont.)\n\nsome extra context 3')
... raise
...
Traceback (most recent call last):
File "<python-input-0>", line 2, in <module>
raise Exception('some error\n\nsome error text\nsome error text (cont.)\n\nsome more error text')
Exception: some error
some error text
some error text (cont.)
some more error text
some context
some context (cont.)
some context 2
some extra context 2
some context 3
some context 3 (cont.)
some extra context 3
The first example IMO isn't optimal, but it's okay enough, but the second example is very confusing. We could format it something like:
$ ./python
Python 3.14.0a2+ experimental free-threading build (heads/gh-127429-dirty:cc4f57a74d0, Dec 1 2024, 07:06:51) [GCC 14.2.1 20240910] on linux
>>> try:
... raise Exception('some error\n\nsome error text\nsome error text (cont.)\n\nsome more error text')
... except Exception as e:
... e.add_note('some context\nsome context (cont.)')
... e.add_note('some context 2\n\nsome extra context 2')
... e.add_note('some context 3\nsome context 3 (cont.)\n\nsome extra context 3')
... raise
...
Traceback (most recent call last):
File "<python-input-0>", line 2, in <module>
raise Exception('some error\n\nsome error text\nsome error text (cont.)\n\nsome more error text')
Exception:
│ │ some error
│ │
│ │ some error text
│ │ some error text (cont.)
│ │
│ └ some more error text
│
├── Note:
│ │ some context
│ └ some context (cont.)
│
├── Note:
│ │ some context 2
│ │
│ └ some extra context 2
│
└── Note:
│ some context 3
│ some context 3 (cont.)
│
└ some extra context 3
Has this already been discussed elsewhere?
No response given
Links to previous discussion of this feature:
No response
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with CPython’s default excepthook and exception-formatting entry points; the issue does not name a file or test. Compare current output with the proposed single-line and multiline note examples, and treat matching the intended tree-like formatting without losing message content as done.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- backend
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100