From 085d7ce11a0a855dec53ba2019360c549bfcbe5f Mon Sep 17 00:00:00 2001 From: Raymond Hettinger Date: Tue, 21 Sep 2021 11:56:10 -0500 Subject: [PATCH] bpo-45246: Document that sorted() only uses "<" comparisons --- Doc/library/functions.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index a8fc7023d11953..19d67e9d754c2c 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -1592,6 +1592,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