classification
Title: Wrong documentation (Language Ref) for unicode and str comparison
Type: behavior Stage: resolved
Components: Documentation Versions: Python 2.7
process
Status: closed Resolution: out of date
Dependencies: Superseder: Doc: remove errors about mixed-type comparisons.
View: 12067
Assigned To: docs@python Nosy List: RK-5wWm9h, docs@python, martin.panter
Priority: normal Keywords:

Created on 2017-01-19 14:26 by RK-5wWm9h, last changed 2017-05-23 06:16 by martin.panter. This issue is now closed.

Messages (3)
msg285790 - (view) Author: (RK-5wWm9h) Date: 2017-01-19 14:26
PROBLEM (IN BRIEF):

In the currently published 2.7.13 The Python Language Reference manual, section 5.9 "Comparisons" (https://docs.python.org/2/reference/expressions.html#comparisons):

    "If both are numbers, they are converted to a common type. Otherwise, objects of different types always compare unequal..."

This an *incorrect (and misleading) statement*.


PROPOSED FIX:

Insert a new sentence, to give this resulting text:

    "If both are numbers, they are converted to a common type. If one is str and the other unicode, they are compared as below. Otherwise, objects of different types always compare unequal..."


DETAILS, JUSTIFICATION, CORRECTNESS, ETC:

The behaviour that a str and a unicode object -- despite being objects of different types -- may compare equal, is explicitly stated several paragraphs later:

    "* Strings are compared lexicographically using the numeric equivalents (the result of the built-in function ord()) of their characters. Unicode and 8-bit strings are fully interoperable in this behavior. [4]"

Text in the 2.7.13 The Python Standard Library (Library Reference manual) is careful to cover this unicode - str case (https://docs.python.org/2/library/stdtypes.html#comparisons):

    "Objects of different types, except different numeric types and different string types, never compare equal; such objects are ordered consistently but arbitrarily (so that sorting a heterogeneous array yields a consistent result)."


IMPACT AND RELATED BUG:

The current incorrect text is really misleading for anyone reading the Language Ref.  It's easy to see the categorical statement and stop reading because your question has been answered.

Further, the Library ref about unicode and str (The Python Standard Library (Library Reference manual) section 5.6 "Sequence Types": https://docs.python.org/2/library/stdtypes.html#sequence-types-str-unicode-list-tuple-bytearray-buffer-xrange), links here.  Link text: "(For full details see Comparisons in the language reference.)".

(Aside: That paragraph has a mistake similar to this present bug: it says "to compare equal, every element must compare equal and the two sequences must be of the same type"; I'll file a separate bug for it.)

PS: First time reporting a Python bug; following https://docs.python.org/2/bugs.html.  Hope I did ok!  :-)
msg285805 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2017-01-19 16:31
The Python 3 version of this was rewritten in Issue 12067. It would be good to port the new text to the Python 2 version, although that is not straightforward because of various differences between Python 2 and 3.

That doesn’t rule out making smaller more specific edits in the mean time. However your proposal still seems misleading to only mention str and unicode as special cases. It does not allow for str vs bytearray, set vs frozenset, or custom classes/types implementing their own __eq__() etc methods.
msg294234 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2017-05-23 06:16
I backported Issue 12067 documentation, so hopefully this is fixed.
History
Date User Action Args
2017-05-23 06:16:50martin.pantersetstatus: open -> closed
superseder: Doc: remove errors about mixed-type comparisons.
messages: + msg294234

resolution: out of date
stage: resolved
2017-01-19 16:31:32martin.pantersetnosy: + martin.panter
messages: + msg285805
2017-01-19 16:22:29martin.panterlinkissue12067 dependencies
2017-01-19 14:42:45RK-5wWm9hsettitle: Wrong documentation for unicode and str comparison -> Wrong documentation (Language Ref) for unicode and str comparison
2017-01-19 14:26:43RK-5wWm9hcreate