怎么在Python自定义类中重载__mod__方法
详细讲解在Python自定义类中重载__mod__方法的操作步骤、代码示例、类型检查机制、NotImplemented回退与__rmod__配合使用的最佳实践。
在 Python 中重载 __mod__ 方法,核心是在自定义类中定义 def __mod__(self, other): 函数,用来接管取模运算符 % 的计算逻辑。当自定义类的实例出现在 % 左侧时,Python 会自动调用该方法并传入右侧操作数;开发者在方法内部完成数值校验、边界检查和模运算后返回新实例,若遇到不支持的操作数类型则返回 NotImplemented。
一、__mod__ 的作用与调用原理
Python 的内置运算符均由魔术方法(Magic Methods)在底层驱动。当我们编写表达式 a % b 时,Python 解释器并不会直接强制执行底层的整数除法求余,而是按照既定的协议向对象请求计算结果。如果 a 是一个自定义类的实例,Python 优先寻找并执行 a.__mod__(b)。
理解重载机制的关键在于明白 Python 的协同调度过程。如果 __mod__ 发现传入的 other 并非预期类型,它不应直接抛出异常,而是应该返回特殊的单例对象 NotImplemented。这样 Python 解释器就会尝试反向调用右侧对象的 __rmod__ 方法。如果双方都无法处理,最终才会由解释器统一抛出 TypeError。
二、重载 __mod__ 的具体实现步骤
在自定义类中重载 __mod__ 时,标准实现过程可以清晰地划分为四个阶段:声明方法签名、类型检查与值提取、模运算及除零防护、包装并返回新对象。
1. 基础示例:角度类(Angle)的周期性取模
以表示几何角度的 Angle 类为例。角度天然具有 $0^\circ \sim 360^\circ$ 的周期性,对一个角度对象执行取模操作,可以得到其在特定分度下的余角。以下是完整的类定义代码:
class Angle:
def __init__(self, degrees: float):
self.degrees = float(degrees)
def __mod__(self, other):
# 1. 判断 other 是同一类实例还是常规数值
if isinstance(other, Angle):
divisor = other.degrees
elif isinstance(other, (int, float)):
divisor = float(other)
else:
# 2. 不支持的类型返回 NotImplemented,交给 Python 调度
return NotImplemented
# 3. 显式防范除以零
if divisor == 0:
raise ZeroDivisionError("Angle modulo by zero")
# 4. 计算余数并返回新的 Angle 实例
result = self.degrees % divisor
return Angle(result)
def __repr__(self):
return f"Angle({self.degrees:.2f}°)"
2. 运行与验证
在 Python 交互环境或脚本中执行以下测试:
a1 = Angle(375)
# 对整数取模
r1 = a1 % 360
print("r1:", r1)
# 对另一个 Angle 对象取模
a2 = Angle(90)
r2 = a1 % a2
print("r2:", r2)
终端示例输出:
r1: Angle(15.00°)
r2: Angle(15.00°)
可以看到,无论是原生整数还是同类的 Angle 实例,__mod__ 均能正常提取数值并返回全新的 Angle 对象,且原始对象 a1 的属性保持不变。
三、关键机制对比:__mod__ 与 __rmod__
在实现自定义数学类时,一个常见的疑问是:为什么实现了 __mod__ 后,Angle(375) % 180 可以正常运行,而 180 % Angle(375) 却可能报错?这就涉及到 __mod__ 与反向运算符 __rmod__ 的职责划分。
| 对比维度 | __mod__(self, other) | __rmod__(self, other) |
|---|---|---|
| 触发条件 | 当自定义类实例处于 % 的左侧时触发 |
当自定义类实例处于 % 的右侧且左侧无法处理时触发 |
| 调度优先级 | 第一优先级(左操作数主导) | 第二优先级(备用回退机制) |
| self 的角色 | self 为被除数(分子) |
self 为除数(分母) |
| 典型表达式 | custom_obj % 10 |
10 % custom_obj |
这种差异之所以关键,是因为内置类型(例如 int 和 float)并不认识我们的自定义类。当执行 100 % angle 时,int.__mod__ 发现右侧是未知的 Angle 类型,便返回 NotImplemented。此时,只有在 Angle 类中定义了 __rmod__,Python 才能继续调用 angle.__rmod__(100) 完成运算;否则会直接报 TypeError: unsupported operand type(s) for %。
四、完整实战:支持双向取模的健壮自定义类
为了让自定义类具备工业级的健壮性,通常建议同时实现 __mod__、__rmod__ 以及原地取模 __imod__,并结合类型约束与异常保护。下面给出一个生产可用的 Duration(时间跨度)类示例:
class Duration:
"""表示以秒为单位的时间跨度对象"""
def __init__(self, seconds: int):
if not isinstance(seconds, (int, float)):
raise TypeError("seconds 必须是数值类型")
self.seconds = int(seconds)
def __mod__(self, other):
# 提取操作数
if isinstance(other, Duration):
divisor = other.seconds
elif isinstance(other, (int, float)):
divisor = int(other)
else:
return NotImplemented
if divisor == 0:
raise ZeroDivisionError("Duration modulo by zero")
return Duration(self.seconds % divisor)
def __rmod__(self, other):
# 当执行 other % self 时触发
if isinstance(other, (int, float)):
if self.seconds == 0:
raise ZeroDivisionError("Duration modulo by zero")
return Duration(int(other) % self.seconds)
return NotImplemented
def __imod__(self, other):
# 支持原地赋值 %=
result = self.__mod__(other)
if result is NotImplemented:
return NotImplemented
self.seconds = result.seconds
return self
def __eq__(self, other):
if isinstance(other, Duration):
return self.seconds == other.seconds
return False
def __repr__(self):
return f"Duration({self.seconds}s)"
综合测试用例
d1 = Duration(3665) # 1小时1分5秒
# 1. 正向取模:计算去除整小时(3600秒)后的剩余秒数
r_forward = d1 % 3600
print("正向取模结果:", r_forward)
# 2. 对象间取模
d_hour = Duration(3600)
r_obj = d1 % d_hour
print("对象间取模结果:", r_obj)
# 3. 反向取模:原生数值在左侧
r_reverse = 5000 % d_hour
print("反向取模结果:", r_reverse)
# 4. 原地取模
d_inplace = Duration(125)
d_inplace %= 60
print("原地取模结果:", d_inplace)
示例输出:
正向取模结果: Duration(65s)
对象间取模结果: Duration(65s)
反向取模结果: Duration(1400s)
原地取模结果: Duration(5s)
五、核心注意事项与避坑指南
重载 __mod__ 虽然语法简单,但在工程实践中有几个必须注意的细节:
严禁在类型不符时直接 raise TypeError:必须返回 NotImplemented。这是初学者最容易犯的错误。一旦显式抛出 TypeError,Python 解释器会立即中断执行,导致右侧对象的 __rmod__ 彻底失去执行机会,破坏了多态与协同计算协议。
- 保持不可变语义:
__mod__属于二元运算符,应当始终返回一个全新构建的对象,绝不能就地修改self的内部数据。若需要原地修改语义,应单独重载__imod__。 - 负数取模的数学定义:Python 的
%遵循“向下取整(Floor Division)”原则,即结果的符号与除数(右操作数)相同。例如-5 % 3在 Python 中等于1,而不是-2。在编写自定义类的算法逻辑时,应确保内部数值与 Python 原生规则保持一致。 - 除以零异常必须抛出:当右操作数或提取到的值为
0时,必须及时引发ZeroDivisionError,不要试图静默返回 0 或None,这会掩盖上层调用中的逻辑缺陷。
免责声明:本文内容仅供参考,不代表本站观点。转载或引用请注明出处。









