Python NotImplemented constant

Question

Looking through decimal.py, it uses NotImplemented in many special methods. e.g.

class A(object):     def __lt__(self, a):         return NotImplemented      def __add__(self, a):         return NotImplemented 

The Python docs say:

NotImplemented

Special value which can be returned by the “rich comparison” special methods (__eq__(), __lt__(), and friends), to indicate that the comparison is not implemented with respect to the other type.

It doesn't talk about other special methods and neither does it describe the behavior.

It seems to be a magic object which if returned from other special methods raises TypeError, and in “rich comparison” special methods does nothing.

e.g.

print A() < A() 

prints True, but

print A() + 1 

raises TypeError, so I am curious as to what's going on and what is the usage/behavior of NotImplemented.

Answer 1

NotImplemented allows you to indicate that a comparison between the two given operands has not been implemented (rather than indicating that the comparison is valid, but yields False, for the two operands).

From the Python Language Reference:

For objects x and y, first x.__op__(y) is tried. If this is not implemented or returns NotImplemented, y.__rop__(x) is tried. If this is also not implemented or returns NotImplemented, a TypeError exception is raised. But see the following exception:

Exception to the previous item: if the left operand is an instance of a built-in type or a new-style class, and the right operand is an instance of a proper subclass of that type or class and overrides the base's __rop__() method, the right operand's __rop__() method is tried before the left operand's __op__() method. This is done so that a subclass can completely override binary operators. Otherwise, the left operand's __op__() method would always accept the right operand: when an instance of a given class is expected, an instance of a subclass of that class is always acceptable.