[issue15997] NotImplemented needs to be documented

[Max]

New submission from Max:

Quoting from http://docs.python.org/reference/datamodel.html#the-standard-type-hierarchy:

NotImplemented
This type has a single value. There is a single object with this value. This object is accessed through the built-in name NotImplemented. 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.) Its truth value is true.

This is not a sufficient description of NotImplemented behavior. What does it mean "reflected operation" (I assume it is other.__eq__(self), but it needs to be clarified), and what does it mean "or some other fallback" (wouldn't developers need to know?). It also doesn't state what happens if the reflected operation or the fallback again return NotImplemented.

The rest of the documentation doesn't seem to talk about this either, despite several mentions of NotImplemented, with references to other sections.

This is particularly serious problem because Python's behavior changed in this respect not that long ago.

----------
assignee: docs at python
components: Documentation
messages: 170860
nosy: docs at python, max
priority: normal
severity: normal
status: open
title: NotImplemented needs to be documented
type: enhancement
versions: Python 3.2

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