1 files changed, 27 insertions, 4 deletions
diff --git a/Doc/ref/ref3.tex b/Doc/ref/ref3.tex
index d0c8ccf..15fc188 100644
--- a/Doc/ref/ref3.tex
+++ b/Doc/ref/ref3.tex
@@ -1307,6 +1307,11 @@ defines mutable objects and implements a \method{__cmp__()} or
 since the dictionary implementation requires that a key's hash value
 is immutable (if the object's hash value changes, it will be in the
 wrong hash bucket).
+
+\versionchanged[\method{__hash__()} may now also return a long
+integer object; the 32-bit integer is then derived from the hash
+of that object]{2.5}
+
 \withsubitem{(object method)}{\ttindex{__cmp__()}}
 \end{methoddesc}
 
@@ -1886,6 +1891,9 @@ method should be the equivalent to using \method{__floordiv__()} and
 \method{__pow__()} should be defined to accept an optional third
 argument if the ternary version of the built-in
 \function{pow()}\bifuncindex{pow} function is to be supported.
+
+If one of those methods does not support the operation with the
+supplied arguments, it should return \code{NotImplemented}.
 \end{methoddesc}
 
 \begin{methoddesc}[numeric object]{__div__}{self, other}
@@ -1918,13 +1926,28 @@ called to implement the binary arithmetic operations (\code{+},
 \function{pow()}\bifuncindex{pow}, \code{**}, \code{<<},
 \code{>>}, \code{\&}, \code{\^}, \code{|}) with reflected
 (swapped) operands.  These functions are only called if the left
-operand does not support the corresponding operation.  For instance,
-to evaluate the expression \var{x}\code{-}\var{y}, where \var{y} is an
-instance of a class that has an \method{__rsub__()} method,
-\code{\var{y}.__rsub__(\var{x})} is called.  Note that ternary
+operand does not support the corresponding operation and the
+operands are of different types.\footnote{
+    For operands of the same type, it is assumed that if the
+    non-reflected method (such as \method{__add__()}) fails the
+    operation is not supported, which is why the reflected method
+    is not called.} 
+For instance, to evaluate the expression \var{x}\code{-}\var{y},
+where \var{y} is an instance of a class that has an
+\method{__rsub__()} method, \code{\var{y}.__rsub__(\var{x})}
+is called if \code{\var{x}.__sub__(\var{y})} returns
+\var{NotImplemented}.
+
+Note that ternary
 \function{pow()}\bifuncindex{pow} will not try calling
 \method{__rpow__()} (the coercion rules would become too
 complicated).
+
+\note{If the right operand's type is a subclass of the left operand's
+      type and that subclass provides the reflected method for the
+      operation, this method will be called before the left operand's
+      non-reflected method.  This behavior allows subclasses to
+      override their ancestors' operations.}
 \end{methoddesc}
 
 \begin{methoddesc}[numeric object]{__iadd__}{self, other}