"hashable collections" in the `object.__hash__` documentation is misleading

[dluschan]

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

• gh-158798: Use "hashed collections" consistently in object.__hash__ docs #158799

[gvanrossum]

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?

[jadhavroshani713-sys]

I reviewed the change in Doc/reference/datamodel.rst. The terminology change from “hashable collections” to “hashed collections” is consistent with the first paragraph of object.hash, which already refers to “hashed collections”. The change also avoids incorrectly linking the phrase to the hashable glossary term.

[gvanrossum]

Why was a comment here marked as spam?

[pochmann]

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 collections module 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".