[Python-checkins] r60146 - python/trunk/Doc/c-api/typeobj.rst

Sun Jan 20 20:48:40 CET 2008

Author: georg.brandl
Date: Sun Jan 20 20:48:40 2008
New Revision: 60146
Modified:
 python/trunk/Doc/c-api/typeobj.rst
Log:
#1219903: fix tp_richcompare docs.
Modified: python/trunk/Doc/c-api/typeobj.rst
==============================================================================

--- python/trunk/Doc/c-api/typeobj.rst	(original)
+++ python/trunk/Doc/c-api/typeobj.rst	Sun Jan 20 20:48:40 2008
@@ -662,13 +662,19 @@
 
 .. cmember:: richcmpfunc PyTypeObject.tp_richcompare
 
- An optional pointer to the rich comparison function.
+ An optional pointer to the rich comparison function, whose signature is
+ ``PyObject *tp_richcompare(PyObject *a, PyObject *b, int op)``.
 
- The signature is the same as for :cfunc:`PyObject_RichCompare`. The function
- should return the result of the comparison (usually ``Py_True`` or
- ``Py_False``). If the comparison is undefined, it must return
- ``Py_NotImplemented``, if another error occurred it must return ``NULL`` and set
- an exception condition.
+ The function should return the result of the comparison (usually ``Py_True``
+ or ``Py_False``). If the comparison is undefined, it must return
+ ``Py_NotImplemented``, if another error occurred it must return ``NULL`` and
+ set an exception condition.
+
+ .. note::
+
+ If you want to implement a type for which only a limited set of
+ comparisons makes sense (e.g. ``==`` and ``!=``, but not ``<`` and
+ friends), directly raise :exc:`TypeError` in the rich comparison function.
 
 This field is inherited by subtypes together with :attr:`tp_compare` and
 :attr:`tp_hash`: a subtype inherits all three of :attr:`tp_compare`,
@@ -694,10 +700,10 @@
 | :const:`Py_GE` | ``>=`` |
 +----------------+------------+
 
+
 The next field only exists if the :const:`Py_TPFLAGS_HAVE_WEAKREFS` flag bit is
 set.
 
-
 .. cmember:: long PyTypeObject.tp_weaklistoffset
 
 If the instances of this type are weakly referenceable, this field is greater
