[docs] Comparison of sequences

[Matthew Gilson]

It seems to me that the documentation on comparison for sequences could 
be improved slightly.

(reference)
http://docs.python.org/3/reference/expressions.html#not-in

"""
Tuples and lists are compared lexicographically using comparison of 
corresponding elements. This means that to compare equal, each element 
must compare equal and the two sequences must be of the same type and 
have the same length.

If not equal, the sequences are ordered the same as their first 
differing elements. For example, [1,2,x] <= [1,2,y] has the same value 
as x <= y. If the corresponding element does not exist, the shorter 
sequence is ordered first (for example, [1,2] < [1,2,3]).
"""

The first paragraph is clear -- if you compare two sequences 
(lists/tuples) which are of different type then they aren't equal. 
However, the second paragraph is not quite as clear what the result of 
rich comparisons should be if you compare a list and a tuple. e.g. what 
should the result of `[2] > (1,)` be?  In python3.x, this results in a 
TypeError (presumably because the rich comparison methods aren't 
overloaded to allow that behavior -- But documentation reader doesn't 
really have a good way of knowing that), but on python2.x the ordering 
is not based on their elements as implied by the documentation but are 
instead ordered based on their type.

I propose that the documentation should say something like this:

Python3.x:

"If not equal, the sequences are ordered the same as their first 
differing elements if they have the same type.  Otherwise the comparison 
results in a `TypeError`".

Python2.7:

"If not equal, the sequences are ordered the same as their first 
differing elements if they have the same type.  Otherwise the result is 
the same as comparing the sequence types."