[Python-checkins] r79730 - python/trunk/Doc/library/functools.rst

[raymond.hettinger]

Author: raymond.hettinger
Date: Sun Apr  4 03:24:59 2010
New Revision: 79730

Log:
Issue 5479:  Add functools.total_ordering class decorator.

Modified:
   python/trunk/Doc/library/functools.rst

Modified: python/trunk/Doc/library/functools.rst
==============================================================================
--- python/trunk/Doc/library/functools.rst	(original)
+++ python/trunk/Doc/library/functools.rst	Sun Apr  4 03:24:59 2010
@@ -17,6 +17,26 @@
 
 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])