怎么在Python自定义类中重载__mod__方法

阿麦
阿麦
发布时间:2026-11-19 | 5人浏览过
原创

详细讲解在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。

怎么在Python自定义类中重载__mod__方法
图 1:Python 解释器在求值 a % b 时的分派执行流程

二、重载 __mod__ 的具体实现步骤

在自定义类中重载 __mod__ 时,标准实现过程可以清晰地划分为四个阶段:声明方法签名、类型检查与值提取、模运算及除零防护、包装并返回新对象。

怎么在Python自定义类中重载__mod__方法
图 2:实现 __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
怎么在Python自定义类中重载__mod__方法
图 3:__mod__ 与 __rmod__ 的职责定位与协作关系

这种差异之所以关键,是因为内置类型(例如 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,这会掩盖上层调用中的逻辑缺陷。
怎么在Python自定义类中重载__mod__方法
图 4:重载 __mod__ 的关键法则与质量控制总结
相关专题:

本站声明

本文内容仅供参考,不代表本站观点。转载或引用请注明出处。如发现内容问题,请通过联系我们页面反馈。

Python 相关产品和应用

全部下载

专题列表