[issue15997] NotImplemented needs to be documented

[Terry J. Reedy]

Terry J. Reedy added the comment:

I was wrong about TypeError; forget that. The seeming equivalent to 'return NotImplement' is not defining the method. My confusion stemed from the fact that NotImplemented returned from special methods gets intercepted and converted to TypeError exceptions by the operator functions that call them -- unless there is an alternate path *and* the alternate does not also return NotImplemented.

Changing "will try reflected operation" to "will return the result of the reflected operation called on the swapped arguments" is wrong as the latter is not completely correct. If the fallback also returns NotImplemented, it is ignored and TypeError is raised the same as if the fallback did not exist. But as Martin said, the details belong in operator documentation.

I would like to more closely parallel the None entry, which has

"It is used to signify the absence of a value in many situations, e.g.  it is returned from functions that don’t explicitly return anything."

by replacing

"Numeric methods and rich comparison methods may return this value if they do not implement the operation for the operands provided. (The interpreter will then try the reflected operation, or some other fallback, depending on the operator.)"

with

"It is used to signify that a method does not implement the operation requested for the operands provided. For example, the special methods for arithmetic and and rich comparison may return NotImplemented, and when they do, the interpreter will try the reversed or reflected operation."

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue15997>
_______________________________________