I had to read the documentation on dataclass unsafe_hash and initially found it hard to decipher.
On creating a truth table showing how arguments control the generation of __hash__ it became much clearer to me. I would like to hear if others find the addition of a table similar to the folowing would AID the description:
unsafe_hash
eq
frozen
dataclass __hash__ state
False
False
False
ABSENT
False
False
True
ABSENT
False
True
False
SET_NONE(Unhashable)
False
True
True
PRESENT
True
False
False
PRESENT
True
False
True
PRESENT
True
True
False
PRESENT
True
True
True
PRESENT
Personally, I find the table form much better at succinctly describing logical expressions of two-to-four variables.
There’s a similar table in the dataclasses source code. It has a little more detail than your table: what happens if the class already has __hash__ defined.
I find it helpful, but when we were developing dataclasses other people found it confusing, so I didn’t add it to the docs. While the __hash__ table is the most complex, there are tables for all of the added dunders.
The docs could have a “no” table and maybe a “yes” table to decrease the complexity, but I find that the text descriptions need something more as the text can be strictly correct, but hard to discern.
Another aid can be to add the Boolean equation. For me, a text description of what the table is for, but without a textual explanation of the logic itself but with the logic equation might prove a more comprehensible way of explanation.
I should add that I have a digital design background which colours my judgement.
“Decision table”, thanks for that, I had forgotten that term and got into the habit of calling everything a truth table.
Don’t cares
I had omitted talk on the use of “don’t cares”, which the article mentions, and which would be ideal for using on the other two table inputs when unsafe_hash is True and so cut the number of table rows:
unsafe_hash
eq
frozen
dataclass__hash__ state
False
False
False
ABSENT
False
False
True
ABSENT
False
True
False
SET_NONE(Unhashable)
False
True
True
PRESENT
True
-
-
PRESENT
Or even down to the following:
default
unsafe_hash
eq
frozen
dataclass__hash__ state
False
False
-
ABSENT
False
True
False
SET_NONE(Unhashable)
False
True
True
PRESENT
True
-
-
PRESENT
(SInce I’m playing with this table markdown thing i added an indicator for the default case).