Repository navigation
Description
Documentation
Documentation: https://docs.python.org/3/reference/datamodel.html#object.__hash__
The object.__hash__ documentation uses the phrase "hashable collections", and in one place links it to the glossary term "hashable". This is inaccurate, and it is inconsistent with the first paragraph of the same entry.
Current text, second paragraph:
If a class does not define an
__eq__()method it should not define a__hash__()operation either; if it defines__eq__()but not__hash__(), its instances will not be usable as items in hashable collections. If a class defines mutable objects and implements an__eq__()method, it should not implement__hash__(), since the implementation of [hashable] collections requires that a key's hash value is immutable (if the object's hash value changes, it will be in the wrong hash bucket).
([hashable] is a link to the glossary term.)
Problem
The glossary defines "hashable" as a property of an object: it has a hash value that never changes during its lifetime and can be compared to other objects. The glossary also says that mutable containers such as lists and dictionaries are not hashable.
"Hashable collections" therefore reads as "collections that can be hashed". That is not what is meant, and set and dict are not hashable in that sense. What is meant is collections that use hashing internally and need their keys or elements to be hashable. Linking the phrase to the glossary entry makes the wrong reading more likely.
The first paragraph of the same entry says "hashed collections including set, frozenset, dict, and frozendict", so the terminology is also inconsistent within one entry.
Suggested change
Use "hash-based collections" consistently and drop the glossary link from that phrase:
...its instances will not be usable as items in hash-based collections. If a class defines mutable objects and implements an
__eq__()method, it should not implement__hash__(), since the implementation of hash-based collections requires that a key's hash value is immutable...
The first paragraph could then say "hash-based collections" instead of "hashed collections", so one term is used throughout.
Linked PRs
Metadata
Metadata
Assignees
Labels
Projects
- StatusShow more project fieldsTodo
Activity
gvanrossum commentedon Oct 4, 2026
Nevertheless I feel that that paragraph benefits from a link to hashable in the glossary. Please find a way to preserve that link.
Also, is "hashable collection" used elsewhere?
gvanrossum commentedon Oct 4, 2026
Why was a comment here marked as spam?
pochmann commentedon Oct 4, 2026
If a stamp collection is a collection of stamps, a hashable collection could be a collection of hashables.
And "collection" could refer to the data, e.g., the set elements, while the set is a "container" for the collection. Like the
collectionsmodule being titled "collections— Container datatypes" and introduced with "This module implements specialized container datatypes ...". And then the collection, e.g., the set members, is/are hashable.But neither is how I'd read it unless I already know it's meant that way.
You PR replaces "hashable collections" with "hashed collection". I think that has the same problem, no? Your "hash-based collections" sounds good. Or maybe "hashing collections".
sirosen commentedon Nov 5, 2026
Would "collections of hashables" be satisfactory?
It removes the ambiguity and can be linked to the glossary.
pythongh-158798: Replace misleading "hashable collections" in object.…