Truth tables in documentation

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.

I blogged on the issue and created a short program to generate the table.

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.

2 Likes

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. :blush:

I think “Decision table” is a better term than truth table:

Decision tables are commonly recognised as a simple, intuitive, clear

way to present data of the form “if this… and that… then this”. I

find it difficult to believe that people found such a table confusing.

To be clear, I don’t doubt your statement that they said it was

confusing. I just find it implausible that they actually were confused.

If they can read conditional tests of the form:

if A and B and C:

    do_this()

elif A and B and not C:

    do_that()

elif A and not B and C:

    ...

then they ought to be able to read a decision table.

In any case, if people genuinely find the table confusing, they can just

ignore it and read the text as they already are doing. Adding a table

will help those who find them useful and not harm those who don’t.

+1 on adding a decision table.

“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).

I think you’d want to include the “existing __hash__” column. And I think the last column should be named better, maybe “@dataclass action”.

You should probably just open a bpo issue and PR and we can discuss it there.