Python In-Place Subtraction Operator

Python provides the operator x -= y to subtract two objects in-place by calculating the difference x - y and assigning the result to the first operands variable name x. You can set up the in-place subtraction behavior for your own class by overriding the magic “dunder” method __isub__(self, other) in your class definition.

>>> x = 3
>>> x -= 2
>>> x

The expression x -= y is syntactical sugar for the longer-form x = x - y:

>>> x = 3
>>> x = x - 2
>>> x

Let’s explore some examples on different data types of the operands.

Integer Example

The -= operator on integer operands stores the mathematical difference of both operands in the left-hand operands’ variable name.

>>> x = 82
>>> x -= 40
>>> x

Float Example

If at least one of the operands is a float value, the result is also a float—float is infectious!

>>> x = 2
>>> x -= 10.0
>>> x

Set Example

If the operands are sets, the result of the in-place subtraction operation overwrites an existing set with the set difference operation:

>>> my_set = {'Alice', 'Bob', 'Carl'}
>>> my_set -= {1, 'Bob', 'Alice'}
>>> my_set

The in-place subtraction operator on sets doesn’t create a new set object but works on an existing set. Changing the set in-place for one variable x has side-effects. For instance, another variable my_set may point to the same object in memory that is updated through the use of in-place subtraction on any other variable pointing to that same object in memory.

>>> my_set = {'Alice', 'Bob', 'Carl'}
>>> x = my_set
>>> x -= {1, 'Bob', 'Alice'}
>>> x
>>> my_set

Incompatible Data Type

What if two operands have an incompatible data type—unlike floats and integers? For example, if you try to subtract a list from an integer variable?

>>> x = 4
>>> x -= [1, 2, 3]
Traceback (most recent call last):
  File "<pyshell#9>", line 1, in <module>
    x -= [1, 2, 3]
TypeError: unsupported operand type(s) for -=: 'int' and 'list'

The result of incompatible addition is a TypeError. You can fix it by using only compatible data types for the in-place addition operation.

Can you use the addition operator on custom objects? Yes!

Python In-Place Subtraction Magic Method

To use the in-place subtraction operator -= on custom objects, you need to define the __isub__() method (“dunder method”, “magic method”) that takes two arguments self and other, updates the first argument self with the result of the subtraction, and returns the updated object.

In the following code, you subtract two Data objects from each other by combining their contents:

class Data:

    def __init__(self, data): = data

    def __isub__(self, other): -=
        return self

x = Data(44)
y = Data(2)

x -= y
# 42

You can see that the content of the first operand is updated as a result of the in-place subtraction operation.

Python In-Place Operators

In-place assignment operators (also called compound assignment operators) perform an operation in-place on a variable provided as first operand. They overwrite the value of the first operand variable with the result of the operation when performing the operator without assignment. For example, x += 3 is the same as x = x + 3 of first calculating the result of x +3 and then assigning it to the variable x.

OperatorNameShort ExampleEquivalent Long Example
=In-place Assignmentx = 3
+=In-place Additionx += 3x = x + 3
-=In-place Subtractionx -= 3x = x - 3
*=In-place Multiplicationx *= 3x = x * 3
/=In-place Divisionx /= 3x = x / 3
%=In-place Modulox %= 3x = x % 3
//=In-place Integer Divisionx //= 3x = x // 3
**=In-place Powerx **= 3x = x ** 3
&=In-place Bitwise Andx &= 3x = x & 3
|=In-place Bitwise Orx |= 3x = x | 3
^=In-place Bitwise XORx ^= 3x = x ^ 3
>>=In-place Bitwise Shift Rightx >>= 3x = x >> 3
<<=In-place Bitwise Shift Leftx <<= 5x = x << 5