[docs] Doc: remove errors about mixed-type comparisons. (issue 12067)

[vadmium+py at gmail.com]

http://bugs.python.org/review/12067/diff/19802/Doc/reference/expressions.rst
File Doc/reference/expressions.rst (right):

http://bugs.python.org/review/12067/diff/19802/Doc/reference/expressions.rst#newcode1154
Doc/reference/expressions.rst:1154: 8-bit strings are fully
interoperable in this behavior. [#]_
On 2017/01/21 13:03:53, storchaka wrote:
> This description is misleading. Unicode and 8-bit strings are not
fully
> interoperable.
> 
> >>> chr(0xff) == unichr(0xff)
> __main__:1: UnicodeWarning: Unicode equal comparison failed to convert
both
> arguments to Unicode - interpreting them as being unequal
> False
> >>> chr(0xff) < unichr(0xff)
> Traceback (most recent call last):
>   File "<stdin>", line 1, in <module>
> UnicodeDecodeError: 'ascii' codec can't decode byte 0xff in position
0: ordinal
> not in range(128)
> 
> When compare str and unicode, the str operand is converted to Unicode.
If the
> conversion is failed, values are traited as non-equal.

Okay, I shall replace the second sentence with:

When comparing an 8-bit string and a Unicode string, the 8-bit string is
converted to Unicode. If the conversion fails, the strings are
considered unequal.

http://bugs.python.org/review/12067/diff/19802/Doc/reference/expressions.rst#newcode1174
Doc/reference/expressions.rst:1174: - For two collections to compare
equal, they must be of the same type, have
On 2017/01/21 13:03:53, storchaka wrote:
> Subclasses are comparable with base class or other subclasses of the
same base
> class.

This would apply equally to the Python 3 version.

Andy originally omitted the “built-in” clarifier, and wrote “(or
subtypes of each other)”. But then he wanted to make this specific to
only built-in types, not user-defined subclasses:

https://bugs.python.org/review/12067/diff2/12409:13054/Doc/reference/expressions.rst#oldcode1147

IMO much of the finer details would be better off separately with the
documentation for each type, e.g. in Doc/library/stdtypes.rst. We should
keep the documentation on expressions general. A bit like how the
documentation on function call expressions just points to a different
chapter for the behaviour of each built-in function.

http://bugs.python.org/review/12067/diff/19802/Doc/reference/expressions.rst#newcode1197
Doc/reference/expressions.rst:1197: User-defined classes that customize
their comparison behavior should follow
On 2017/01/21 13:03:53, storchaka wrote:
> Would it be worth to document when custom comparison methods should
return
> NotImplemented?

Perhaps. See <https://bugs.python.org/issue15997>. Some of the details
are already in datamodel.rst under __eq__() etc, but they may make more
sense here under the comparison operators.

For the time being, do you think the link to :meth:`__lt__` in the third
paragraph is enough of a hint?

> The hash of hashable user defined classes should be consistent with
the
> equality.

Agreed. I shall include a bullet point like

* The :func:`hash` result should be consistent with equality. Objects
that are equal should either have the same hash value, or be marked as
unhashable.

This also applies to Python 3.

http://bugs.python.org/review/12067/