[Python-checkins] [3.10] bpo-45246: Document that sorted() only uses "<" comparisons (GH-28494) (GH-28502)

ambv webhook-mailer at python.org
Tue Sep 21 16:32:13 EDT 2021

commit: 0d41bf15702832540afc1b1c078bc4fde5baebd6
branch: 3.10
author: Łukasz Langa <lukasz at langa.pl>
committer: ambv <lukasz at langa.pl>
date: 2021-09-21T22:32:09+02:00

[3.10] bpo-45246: Document that sorted() only uses "<" comparisons (GH-28494) (GH-28502)

(cherry picked from commit 9a0dcc5b2e04d9c51350107734f12a1cbc0284a7)

Co-authored-by: Raymond Hettinger <rhettinger at users.noreply.github.com>

M Doc/library/functions.rst

diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index 9629acec2bc72..e89323f99fd6c 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -1603,6 +1603,15 @@ are always available.  They are listed here in alphabetical order.
    compare equal --- this is helpful for sorting in multiple passes (for
    example, sort by department, then by salary grade).
+   The sort algorithm uses only ``<`` comparisons between items.  While
+   defining an :meth:`~object.__lt__` method will suffice for sorting,
+   :PEP:`8` recommends that all six :ref:`rich comparisons
+   <comparisons>` be implemented.  This will help avoid bugs when using
+   the same data with other ordering tools such as :func:`max` that rely
+   on a different underlying method.  Implementing all six comparisons
+   also helps avoid confusion for mixed type comparisons which can call
+   reflected the :meth:`~object.__gt__` method.
    For sorting examples and a brief sorting tutorial, see :ref:`sortinghowto`.
 .. decorator:: staticmethod

More information about the Python-checkins mailing list