Issue 5479: Add functools.total_ordering class decorator.

diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst
index a09d3cf7255d3eaf1ad5b89fe222385c019f88d5..8f9528a1573a85532c57f199ff45e6db81e86845 100644 (file)
--- a/Doc/library/functools.rst
+++ b/Doc/library/functools.rst
@@ -17,6 +17,26 @@ function for the purposes of this module.
 
 The :mod:`functools` module defines the following functions:
 
+.. function:: total_ordering(cls)
+
+   Given a class defining one or more rich comparison ordering methods, this
+   class decorator supplies the rest.  This simplies the effort involved
+   in specifying all of the possible rich comparison operations:
+
+   The class must define one of :meth:`__lt__`, :meth:`__le__`,
+   :meth:`__gt__`, or :meth:`__ge__`.
+   In addition, the class should supply an :meth:`__eq__` method.
+
+   For example::
+
+       @total_ordering
+       class Student:
+           def __eq__(self, other):
+               return ((self.lastname.lower(), self.firstname.lower()) ==
+                       (other.lastname.lower(), other.firstname.lower()))
+           def __lt__(self, other):
+               return ((self.lastname.lower(), self.firstname.lower()) <
+                       (other.lastname.lower(), other.firstname.lower()))
 
 .. function:: reduce(function, iterable[, initializer])