Clarify the meaning dataclasses.field(..., hash=False)

[picnixz]

See https://discuss.python.org/t/unclear-docs-for-dataclasses-field/80716. Currently the docs are:

hash: This can be a bool or None. If true, this field is included in the generated __hash__() method. If None (the default), use the value of compare: this would normally be the expected behavior. A field should be considered in the hash if it’s used for comparisons. Setting this value to anything other than None is discouraged.

We can change it to

 hash: This can be a bool or None. If true, this field is included in the generated :meth:`~object.__hash__` method.
+If false, this field is excluded from the generated :meth:`~object.__hash__` method.
 If :const:`None` (the default), use the value of compare: this would normally be the expected behavior.

Linked PRs

• gh-130130: Clarify hash=False docs in dataclasses.field #130324
• [3.12] gh-130130: Clarify hash=False docs in dataclasses.field (GH-130324) #130336
• [3.13] gh-130130: Clarify hash=False docs in dataclasses.field (GH-130324) #130337

[ericvsmith]

I also think it should be changed from:

If None (the default), use the value of compare: this would normally be the expected behavior. A field should be considered in the hash if it’s used for comparisons.

to

If None (the default), use the value of compare: this would normally be the expected behavior, since a field should be included in the hash if it’s used for comparisons.

[Lonwwolf14]

Hi @picnixz,

I’ve reviewed issue #130130 regarding the unclear documentation for the hash parameter in dataclasses.field(). From what I understand, the current documentation states that hash can be a bool or None, and if set to True, the field is included in the generated __hash__() method. If set to None (default), it follows the compare value, which is the expected behavior for consistency between comparisons and hashing. However, the documentation lacks clarity on what happens when hash=False, which can confuse users.

I’m planning to update the dataclasses.rst file in the documentation to incorporate this clarification. Please let me know if my understanding is correct or if there are any other aspects I should consider before proceeding.

[ericvsmith]

Merged. Thanks!