Clarify NotImplemented vs NotImplementedError. Initial patch by Emmanuel...

Clarify NotImplemented vs NotImplementedError.  Initial patch by Emmanuel Barry.  Closes issue 27242.

Doc/library/constants.rst

@@ -33,16 +33,22 @@ A small number of constants live in the built-in namespace.  They are:
    (e.g. :meth:`__imul__`, :meth:`__iand__`, etc.) for the same purpose.
    Its truth value is true.
 
-.. note::
+   .. note::
+
+      When a binary (or in-place) method returns ``NotImplemented`` the
+      interpreter will try the reflected operation on the other type (or some
+      other fallback, depending on the operator).  If all attempts return
+      ``NotImplemented``, the interpreter will raise an appropriate exception.
+      Incorrectly returning ``NotImplemented`` will result in a misleading
+      error message or the ``NotImplemented`` value being returned to Python code.
+
+      See :ref:`implementing-the-arithmetic-operations` for examples.
 
-   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.
+   .. note::
 
-   See
-   :ref:`implementing-the-arithmetic-operations`
-   for more details.
+      ``NotImplentedError`` and ``NotImplemented`` are not interchangeable,
+      even though they have similar names and purposes.
+      See :exc:`NotImplementedError` for details on when to use it.
 
 
 .. data:: Ellipsis

Doc/library/exceptions.rst

@@ -228,9 +228,21 @@ The following exceptions are the exceptions that are usually raised.
 .. exception:: NotImplementedError
 
    This exception is derived from :exc:`RuntimeError`.  In user defined base
-   classes, abstract methods should raise this exception when they require derived
-   classes to override the method.
+   classes, abstract methods should raise this exception when they require
+   derived classes to override the method, or while the class is being
+   developed to indicate that the real implementation still needs to be added.
 
+   .. note::
+
+      It should not be used to indicate that an operater or method is not
+      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::
+
+      ``NotImplementedError`` and ``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]]])
@@ -436,6 +448,15 @@ The following exceptions are the exceptions that are usually raised.
    Raised when an operation or function is applied to an object of inappropriate
    type.  The associated value is a string giving details about the type mismatch.
 
+   This exception may be raised by user code to indicate that an attempted
+   operation on an object is not supported, and is not meant to be. If an object
+   is meant to support a given operation but has not yet provided an
+   implementation, :exc:`NotImplementedError` is the proper exception to raise.
+
+   Passing arguments of the wrong type (e.g. passing a :class:`list` when an
+   :class:`int` is expected) should result in a :exc:`TypeError`, but passing
+   arguments with the wrong value (e.g. a number outside expected boundaries)
+   should result in a :exc:`ValueError`.
 
 .. exception:: UnboundLocalError