It's not clear right now which elements the note is referring to - you might want to clarify that this applies when there are multiple equal elements involved in an operation, which are kept is an implementation detail.

It's not clear right now which elements the note is referring to - you might want to clarify that this applies when there are multiple equal elements involved in an operation, which are kept is an implementation detail.

Not for equal elements but other then that also, you can see the orgnal issue for it.

I recommend against making any change. While satisfying to the OP, this is unlikely to benefit any reader. Instead, it is likely to cause unnecessary worry and confusion about an issue that no one has in practice (this hasn't come up in the 20 year history of sets and in the 30 year history of dicts). In general, our position is that all behaviors are implementation details unless the docs say otherwise. We likewise don't document that __hash__ is called and can raise a TypeError if missing or some other error in the hash logic, nor do we explicitly document that the return value of the method is None. People reading about set.add just want to know that it adds a value to a set; in general, they don't care about the mechanics. IMO the PR just makes the docs less readable.

I recommend against making any change. While satisfying to the OP, this is unlikely to benefit any reader. Instead, it is likely to cause unnecessary worry and confusion about an issue that no one has in practice (this hasn't come up in the 20 year history of sets and in the 30 year history of dicts). In general, our position is that all behaviors are implementation details unless the docs say otherwise. We likewise don't document that __hash__ is called and can raise a TypeError if missing or some other error in the hash logic, nor do we explicitly document that the return value of the method is None. People reading about set.add just want to know that it adds a value to a set; in general, they don't care about the mechanics. IMO the PR just makes the docs less readable.

ok i'll close the PR then