Use Python 3.11 exception notes (PEP 678) to provide hints on errors

[vstinner]

Python 3.11 adds BaseException.add_note() method to add "notes" to exceptions (PEP 678). One of the Motivations is providing hints to novices:

programming environments for novices can provide more detailed descriptions of various errors, and tips for resolving them

I propose modifying the few existing errors which already provide hints by converting the sentence to a note: restrict the error message to the actual error, and move hints to notes.

Example of an existing error with a hint:

$ python3 -q
>>> import sys
>>> print >>sys.stderr, "hello"
...
TypeError: unsupported operand type(s) for >>: 'builtin_function_or_method' and '_io.TextIOWrapper'. Did you mean "print(<message>, file=<output_stream>)"?

Currently, the actual error ("unsupported operand") and the hint ("Did you mean...") are displayed on the same line. IMO displaying the hint on a separated line would make it easier to spot (it would be less likely to miss it).

Example raising a note manually to see how it's displayed:

try:
    raise TypeError("unsupported operand")
except Exception as exc:
    exc.add_note("Did you mean...")
    raise

Current Python 3.12 output:

Traceback (most recent call last):
  File "bug.py", line 2, in <module>
    raise TypeError("unsupported operand")
TypeError: unsupported operand
Did you mean...

---

I proposed PR #96878 to add _PyErr_AddNote() function to the internal C API.

---

I found these hints:

• "Use sys.set_int_max_str_digits() to increase the limit": see PR gh-95778: Use a note for the max digits error message #96878
• print >> 123: unsupported operand ...: Did you mean "print(<message>, "file=<output_stream>)"?
• 1 is 2: "is" with a literal. Did you mean "=="?
• 1 is not 2: "is" with a literal. Did you mean "!="?
• "Suggestions" added by PyErr_Display() with _Py_Offer_Suggestions() (issue Offer suggestions on AttributeError and NameError #82711) is not a good fit: this code doesn't modify the exception on purpose
• print "hello": Missing parentheses in call to 'print'. Did you mean print(...)? (similar error on exec code)

[iritkatriel]

This achieves the same display:

>>> raise TypeError("unsupported operand\nDid you mean...")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: unsupported operand
Did you mean...

If there is a use case for being able to distinguish the error from the suggestion, then putting the suggestion in a note can help do that.

[vstinner]

Is is something common to include a newline character in error messages? My worry is that maybe it's not displayed properly in a terminal, in logs, or in a graphical dialog (like a popup message). Well, now we have this new feature and I would like to use it :-) You know, eating our own dog food :-)

The disadvantage of notes is that it's something new (Python 3.11 is not released yet ;-)), so maybe existing tools don't show notes yet (just ignore them), and notes might be lost when an exception is converted to a new exception (of a different type and/or with a different error message). Example:

try:
    raise TypeError("original message")
except Exception as exc:
    raise ValueError(f"new message ({exc})") from None

Python 3.12 output:

Traceback (most recent call last):
  File "bug.py", line 4, in <module>
    raise ValueError(f"new message ({exc})") from None
ValueError: new message (original message)

[vstinner]

@iritkatriel: Well, it seems like I failed to convince you to use notes for "suggestions". It seems like I misunderstood the part about "suggestions" (called "tips" in PEP 678). Since you authored PEP 678, I will follow your guidance and I close the issue. So it seems like right now, there is no need for a C API _PyErr_AddNote(): the add_note() method should be enough for now.