From 20bd9f033af72b4e886ab20d46b1558c4dbf3a3f Mon Sep 17 00:00:00 2001 From: Ethan Furman Date: Fri, 5 Aug 2016 15:10:16 -0700 Subject: Clarify NotImplemented vs NotImplementedError. Initial patch by Emmanuel Barry. Closes issue 27242. --- Doc/library/constants.rst | 22 ++++++++++++++-------- Doc/library/exceptions.rst | 25 +++++++++++++++++++++++-- 2 files changed, 37 insertions(+), 10 deletions(-) diff --git a/Doc/library/constants.rst b/Doc/library/constants.rst index d5a0f09..f0742ce 100644 --- a/Doc/library/constants.rst +++ b/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 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 -- cgit v0.12