Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

gh-85959: (bpo-41793) Fix an inaccuracy about reflected methods in datamodel docs #22257

Merged
merged 9 commits into from
Oct 29, 2024
25 changes: 14 additions & 11 deletions Doc/reference/datamodel.rst
Original file line number Diff line number Diff line change
Expand Up @@ -3334,12 +3334,13 @@ left undefined.
These methods are called to implement the binary arithmetic operations
(``+``, ``-``, ``*``, ``@``, ``/``, ``//``, ``%``, :func:`divmod`,
:func:`pow`, ``**``, ``<<``, ``>>``, ``&``, ``^``, ``|``) with reflected
(swapped) operands. These functions are only called if the left operand does
not support the corresponding operation [#]_ and the operands are of different
types. [#]_ For instance, to evaluate the expression ``x - y``, where *y* is
an instance of a class that has an :meth:`__rsub__` method,
``type(y).__rsub__(y, x)`` is called if ``type(x).__sub__(x, y)`` returns
:data:`NotImplemented`.
(swapped) operands. These functions are only called if the operands
are of different types, when the left operand does not support the corresponding
operation [#]_, or the right operand's class is derived from the left operand's
class. [#]_ For instance, to evaluate the expression ``x - y``, where *y* is
an instance of a class that has an :meth:`__rsub__` method, ``type(y).__rsub__(y, x)``
is called if ``type(x).__sub__(x, y)`` returns :data:`NotImplemented` or ``type(y)``
is a subclass of ``type(x)``. [#]_

ethanfurman marked this conversation as resolved.
Show resolved Hide resolved
.. index:: pair: built-in function; pow

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

wimglenn marked this conversation as resolved.
Show resolved Hide resolved

.. method:: object.__iadd__(self, other)
object.__isub__(self, other)
object.__imul__(self, other)
Expand Down Expand Up @@ -3881,7 +3881,10 @@ An example of an asynchronous context manager class::
method—that will instead have the opposite effect of explicitly
*blocking* such fallback.

.. [#] For operands of the same type, it is assumed that if the non-reflected
method -- such as :meth:`~object.__add__` -- fails then the overall
operation is not
supported, which is why the reflected method is not called.
.. [#] For operands of the same type, it is assumed that if the non-reflected method
(such as :meth:`~object.__add__`) fails then the operation is not supported, which is why the
reflected method is not called.

.. [#] If the right operand's type is a subclass of the left operand's type, the
reflected method having precedence allows subclasses to override their ancestors'
operations.
Loading