Skip to content

"hashable collections" in the object.__hash__ documentation is misleading #158798

Open

Description

@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

Activity

  1. gvanrossum commented on Oct 4, 2026

    @gvanrossum
    Member

    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?

  2. gvanrossum commented on Oct 4, 2026

    @gvanrossum
    Member

    Why was a comment here marked as spam?

  3. pochmann commented on Oct 4, 2026

    @pochmann
    Contributor

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

  4. sirosen commented on Nov 5, 2026

    @sirosen
    Contributor

    Would "collections of hashables" be satisfactory?
    It removes the ambiguity and can be linked to the glossary.

  5. added a commit that references this issue on Nov 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    docsDocumentation in the Doc dir

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions