pythongh-129015: Improve disambiguation between NotImplemented and NotImplementedError (python#129562)

---------

Co-authored-by: Bénédikt Tran <[email protected]>
Co-authored-by: Adam Turner <[email protected]>

Author: 3 people

Doc/library/constants.rst

@@ -46,11 +46,12 @@ A small number of constants live in the built-in namespace.  They are:
 
       See :ref:`implementing-the-arithmetic-operations` for examples.
 
-   .. note::
+   .. caution::
 
-      ``NotImplementedError`` and :data:`!NotImplemented` are not interchangeable,
-      even though they have similar names and purposes.
-      See :exc:`NotImplementedError` for details on when to use it.
+      :data:`!NotImplemented` and :exc:`!NotImplementedError` are not
+      interchangeable. This constant should only be used as described
+      above; see :exc:`NotImplementedError` for details on correct usage
+      of the exception.
 
    .. versionchanged:: 3.9
       Evaluating :data:`!NotImplemented` in a boolean context was deprecated.

Doc/library/exceptions.rst

@@ -333,11 +333,13 @@ The following exceptions are the exceptions that are usually raised.
       meant to be supported at all -- in that case either leave the operator /
       method undefined or, if a subclass, set it to :data:`None`.
 
-   .. note::
+   .. caution::
+
+      :exc:`!NotImplementedError` and :data:`!NotImplemented` are not
+      interchangeable. This exception should only be used as described
+      above; see :data:`NotImplemented` for details on correct usage of
+      the built-in constant.
 
-      ``NotImplementedError`` and :data:`NotImplemented` are not interchangeable,
-      even though they have similar names and purposes.  See
-      :data:`!NotImplemented` for details on when to use it.
 
 .. exception:: OSError([arg])
                OSError(errno, strerror[, filename[, winerror[, filename2]]])