[New-bugs-announce] [issue29321] Wrong documentation for unicode and str comparison

[RK-5wWm9h]

New submission from RK-5wWm9h:

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!  :-)

----------
assignee: docs at python
components: Documentation
messages: 285790
nosy: RK-5wWm9h, docs at python
priority: normal
severity: normal
status: open
title: Wrong documentation for unicode and str comparison
type: behavior
versions: Python 2.7

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