Comparable type in extension module

Question

To implement != and == for my CPython extension type, should I implement tp_compare, tp_richcompare or both?

Under what circumstances is each of them called?

Answer 1

tp_richcompare is analogous to the rich comparison special methods in the Python language itself. It is chosen in preference to tp_compare when the comparison operators are invoked on the class.

Use tp_richcompare when you want finer control over the comparison logic. For instance, there might be a very cheap way to determine equality, but not precedence. Say memcmp(a, b, sizeof(*a)) == 0 indicates that two very complex data structures are equal, but memcmp(a, b, sizeof(*a)) < 0 doesn't indicate that a is less than b, which instead requires an expensive algorithm to determine. The tp_compare function would require that you always use the expensive algorithm in order to return either a -1, 0 or 1. The tp_richcompare function, OTOH, tells you which comparison is intended, so you can choose either the expensive or the cheap algorithm, depending on the need at hand.

An additional advantage of tp_richcompare is that you can raise exceptions for operations that don't make sense, such as u < v where u and v are points in space.