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

1 files changed, 23 insertions, 2 deletions

diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst
index 5a71933..1747efe 100644
--- a/Doc/library/exceptions.rst
+++ b/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