Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt

Use this file to discover all available pages before exploring further.

The @= operator is the augmented assignment operator for matrix multiplication in Python, introduced in Python 3.5 via PEP 465. It evaluates the matrix product of two objects and assigns the resulting value back to the left-hand operand. 
A @= B

​
Underlying Mechanics

When the Python interpreter encounters the @= operator, it attempts to perform an in-place operation by invoking specific magic methods (dunder methods) in a strict resolution order. The evaluation of A @= B follows these steps:
  1. __imatmul__ (In-place Matrix Multiplication): Python first checks if the left operand (A) implements the __imatmul__(self, other) method. If implemented, this method is executed. It is expected to modify the object in-place and return the mutated object, which is then bound back to the identifier A.
  2. Fallback to A @ B: If __imatmul__ is not implemented or returns NotImplemented, Python falls back to evaluating the standard matrix multiplication (A @ B) and assigns the newly created object back to A. This fallback adheres to Python’s standard binary operator resolution:
    • The Subclass Rule: If the right operand (B) is an instance of a strict subclass of the left operand’s (A) class, Python prioritizes the right operand’s reflected method. It will invoke B.__rmatmul__(A) before attempting A.__matmul__(B).
    • __matmul__ (Standard Matrix Multiplication): If the subclass rule does not apply, Python invokes A.__matmul__(B).
    • __rmatmul__ (Reflected Matrix Multiplication): If A does not implement __matmul__, or if A.__matmul__(B) returns NotImplemented, Python invokes B.__rmatmul__(A).
  3. TypeError: If none of these methods are implemented, or if all attempted methods return NotImplemented, Python raises a TypeError indicating unsupported operand types.

​
Implementation Syntax

To support the @= operator in custom classes, you must define the __imatmul__ method. If you want to support the fallback behavior, you should also define __matmul__ and __rmatmul__. 
class MatrixObject:
    def __init__(self, data):
        self.data = data

    def __imatmul__(self, other):
        if not isinstance(other, MatrixObject):
            return NotImplemented
        
        # Logic for in-place matrix multiplication goes here
        # Example mutates self.data directly
        self.data = self._compute_matrix_product(self.data, other.data)
        
        # Must return self for augmented assignment to work correctly
        return self

    def __matmul__(self, other):
        if not isinstance(other, MatrixObject):
            return NotImplemented
            
        # Logic for standard matrix multiplication
        new_data = self._compute_matrix_product(self.data, other.data)
        return MatrixObject(new_data)
        
    def _compute_matrix_product(self, data1, data2):
        # Internal computation logic
        pass


# Execution
X = MatrixObject(...)
Y = MatrixObject(...)

X @= Y  # Invokes X.__imatmul__(Y)

​
Type Support

The @= operator is not implemented by any of Python’s built-in scalar or collection types (such as int, float, list, or dict). Attempting to use @= on these standard types will result in a TypeError. The operator exists purely at the syntax level in standard Python to provide a standardized API for third-party numerical and scientific libraries, such as NumPy.
Master Python with Deep Grasping Methodology!Learn More