[Python-checkins] bpo-45246: Document that sorted() only uses "<" comparisons (GH-28494)
rhettinger
webhook-mailer at python.org
Tue Sep 21 13:26:36 EDT 2021
https://github.com/python/cpython/commit/9a0dcc5b2e04d9c51350107734f12a1cbc0284a7
commit: 9a0dcc5b2e04d9c51350107734f12a1cbc0284a7
branch: main
author: Raymond Hettinger <rhettinger at users.noreply.github.com>
committer: rhettinger <rhettinger at users.noreply.github.com>
date: 2021-09-21T12:26:27-05:00
summary:
bpo-45246: Document that sorted() only uses "<" comparisons (GH-28494)
files:
M Doc/library/functions.rst
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index a8fc7023d1195..19d67e9d754c2 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
+ <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