(3.4) Issue22780: reword NotImplemented docs to emphasise should

diff --git a/Doc/library/constants.rst b/Doc/library/constants.rst
index 059a21d5c83ead3a80060be885ac94e6f87e5cec..42b5af23a5b9f2a81b3bb22940f8ceddfae5bbe5 100644 (file)
--- a/Doc/library/constants.rst
+++ b/Doc/library/constants.rst
@@ -26,9 +26,24 @@ A small number of constants live in the built-in namespace.  They are:
 
 .. data:: NotImplemented
 
-   Special value which can be returned by the "rich comparison" special methods
-   (:meth:`__eq__`, :meth:`__lt__`, and friends), to indicate that the comparison
-   is not implemented with respect to the other type.
+   Special value which should be returned by the binary special methods
+   (e.g. :meth:`__eq__`, :meth:`__lt__`, :meth:`__add__`, :meth:`__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. :meth:`__imul__`, :meth:`__iand__`, etc.) for the same purpose.
+   Its truth value is true.
+
+.. note::
+
+   When ``NotImplemented`` is returned, the interpreter will then try the
+   reflected operation on the other type, or some other fallback, depending
+   on the operator.  If all attempted operations return ``NotImplemented``, the
+   interpreter will raise an appropriate exception.
+
+   See
+   :ref:`implementing-the-arithmetic-operations`
+   for more details.
+
 
 
 .. data:: Ellipsis

diff --git a/Doc/library/numbers.rst b/Doc/library/numbers.rst
index fec04ed722cf90973b48bde3b3d59d6de658cae5..8ab07d0b93d9be02e37ea4d094bb21627a7c308f 100644 (file)
--- a/Doc/library/numbers.rst
+++ b/Doc/library/numbers.rst
@@ -110,6 +110,8 @@ those. You can add ``MyFoo`` between :class:`Complex` and
     MyFoo.register(Real)
 
 
+.. _implementing-the-arithmetic-operations:
+
 Implementing the arithmetic operations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index cbccb1e453f783cdbaee80c8a92ff25c7da3f6b5..43abf82766ed0c4da375fa7b5e471947bc9cf790 100644 (file)
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -154,11 +154,16 @@ 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
+   and rich comparison methods should 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.
 
+   See
+   :ref:`implementing-the-arithmetic-operations`
+   for more details.
+
+
 Ellipsis
    .. index:: object: Ellipsis