[3.12] gh-129015: Improve disambiguation between `NotImplemented` and `NotImplemented...

gh-129015: Improve disambiguation between `NotImplemented` and `NotImplementedError` (GH-129562)

---------

(cherry picked from commit a85eeb97710617404ba7a0fac3b264f586caf70c)

Co-authored-by: Mike Castle <dalgoda+github@gmail.com>
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 3eceecc4e0a736913b295a42f3e8e6a520d30431..383bc272116f7a0b81e20fb0865bf6c01eb67bff 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 is deprecated. While

diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst
index 7e0c0f05bb7156d38bf6c5c73bf56539d01c05d4..f168ab2cce7faf2a96928c636fcec27ec8ba93e3 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]]])