[localzet]

Summary

When hashing a tuple fails with TypeError, add an exception note identifying the index of the tuple item whose hash operation failed. Nested tuples accumulate one note per level. Preserve the original exception, message, existing notes, and traceback.

For example, a direct call to hash(("alice", [])) reports the existing unhashable type: 'list' error with the added note when hashing tuple item 1.

This is an implementation of gh-161433, based on the proposal by @WakaTaira.

Rationale and compatibility

• Only the error path in tuple_hash() is changed. Successful hashing and hash values are unaffected.
• Only TypeError gets an additional note; other exceptions are propagated unchanged.
• Exception-note propagation from dictionary keys and set elements requires the separate fix in Exception notes discarded from TypeError within __hash__() #149313 (PR gh-149313: Preserve exception notes/cause in dict/set unhashable type… #149505). This PR deliberately does not change dictionary/set exception handling.

Tests

A single focused test method covers five cases: a direct unhashable item, nested tuples, a custom TypeError, existing notes, and a non-TypeError exception.

A CPython --with-pydebug build completed successfully in the fork and test_tuple, test_dict, test_set, and test_traceback all passed:
https://github.com/localzet/cpython/actions/runs/42240703650

The fork's lint checks passed on the subsequent change adding the NEWS fragment:
https://github.com/localzet/cpython/actions/runs/42241501515

This PR is ready for review and merging. The review feedback about test organization has been addressed. The original proposal author @WakaTaira is acknowledged in Misc/ACKS.

AI assistance

The initial patch, tests, and PR description were prepared with ChatGPT assistance. The implementation is available for human review and maintenance.

[python-cla-bot]

All commit authors signed the Contributor License Agreement.

[vstinner]

@localzet: Can you please sign the CLA? See previous comment.

[vstinner]

dict and set catchs TypeError on hashing to write a hint on the error message: dict_unhashable_type() and set_unhashable_type(). The current TypeError exception is replaced with a new TypeError: notes are discarded. Would it be interesting to copy notes in this case?

Example:

key = ("alice", [])
# hash(key)
d = dict()
d[key] = 1

Output:

Traceback (most recent call last):
  File "/home/vstinner/python/main/x.py", line 4, in <module>
    d[key] = 1
    ~^^^^^
TypeError: cannot use 'tuple' as a dict key (unhashable type: 'list')

If I uncomment the hash() call, I see the new note when hashing tuple item 1:

Traceback (most recent call last):
  File "/home/vstinner/python/main/x.py", line 2, in <module>
    hash(key)
    ~~~~^^^^^
TypeError: unhashable type: 'list'
when hashing tuple item 1

[localzet]

Thanks for reviewing this, Victor! I agree that keeping the tuple-item note visible when the tuple is used as a dict key or set element is important.

The exception replacement is already tracked in gh-149313, with an existing implementation in PR #149505 (which chains the original exception). I intentionally kept this PR limited to tuple_hash() to avoid duplicating that work.

There is a useful distinction between the options: copying __notes__ to the replacement TypeError preserves the concise single-error presentation, while chaining the old exception also retains its traceback and cause but can duplicate the inner error in the common case (as noted in gh-149313).

Update: I implemented a small note-copying proof of concept in my fork: localzet#2. It preserves the concise outer dict/set message and includes regression tests for tuple-item notes and custom __hash__() notes. A debug build and focused test_tuple, test_dict, test_set, and test_traceback suite all passed: https://github.com/localzet/cpython/actions/runs/42277233728.

I have not folded those changes into this upstream PR yet to avoid competing with #149505 without coordination. Would you prefer a focused note-copying change as part of this PR, or to resolve dict/set exception preservation separately in gh-149313?

[vstinner]

LGTM.

The exception replacement is already tracked in #149313, with an existing implementation in PR #149505 (which chains the original exception). I intentionally kept this PR limited to tuple_hash() to avoid duplicating that work.

Oh ok, if it's already tracked somewhere else, I'm fine with not addressing the issue in this PR.

[WakaTaira]

@localzet Thanks for crediting the proposal in the description. Would you mind adding me to Misc/ACKS in this PR?

[localzet]

Thank you for the original gh-161433 proposal and for the helpful follow-up, @WakaTaira! I've added WakaTaira to Misc/ACKS in commit 0910da1 (alphabetically in the W section). If you'd prefer a different name in the acknowledgements, please let me know and I'll update it.