本文详解如何在 Python 自定义类（如四元数 Quat）中正确实现 __mul__ 运算符重载，重点指出因命名错误（如 ___mul__）导致“unsupported operand type”异常的典型问题，并提供可运行示例、调试技巧与最佳实践。
本文详解如何在 python 自定义类（如四元数 quat）中正确实现 `__mul__` 运算符重载，重点指出因命名错误（如 `___mul__`）导致“unsupported operand type”异常的典型问题，并提供可运行示例、调试技巧与最佳实践。
在 Python 中，为自定义类支持链式乘法运算（如 a * b * c），必须正确定义魔术方法 __mul__。然而，一个极其常见却难以察觉的错误是——方法名拼写错误。例如，在提供的四元数（Quat）实现中，作者将方法误写为 ___mul__（三个下划线），而 Python 仅识别标准双下划线形式 __mul__。由于该方法未被注册为乘法操作符处理器，解释器无法找到对应逻辑，最终抛出 TypeError: unsupported operand type(s) for *: 'Quat' and 'Quat'。
下面是一个修复后的完整、可运行的 Quat 类核心片段（基于原代码精简优化）：
import math
from typing import Union
class Vec3:
def __init__(self, x: float, y: float, z: float):
self.x, self.y, self.z = x, y, z
def dot(self, other: 'Vec3') -> float:
return self.x * other.x + self.y * other.y + self.z * other.z
def cross(self, other: 'Vec3') -> 'Vec3':
return Vec3(
self.y * other.z - self.z * other.y,
self.z * other.x - self.x * other.z,
self.x * other.y - self.y * other.x
)
def is_zero(self) -> bool:
return abs(self.x) < 1e-9 and abs(self.y) < 1e-9 and abs(self.z) < 1e-9
def normalised(self) -> 'Vec3':
mag = math.sqrt(self.dot(self))
if mag < 1e-9:
return Vec3(1.0, 0.0, 0.0)
return Vec3(self.x / mag, self.y / mag, self.z / mag)
class Quat:
def __init__(self, w: float, x: float, y: float, z: float):
self.w, self.x, self.y, self.z = w, x, y, z
@classmethod
def from_axis_angle(cls, axis: Vec3 = Vec3(1.0, 0.0, 0.0), angle: float = 0.0):
half = angle * 0.5
s = math.sin(half)
return cls(math.cos(half), axis.x * s, axis.y * s, axis.z * s)
# ✅ 正确：双下划线，方法名严格为 __mul__
def __mul__(self, rhs: 'Quat') -> 'Quat':
lhs_vec = Vec3(self.x, self.y, self.z)
rhs_vec = Vec3(rhs.x, rhs.y, rhs.z)
w = self.w * rhs.w - lhs_vec.dot(rhs_vec)
xyz = (self.w * rhs_vec) + (rhs.w * lhs_vec) + lhs_vec.cross(rhs_vec)
return Quat(w, xyz.x, xyz.y, xyz.z)
# ✅ 可选：实现 __rmul__ 以支持标量左乘（如 2.0 * quat），但非必需
def __rmul__(self, lhs: Union[float, int]) -> 'Quat':
if isinstance(lhs, (int, float)):
return Quat(lhs * self.w, lhs * self.x, lhs * self.y, lhs * self.z)
return NotImplemented
def __repr__(self) -> str:
return f"Quat({self.w:.3f}, {self.x:.3f}, {self.y:.3f}, {self.z:.3f})"现在可安全执行链式乘法：
macOS UI 自动化技能包 —— 用 Python 控制你的 Mac
下载
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
q1 = Quat.from_axis_angle(Vec3(0, 1, 0), math.pi / 2) q2 = Quat.from_axis_angle(Vec3(1, 0, 0), math.pi / 3) q3 = Quat.from_axis_angle(Vec3(0, 0, 1), math.pi / 4) result = q1 * q2 * q3 # ✅ 成功：调用 __mul__ 两次 print(result) # 输出类似：Quat(0.383, 0.637, 0.555, 0.378)
⚠️ 关键注意事项：
立即学习“Python免费学习笔记（深入）”；
- 命名必须精确：__mul__ 是唯一有效的魔术方法名；___mul__、__mul_、mul 等均无效，且不会报错（仅静默忽略），极易引发运行时异常。
- 返回类型需一致：__mul__ 应返回同类型实例（如 Quat），否则后续链式调用会失败（例如返回 None 或 float 将中断 * 链）。
- __rmul__ 仅在左操作数不支持时触发：若需支持 float * Quat，应实现 __rmul__；但 Quat * Quat 始终优先调用左侧对象的 __mul__。
- 调试建议：使用 dir(Quat()) 检查是否包含 '__mul__'；或在方法内添加 print("in __mul__") 验证是否被调用。
总结：运算符重载的核心在于严格遵循 Python 魔术方法命名规范。一次多余的下划线，就足以让精心设计的数学逻辑失效。养成检查 __dunder__ 方法拼写的习惯，并结合 dir() 和简单测试用例验证，是编写健壮数值类库的必备素养。
