Reviewers: gvanrossum, stoneleaf, Jelle Zijlstra, SilentGhost, Message: A few typos and some nits. Mostly good otherwise. http://bugs.python.org/review/27242/diff/18040/Doc/library/constants.rst File Doc/library/constants.rst (right): http://bugs.python.org/review/27242/diff/18040/Doc/library/constants.rst#new... Doc/library/constants.rst:50: even though they have similar purposes. See :exc:`NotImplementedError` Typo: Implented. Otherwise I'd use :exc:`NotImplementedError` on the above line instead of ``NotImplementedError`` Also s/similar purposes/similar names/ here too. http://bugs.python.org/review/27242/diff/18040/Doc/library/exceptions.rst File Doc/library/exceptions.rst (right): http://bugs.python.org/review/27242/diff/18040/Doc/library/exceptions.rst#ne... Doc/library/exceptions.rst:244: even though they have similar purposes. See :data:`NotImplemented` for s/similar purposes/similar names/ IMO. I'd also use :data:`NotImplemented` instead of ``NotImplemented`` on the above line. Also, there's not really a need to reference NotImplementedError from within its own block; but if you do it, please also do this in NotImplemented. Typo: "Implented" on the above line. Please review this at http://bugs.python.org/review/27242/ Affected files: Doc/library/constants.rst Doc/library/exceptions.rst diff --git a/Doc/library/constants.rst b/Doc/library/constants.rst --- a/Doc/library/constants.rst +++ b/Doc/library/constants.rst @@ -26,30 +26,36 @@ A small number of constants live in the .. data:: NotImplemented Special value which should be returned by the binary special methods (e.g. :meth:`__eq__`, :meth:`__lt__`, :meth:`__add__`, :meth:`__rsub__`, etc.) to indicate that the operation is not implemented with respect to the other type; may be returned by the in-place binary special methods (e.g. :meth:`__imul__`, :meth:`__iand__`, etc.) for the same purpose. Its truth value is true. -.. note:: + .. note:: - 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. + 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 more details. + See :ref:`implementing-the-arithmetic-operations` for examples. + + .. note:: + + ``NotImplentedError`` and ``NotImplemented`` are not interchangeable, + even though they have similar purposes. See :exc:`NotImplementedError` + for details on when to use it. .. data:: Ellipsis The same as ``...``. Special value used mostly in conjunction with extended slicing syntax for user-defined container data types. .. data:: __debug__ diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst --- a/Doc/library/exceptions.rst +++ b/Doc/library/exceptions.rst @@ -221,23 +221,35 @@ The following exceptions are the excepti .. exception:: NameError Raised when a local or global name is not found. This applies only to unqualified names. The associated value is an error message that includes the name that could not be found. .. 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:: + + :exc:`NotImplentedError` and ``NotImplemented`` are not interchangeable, + even though they have similar purposes. See :data:`NotImplemented` for + details on when to use it. .. exception:: OSError([arg]) OSError(errno, strerror[, filename[, winerror[, filename2]]]) .. index:: module: errno This exception is raised when a system function returns a system-related error, including I/O failures such as "file not found" or "disk full" (not for illegal argument types or other incidental errors). @@ -429,20 +441,29 @@ The following exceptions are the excepti The exit status or error message that is passed to the constructor. (Defaults to ``None``.) .. exception:: TypeError 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 Raised when a reference is made to a local variable in a function or method, but no value has been bound to that variable. This is a subclass of :exc:`NameError`. .. exception:: UnicodeError