[issue4090] Documenting set comparisons and operations

[Raymond Hettinger]

Raymond Hettinger <rhettinger at users.sourceforge.net> added the comment:

I'll update the note in the Ref Manual section on comparisons.

The docs on sets, dicts, and other containers need to remain clean.  I
object to littering the docs with these kind of "omg danger" messages. 
For beginners using the docs to learn what a container does, these kind
of notes are hard to understand, raise unnecessary worries about the
robustness of the language, and don't provide actionable information. 
For advanced users like yourselves, it doesn't help either.  All it does
is provide some minimal satisfaction that your favorite annoying oddity
is in the docs.

Also, the set/dict docs are the wrong place to discuss the issue.  They
happen to be the arbitrary tool you chose to demonstrate an issue that
properly relates to comparisons in Python.  Since the very beginning, it
has been possible to create comparisons that violate our mental
invariants for containers.  You can feed a partial or random ordering to
sort.  Mertz has an article on oddities arising from identity versus
equality.  A rich comparison can return a vector but get collapsed into
a boolean by the == operator.  You can get hash functions that don't
correspond to equality, etc.  There are tricks with NaN being identical
to itself but not equal to itself.  If these things get noted at all, it
should be in the docs for numbers and nans or comparisons.  It makes no
sense to try to add a comment to every possible place that has an
equality invariant that can be fooled.  For example, it is not hard to
produce a list example where len(s)==1 and s[0] != x and x in s, just
set x=float('nan') and s=[x].  But, of course, we're not going to
clutter the list docs with this nonsense.

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue4090>
_______________________________________