This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: Language Reference: Set items
Type: Stage:
Components: Documentation Versions:
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: BTaskaya, Pixmew, docs@python, rhettinger, terry.reedy
Priority: normal Keywords:

Created on 2020-11-13 15:38 by BTaskaya, last changed 2022-04-11 14:59 by admin.

Messages (4)
msg380901 - (view) Author: Batuhan Taskaya (BTaskaya) * (Python committer) Date: 2020-11-13 15:38
The data types section of the language reference (https://docs.python.org/3.10/reference/datamodel.html#the-standard-type-hierarchy) has this description directly under the Set type (which has 2 childs, set and frozenset). 

> These represent unordered, finite sets of unique, immutable objects.

I feel like this wording is a bit confusing, considering the items doesn't have to be immutable at all. Can we replace this with hashable?
msg380905 - (view) Author: Yash Shete (Pixmew) * Date: 2020-11-13 15:51
Should it be "These represents hashable objects"
msg380931 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2020-11-13 19:44
I recommend leaving the text as is, and possibly creating a new FAQ entry discussing the relationship between immutability and hashability (something that I consider to be an intermediate or advanced topic).

Other thought:

* The set discussion should remain parallel that for mappings (a few paragraphs) after.  That text also discusses immutability

* We've never had a user incident regarding this text, so there is no actual evidence that this current wording is confusing anyone.

* It is common for users to equate hashability with immutability, so I think the current wording is reasonable.  My experience with users indicate that "hashable" is more cryptic than "immutable" because the former implies a knowledge of how hash tables work.

* It's easy for us thinking we're helping by making precise distinctions but have the actual effect of making the docs more opaque.  That is why first-aid books say "bruise" instead of "subdermal hematoma" :-)

* The word "immutable" is a reasonable first approximation that doesn't require knowledge of hash table mechanics.  For the most part, it is how everyday users think about dict keys and set elements. 

* That approximation is useful because a fuller discussion would say that if __hash__ is defined, it should do so on fields that don't mutate.
msg380959 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2020-11-14 07:13
Raymond's last point is that set objects should be immutably hashable.  I would say 'must be' in the sense that mutably hashable objects break sets in various ways, starting with uniqueness.  If we were to make a change, I think the replacement should be 'immutably hashable'

'unique objects' would also need qualification.  As is, one might reasonably expect. for instance, {1+0j, 1.0, 1} to have 3 elements rather than 1.  It is really 'objects unique up to equality', where equality may or may not be by identity.

However, I am inclined to agree with Raymond that we should stick to the current easily read sentence.
History
Date User Action Args
2022-04-11 14:59:38adminsetgithub: 86514
2020-11-14 07:13:53terry.reedysetnosy: + terry.reedy
messages: + msg380959
2020-11-13 19:44:22rhettingersetmessages: + msg380931
2020-11-13 15:51:20Pixmewsetnosy: + Pixmew
messages: + msg380905
2020-11-13 15:38:36BTaskayasetnosy: + rhettinger, docs@python

components: + Documentation
assignee: docs@python
2020-11-13 15:38:16BTaskayacreate