diff --git a/Doc/library/constants.rst b/Doc/library/constants.rst --- a/Doc/library/constants.rst +++ b/Doc/library/constants.rst @@ -40,6 +40,23 @@ A small number of constants live in the built-in namespace. They are: on the operator. If all attempted operations return ``NotImplemented``, the interpreter will raise an appropriate exception. + Note that returning this value only makes sense for binary operations such as + :meth:`__lt__` or :meth:`__add__`. The appropriate way to signal that an + operation is unsupported is to leave the relevant method undefined. If the + method must be defined for some reason, invoking the default behaviour (by + calling the superclass' method with :func:`super`) or raising an exception + is the encouraged way to do this. If the superclass defines the operation but + the subclass wishes to suppress the support, setting ``__meth__ = None`` is + recommended. The interpreter does not recognize such an assignment as a special + case (except in the case of :meth:`__hash__`), and will simply throw an error + when trying to call it, since ``None`` is not callable. + + Despite bearing a similar name, ``NotImplemented`` and :exc:`NotImplementedError` + are fundamentally distinct. :exc:`NotImplementedError` is used to signal that + an operation is meant to be supported, but that it has not been implemented + yet. The appropriate exception to raise in the case of an unsupported operation + is :exc:`TypeError`. + See :ref:`implementing-the-arithmetic-operations` for more details. diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst --- a/Doc/library/exceptions.rst +++ b/Doc/library/exceptions.rst @@ -231,6 +231,21 @@ The following exceptions are the exceptions that are usually raised. classes, abstract methods should raise this exception when they require derived classes to override the method. +.. note:: + + This exception should only be raised in the cases where the subclasses need + to overwrite the method to provide an implementation. It may also be used + in development to signal that the implementation will come in the future. + However, it should not be used to indicate that an operation is not meant to + be supported at all. The correct exception to signal the lack of support for + a specific operation (regardless of the input) is :exc:`TypeError`. + + The purposes of :data:`NotImplemented` and of this exception tend to be confused, + due to having similar names. :data:`NotImplemented` is a return value used to + tell the interpreter that one operand of a binary operation cannot perform + the requested operation, and that it should try the reflected version, which + may be provided by the other argument. Failure from both arguments to perform + the operation will subsequently raise a :exc:`TypeError`. .. exception:: OSError([arg]) OSError(errno, strerror[, filename[, winerror[, filename2]]]) @@ -436,6 +451,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. 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 be a :exc:`ValueError`. .. exception:: UnboundLocalError