Show which tuple item is unhashable when a nested dict key or set element is rejected #161433

Feature or enhancement

{([1],): 1} looks contrived, but this comes up in real code as soon as a tuple
key is built from existing data:

row = {"user": "alice", "tags": ["a", "b"]}
groups = {}
groups.setdefault((row["user"], row["tags"]), [])

TypeError: cannot use 'tuple' as a dict key (unhashable type: 'list')

Tuples are normally valid keys, so the message appears to reject the tuple because
of a list that isn't visibly related to it. Nothing says that the list is inside
the tuple, or where. This was pointed out on gh-132825 and again in the PEP 814
thread, and it is harder to follow with deeper nesting or longer tuples.

I'd suggest adding a note in the error path of tuple_hash, following what the
json module already does for nested values:

>>> json.dumps({"a": [1, object()]})
TypeError: Object of type object is not JSON serializable
when serializing list item 1
when serializing dict item 'a'

>>> hash(("alice", ["a", "b"]))  # proposed
TypeError: unhashable type: 'list'
when hashing tuple item 1

The note would be added only after an item's hash has failed, so successful hashing
is unaffected. Nested tuples would produce one note per level.

Dependency on gh-149313: the dict and set paths currently replace the exception
and discard its notes, so the note would only become visible for dict keys and set
elements once that issue is fixed. Until then, only direct hash() calls would
show it.

Reproduced on 3.14.6 and 3.15.0b2.

I noticed this behavior and found it confusing myself, and the proposal is my own. I used Claude to help write this up in English and to re-check the behavior.

Has this already been discussed elsewhere?

This is a minor feature, which does not need previous discussion elsewhere

Links to previous discussion of this feature:

• "unhashable type" is a beginner-unfriendly error message #132825 (comment on nested keys): "unhashable type" is a beginner-unfriendly error message #132825 (comment)
• PEP 814 thread: https://discuss.python.org/t/pep-814-add-frozendict-built-in-type/104854/16
• Exception notes discarded from TypeError within __hash__() #149313

Linked PRs

• gh-161433: Identify the failing item when hashing tuples #161496