Skip to content

Commit 298e041

Browse files
bpo-41793: Fix an inaccuracy about reflected methods in datamodel docs (GH-22257)
* Qualifying that the right operand's type must be a *strict* subclass for the reflected method to take precedence avoids an edge case / counter-example when the types are actually equal. Co-authored-by: Ethan Furman <[email protected]>
1 parent 5527c40 commit 298e041

File tree

1 file changed

+14
-11
lines changed

1 file changed

+14
-11
lines changed

Doc/reference/datamodel.rst

Lines changed: 14 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -3334,12 +3334,13 @@ left undefined.
33343334
These methods are called to implement the binary arithmetic operations
33353335
(``+``, ``-``, ``*``, ``@``, ``/``, ``//``, ``%``, :func:`divmod`,
33363336
:func:`pow`, ``**``, ``<<``, ``>>``, ``&``, ``^``, ``|``) with reflected
3337-
(swapped) operands. These functions are only called if the left operand does
3338-
not support the corresponding operation [#]_ and the operands are of different
3339-
types. [#]_ For instance, to evaluate the expression ``x - y``, where *y* is
3340-
an instance of a class that has an :meth:`__rsub__` method,
3341-
``type(y).__rsub__(y, x)`` is called if ``type(x).__sub__(x, y)`` returns
3342-
:data:`NotImplemented`.
3337+
(swapped) operands. These functions are only called if the operands
3338+
are of different types, when the left operand does not support the corresponding
3339+
operation [#]_, or the right operand's class is derived from the left operand's
3340+
class. [#]_ For instance, to evaluate the expression ``x - y``, where *y* is
3341+
an instance of a class that has an :meth:`__rsub__` method, ``type(y).__rsub__(y, x)``
3342+
is called if ``type(x).__sub__(x, y)`` returns :data:`NotImplemented` or ``type(y)``
3343+
is a subclass of ``type(x)``. [#]_
33433344

33443345
.. index:: pair: built-in function; pow
33453346

@@ -3354,7 +3355,6 @@ left undefined.
33543355
non-reflected method. This behavior allows subclasses to override their
33553356
ancestors' operations.
33563357

3357-
33583358
.. method:: object.__iadd__(self, other)
33593359
object.__isub__(self, other)
33603360
object.__imul__(self, other)
@@ -3881,7 +3881,10 @@ An example of an asynchronous context manager class::
38813881
method—that will instead have the opposite effect of explicitly
38823882
*blocking* such fallback.
38833883
3884-
.. [#] For operands of the same type, it is assumed that if the non-reflected
3885-
method -- such as :meth:`~object.__add__` -- fails then the overall
3886-
operation is not
3887-
supported, which is why the reflected method is not called.
3884+
.. [#] For operands of the same type, it is assumed that if the non-reflected method
3885+
(such as :meth:`~object.__add__`) fails then the operation is not supported, which is why the
3886+
reflected method is not called.
3887+
3888+
.. [#] If the right operand's type is a subclass of the left operand's type, the
3889+
reflected method having precedence allows subclasses to override their ancestors'
3890+
operations.

0 commit comments

Comments
 (0)