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

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.

I backported Issue 12067 documentation, so hopefully this is fixed.