[docs] sorted() documentation possible improvement, un-'stable' cases

[John White]

sorted() documentation states: 

"The built-in sorted() function is guaranteed to be stable. A sort is
stable if it guarantees not to change the relative order of elements that
compare equal — this is helpful for sorting in multiple passes (for
example, sort by department, then by salary grade). "

Some people might get the misconception that order will be stable even on different runs of the exact same code. 

e.g.  the code below: 

d = {'a': 0, 'b': 0, 'c': 0, 'd': 1}
print(sorted(d, key=lambda x: d[x]))

# It would print a different order on different runs (assuming PYTHONHASHSEED=random).

For more details see this StackOverflow question. 

Perhaps adding the following in the documentation might help: 

"It is not guaranteed to be stable on different runs  or when the order of the given iterable has changed (even if the iterable is a dict)."




 		 	   		  
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20150916/1986d24d/attachment.html>