Issue 1219903: tp_richcompare documentation wrong and incomplete (original) (raw)

tp_richcompare slot as documented here:

http://www.python.org/doc/current/api/type-structs.html

is incorrect. It states: "The signature is the same as for PyObject_RichCompare(). The function should return 1 if the requested comparison returns true, 0 if it returns false. It should return -1 and set an exception condition when an error occurred during the comparison"

However PyObject_RichCompare() actually returns a PyObject* not an int. The documentation at this location really should spell out the full specification for the richcomparefunc.

In addition, it's not exactly clear how to implement unordered comparisons (ones where == and != work, but <, >, <=, >= don't). You cannot return Py_NotImplemented because richcomp always falls back to pointer comparison unless PyInstance_Check() is true. For extension types, this won't be the case and the right thing to do is actually raise the exception in the richcomp function. This needs to be documented too.