[docs] [issue37934] Docs: Clarify NotImplemented use cases

[Kyle Stanley]

Kyle Stanley <aeros167 at gmail.com> added the comment:

Thanks for the feedback Vedran and Raymond.

> It is not the purpose of the docs to list use cases.  Mostly we say what something does or how it is defined. As Vedran says, how people use it is their own business.

The underlying issue here seems to be that I misunderstood the existing section to suggest to suggest binary special methods are the only use case, which is probably a good argument in favor of not listing additional use cases. This can be misinterpreted as suggesting that others are not recommended, and lead to further confusion.


First sentence of the NotImplemented documentation:

> Special value which should be returned by the binary special methods (e.g. __eq__(), __lt__(), __add__(), __rsub__(), etc.) to indicate that the operation is not implemented with respect to the other type; may be returned by the in-place binary special methods (e.g. __imul__(), __iand__(), etc.) for the same purpose. 

Would it be viable to rephrase the existing section in a manner that explains the functional purpose of NotImplemented without revolving around its use case in binary special methods?

> Also, please be careful expanded the docs.  They quickly become a promise.

Good point, I may not have adequately considered that mentioning a use case turns into a promise for that functionality. This could easily result in a significant long-term maintenance cost.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue37934>
_______________________________________