gh-129015: Improve disambiguation between `NotImplemented` and `NotImplementedError...

---------

Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

diff --git a/Doc/library/constants.rst b/Doc/library/constants.rst
index 04bb8c51a3b197f6e3f52292c3f87dc0c8f418d9..c0ac4ea8412ebdde671390ece98076c554abf283 100644 (file)
--- a/Doc/library/constants.rst
+++ b/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.

diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst
index 319d261ef3fb4d86cfb18fbc135e41beab9733bf..c56604339030d3b92e2bd9ca87494995955cc1d6 100644 (file)
--- a/Doc/library/exceptions.rst
+++ b/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]]])