[Python-checkins] cpython (merge 3.4 -> default): Issue22780: reword NotImplemented docs to emphasise should

ethan.furman python-checkins at python.org
Thu Nov 27 06:18:15 CET 2014


https://hg.python.org/cpython/rev/b6ee02acaae9
changeset:   93615:b6ee02acaae9
parent:      93612:d502b5d60e00
parent:      93614:ebb8865dcf54
user:        Ethan Furman <ethan at stoneleaf.us>
date:        Wed Nov 26 21:17:53 2014 -0800
summary:
  Issue22780: reword NotImplemented docs to emphasise should

files:
  Doc/library/constants.rst   |  20 +++++++++++++++++---
  Doc/library/numbers.rst     |   2 ++
  Doc/reference/datamodel.rst |   7 ++++++-
  3 files changed, 25 insertions(+), 4 deletions(-)


diff --git a/Doc/library/constants.rst b/Doc/library/constants.rst
--- a/Doc/library/constants.rst
+++ b/Doc/library/constants.rst
@@ -26,9 +26,23 @@
 
 .. data:: NotImplemented
 
-   Special value which should be returned by the special methods
-   (:meth:`__eq__`, :meth:`__lt__`, :meth:`__add__`, etc.) to indicate
-   that the operation is not implemented with respect to the other type.
+   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::
+
+   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.
+
+   See
+   :ref:`implementing-the-arithmetic-operations`
+   for more details.
 
 
 .. data:: Ellipsis
diff --git a/Doc/library/numbers.rst b/Doc/library/numbers.rst
--- a/Doc/library/numbers.rst
+++ b/Doc/library/numbers.rst
@@ -110,6 +110,8 @@
     MyFoo.register(Real)
 
 
+.. _implementing-the-arithmetic-operations:
+
 Implementing the arithmetic operations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -154,11 +154,16 @@
 
    This type has a single value.  There is a single object with this value. This
    object is accessed through the built-in name ``NotImplemented``. Numeric methods
-   and rich comparison methods may return this value if they do not implement the
+   and rich comparison methods should return this value if they do not implement the
    operation for the operands provided.  (The interpreter will then try the
    reflected operation, or some other fallback, depending on the operator.)  Its
    truth value is true.
 
+   See
+   :ref:`implementing-the-arithmetic-operations`
+   for more details.
+
+
 Ellipsis
    .. index:: object: Ellipsis
 

-- 
Repository URL: https://hg.python.org/cpython


More information about the Python-checkins mailing list