From 4bd9caafb64589288e5171087070bde726178c58 Mon Sep 17 00:00:00 2001 From: andrei kulakov Date: Fri, 30 Jul 2021 12:52:44 -0400 Subject: [PATCH] bpo-41911: Update docs for various expressions (GH-27470) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Łukasz Langa --- Doc/reference/expressions.rst | 41 +++++++++++++++++++++++++++++------ 1 file changed, 34 insertions(+), 7 deletions(-) diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst index aaa21349076ba2..b1b32dfba26e5b 100644 --- a/Doc/reference/expressions.rst +++ b/Doc/reference/expressions.rst @@ -1153,6 +1153,7 @@ Raising ``0.0`` to a negative power results in a :exc:`ZeroDivisionError`. Raising a negative number to a fractional power results in a :class:`complex` number. (In earlier versions it raised a :exc:`ValueError`.) +This operation can be customized using the special :meth:`__pow__` method. .. _unary: @@ -1174,14 +1175,16 @@ All unary arithmetic and bitwise operations have the same priority: single: operator; - (minus) single: - (minus); unary operator -The unary ``-`` (minus) operator yields the negation of its numeric argument. +The unary ``-`` (minus) operator yields the negation of its numeric argument; the +operation can be overridden with the :meth:`__neg__` special method. .. index:: single: plus single: operator; + (plus) single: + (plus); unary operator -The unary ``+`` (plus) operator yields its numeric argument unchanged. +The unary ``+`` (plus) operator yields its numeric argument unchanged; the +operation can be overridden with the :meth:`__pos__` special method. .. index:: single: inversion @@ -1189,7 +1192,10 @@ The unary ``+`` (plus) operator yields its numeric argument unchanged. The unary ``~`` (invert) operator yields the bitwise inversion of its integer argument. The bitwise inversion of ``x`` is defined as ``-(x+1)``. It only -applies to integral numbers. +applies to integral numbers or to custom objects that override the +:meth:`__invert__` special method. + + .. index:: exception: TypeError @@ -1225,6 +1231,9 @@ the other must be a sequence. In the former case, the numbers are converted to a common type and then multiplied together. In the latter case, sequence repetition is performed; a negative repetition factor yields an empty sequence. +This operation can be customized using the special :meth:`__mul__` and +:meth:`__rmul__` methods. + .. index:: single: matrix multiplication operator: @ (at) @@ -1247,6 +1256,9 @@ integer; the result is that of mathematical division with the 'floor' function applied to the result. Division by zero raises the :exc:`ZeroDivisionError` exception. +This operation can be customized using the special :meth:`__div__` and +:meth:`__floordiv__` methods. + .. index:: single: modulo operator: % (percent) @@ -1270,6 +1282,8 @@ also overloaded by string objects to perform old-style string formatting (also known as interpolation). The syntax for string formatting is described in the Python Library Reference, section :ref:`old-string-formatting`. +The *modulo* operation can be customized using the special :meth:`__mod__` method. + The floor division operator, the modulo operator, and the :func:`divmod` function are not defined for complex numbers. Instead, convert to a floating point number using the :func:`abs` function if appropriate. @@ -1284,6 +1298,9 @@ must either both be numbers or both be sequences of the same type. In the former case, the numbers are converted to a common type and then added together. In the latter case, the sequences are concatenated. +This operation can be customized using the special :meth:`__add__` and +:meth:`__radd__` methods. + .. index:: single: subtraction single: operator; - (minus) @@ -1292,6 +1309,8 @@ In the latter case, the sequences are concatenated. The ``-`` (subtraction) operator yields the difference of its arguments. The numeric arguments are first converted to a common type. +This operation can be customized using the special :meth:`__sub__` method. + .. _shifting: @@ -1311,6 +1330,9 @@ The shifting operations have lower priority than the arithmetic operations: These operators accept integers as arguments. They shift the first argument to the left or right by the number of bits given by the second argument. +This operation can be customized using the special :meth:`__lshift__` and +:meth:`__rshift__` methods. + .. index:: exception: ValueError A right shift by *n* bits is defined as floor division by ``pow(2,n)``. A left @@ -1336,7 +1358,8 @@ Each of the three bitwise operations has a different priority level: operator: & (ampersand) The ``&`` operator yields the bitwise AND of its arguments, which must be -integers. +integers or one of them must be a custom object overriding :meth:`__and__` or +:meth:`__rand__` special methods. .. index:: pair: bitwise; xor @@ -1344,7 +1367,8 @@ integers. operator: ^ (caret) The ``^`` operator yields the bitwise XOR (exclusive OR) of its arguments, which -must be integers. +must be integers or one of them must be a custom object overriding :meth:`__xor__` or +:meth:`__rxor__` special methods. .. index:: pair: bitwise; or @@ -1352,7 +1376,8 @@ must be integers. operator: | (vertical bar) The ``|`` operator yields the bitwise (inclusive) OR of its arguments, which -must be integers. +must be integers or one of them must be a custom object overriding :meth:`__or__` or +:meth:`__ror__` special methods. .. _comparisons: @@ -1380,7 +1405,9 @@ in mathematics: comp_operator: "<" | ">" | "==" | ">=" | "<=" | "!=" : | "is" ["not"] | ["not"] "in" -Comparisons yield boolean values: ``True`` or ``False``. +Comparisons yield boolean values: ``True`` or ``False``. Custom +:dfn:`rich comparison methods` may return non-boolean values. In this case +Python will call :func:`bool` on such value in boolean contexts. .. index:: pair: chaining; comparisons