Implementing python **mul** for Custom Classes

In Python, the multiplication operator * is more than syntax. When you write a * b, the interpreter dispatches to the __mul__ method of a (or b via the reflected protocol). For built-in types like int and float, that method is implemented in C. For custom classes, you control the behavior by defining __mul__. This article explains how to implement python **mul** correctly, handle reflected operands, and avoid the pitfalls that lead to confusing errors.

The Role of __mul__ in Python's Data Model

Python's data model uses special methods, also called dunder methods, to define how objects behave with operators. __mul__ is the method behind the * operator. When the interpreter evaluates x * y, it first tries type(x).__mul__(x, y). If that method returns NotImplemented, Python then tries type(y).__rmul__(y, x) (the reflected version). If both return NotImplemented, a TypeError is raised.

This dispatch mechanism means that implementing __mul__ on a class affects not only how that class is multiplied but also how it participates in expressions with other types. A well-designed __mul__ should return a new instance of the class (or a compatible type) and should never mutate the operands.

Implementing __mul__ in a Custom Class

Consider a simple Vector class that stores numeric components. A natural multiplication operation is scalar multiplication, where each component is scaled by a number.

class Vector:
    def __init__(self, *components):
        self.components = tuple(components)

    def __mul__(self, scalar):
        if not isinstance(scalar, (int, float)):
            return NotImplemented
        return Vector(*(c * scalar for c in self.components))

    def __repr__(self):
        return f"Vector{self.components}"

Here, __mul__ checks that the right operand is a number. If it is not, it returns NotImplemented instead of raising an error immediately. This allows Python to give the other operand a chance to handle the operation. If the other operand also cannot handle it, Python raises a TypeError with a clear message.

The method returns a new Vector instance, leaving the original unchanged. This matches the expected behavior of multiplication for immutable-like types. If you want to support in-place multiplication, you would implement __imul__ separately.

Handling Different Operand Types

A single __mul__ method can support more than one type of right operand. For example, you might want to allow multiplying a Vector by another Vector of the same length, performing element-wise multiplication.

class Vector:
    # ... previous code ...

    def __mul__(self, other):
        if isinstance(other, (int, float)):
            return Vector(*(c * other for c in self.components))
        if isinstance(other, Vector) and len(other.components) == len(self.components):
            return Vector(*(a * b for a, b in zip(self.components, other.components)))
        return NotImplemented

This approach centralizes type checking in one place. When the types are incompatible, returning NotImplemented lets Python attempt the reflected operation, which is often the correct behavior. For instance, if you multiply an int by a Vector, the int's __mul__ does not know about Vector, so it returns NotImplemented. Python then calls Vector.__rmul__, which you must define to handle the reversed order.

Reflected Multiplication with __rmul__

When the left operand does not support multiplication with the right operand, Python tries the right operand's __rmul__. This is essential for commutative operations like scalar multiplication. Without __rmul__, 2 * vector would fail even though vector * 2 works.

class Vector:
    # ... previous code ...

    def __rmul__(self, scalar):
        return self.__mul__(scalar)

In this case, __rmul__ simply delegates to __mul__ because scalar multiplication is commutative. For non-commutative operations, you would need to implement the logic separately. Always return NotImplemented if the type is unsupported, even in __rmul__, to preserve the correct error behavior.

The following table summarizes the three related methods:

In-Place Multiplication with __imul__

In-place operators like *= are handled by __imul__. If you do not define __imul__, Python falls back to __mul__ and then assigns the result back to the variable. That is often acceptable, but it creates a new object. For mutable classes where you want to avoid allocation, implement __imul__ to modify the instance and return self.

class MutableVector:
    def __init__(self, *components):
        self.components = list(components)

    def __imul__(self, scalar):
        if not isinstance(scalar, (int, float)):
            return NotImplemented
        self.components = [c * scalar for c in self.components]
        return self

Note that __imul__ should return the modified object, not a new one. If you return a different object, Python will still assign that result to the variable, which can be surprising. Only use __imul__ when mutation is semantically meaningful and performance matters.

Common Mistakes and Edge Cases

One frequent mistake is raising TypeError directly inside __mul__ instead of returning NotImplemented. Doing so prevents Python from trying the reflected operation and can break expressions where the other operand knows how to handle the multiplication. Always return NotImplemented for unsupported types.

Another edge case involves equality and hashability. If you implement __mul__ and __eq__ but not __hash__, instances become unhashable. This is fine for mutable classes but can cause issues if you use them in sets or as dictionary keys. Decide whether your class should be immutable and implement __hash__ accordingly.

Also consider what happens when the other operand is a subclass. Python's dispatch rules give priority to the right operand's reflected method if it is a subclass of the left operand's type. This is the