From: Łukasz Langa Date: Tue, 21 Sep 2021 20:32:09 +0000 (+0200) Subject: [3.10] bpo-45246: Document that sorted() only uses "<" comparisons (GH-28494) (GH... X-Git-Tag: v3.10.0~27 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=2e4d66d2e71d36de394e0e7a4e60ed7b6a539933;p=thirdparty%2FPython%2Fcpython.git [3.10] bpo-45246: Document that sorted() only uses "<" comparisons (GH-28494) (GH-28502) (cherry picked from commit 9a0dcc5b2e04d9c51350107734f12a1cbc0284a7) Co-authored-by: Raymond Hettinger --- diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 96f77ca33a98..f4c3ef4600f6 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 + ` 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