Python魔术方法__rfloordiv__详解：整除反向运算符的分派机制与实战

这一篇继续聊 Python 3.12 魔术方法系列走到第 37 篇主角是__rfloordiv__。名字看着唬人翻译成大白话就是整除运算符//的“反向版本”。正常写a // bPython 优先让左侧的a去调用__floordiv__可一旦a是intb是你自己定义的类实例int根本不知道b是什么东西这时候就需要b站出来救场——用__rfloordiv__告诉解释器other // self该怎么算。这个机制几乎天天在用但很多人第一次写自定义类时都会被它绕晕。这篇文章适合正在系统学习魔术方法、或者想在自定义类型里做数学运算、封装量化计算、区间拆分等功能的开发者。我会把分派机制、方向陷阱、返回值规则讲透再用三个能直接跑的业务案例带你走一遍完整实现最后整理几个真实项目里最容易踩的坑。1. 先搞懂运算符的分派机制__rfloordiv__是谁在什么时机调用的1.1 从一次普通的a // b说起很多教程把__rfloordiv__简单解释成“处理右侧操作数”这个说法不算错但漏掉了关键细节。Python 解释器对二元运算符的处理有一套固定的查找顺序拿a // b来说完整流程是这样的先查type(a)有没有定义__floordiv__如果有就调用type(a).__floordiv__(a, b)得到一个结果如果这个结果不是NotImplemented直接返回并结束如果a没定义__floordiv__或者返回了NotImplemented就转去查type(b)有没有__rfloordiv__如果有调用type(b).__rfloordiv__(b, a)注意这里参数顺序反过来了如果两边都不支持抛出TypeError: unsupported operand type(s) for //: ...。我先把结论放前面__rfloordiv__(self, other)里的self永远是运算符右边的操作数other永远是左边的操作数方法体里要计算的其实是other // self。这个方向一旦搞反所有结果都会莫名其妙。用代码验证最直观。class Left: def __floordiv__(self, other): return Left.__floordiv__ class Right: def __rfloordiv__(self, other): return Right.__rfloordiv__ l Left() r Right() print(l // r) # 输出 Left.__floordiv__这个例子说明只要左侧类型把自己的__floordiv__正常执行了右侧的__rfloordiv__根本不会被调用。真正会触发反向方法的场景是左侧类型主动“让位”。class LeftGiveUp: def __floordiv__(self, other): return NotImplemented class RightTakeOver: def __rfloordiv__(self, other): return RightTakeOver handles it print(LeftGiveUp() // RightTakeOver())输出就是一个字符串RightTakeOver handles it。你甚至可以什么都不做只让左侧方法返回NotImplemented右侧就能接管整个运算。这也是为什么很多自定义数值类在和其他类型混合运算时会在关键位置返回NotImplemented而不是直接抛异常——它在给右侧类型留机会。1.2 一个关键字眼NotImplementedNotImplemented和NotImplementedError是两回事新手特别容易混淆。NotImplementedError是异常抛出去程序就崩了NotImplemented是一个单例对象用来告诉解释器“这个方法我处理不了你去试试对家”。它不是错误而是语言层面的“协商”机制。结合前面说的流程__rfloordiv__内部同样可以返回NotImplemented。比如右侧类只支持和整数做整除遇到字符串时就不该硬算而是返回NotImplemented让解释器继续往上抛或者最终报 TypeError。这样可以避免在方法里手动维护一套异常逻辑行为也更符合 Python 的惯例。class Step: def __init__(self, size): self.size size def __rfloordiv__(self, other): if isinstance(other, (int, float)): return other // self.size return NotImplemented上面这段代码里abc // Step(3)会得到干净的TypeError: unsupported operand type(s) for //: str and Step而不是自己抛一个奇怪异常。这种风格在标准库和成熟的第三方库里非常常见。1.3 Python 3.12 下行为有变化吗先给结论__rfloordiv__这套分派机制在 Python 3.8 到 3.12 之间基本稳定代码迁移到 3.12 一般不会因为反射方法的查找顺序而出问题。3.12 的改进更多体现在错误提示和类型系统上比如语法错误定位更准确、f-string 解析重写、支持新版泛型语法 PEP 695。真正涉及运算的地方还是老一套。不过有个细节值得注意在 Python 3.12 里如果自定义类的__rfloordiv__返回了错误类型比如返回字符串解释器给出的 TypeError 信息依然会带上两个操作数的类型名方便排查。我自己在写代码时经常利用这一点故意让它报错从错误消息里反推解释器到底尝试了哪些类型方法。这个方法后面会专门演示。还有一个容易被忽略的点__rfloordiv__并不只对//生效。标准库的operator.floordiv(a, b)底层走的也是同一个协议a // b这种增强赋值则对应__ifloordiv__它们之间有分工但也有交叉。理解了__rfloordiv__后面学__ifloordiv__、__rmod__、__rtruediv__都会轻松很多。2. 方向陷阱、返回值约定与三个必须牢记的规则2.1 self 和 other 的方向问题这是整个系列里出现频率最高的坑。__rfloordiv__(self, other)中self是右侧操作数other是左侧操作数方法体里要实现other // self的语义。我见过的错误代码十有八九是把self // other写在里面导致10 // obj最终算出来的是obj // 10结果完全不是一回事。一个记忆技巧反向方法的名字里有个r可以理解成 “right”。它是为右侧对象准备的所以self绑定右侧对象。在写方法体时先问自己一句用户写的是other // self我拿到了两个量哪个应该作为除数正常情况下self是自定义类的实例通常承载着“单位”“步长”“区间宽度”这类语义所以更合理的逻辑往往是other // self.value。class Step: def __init__(self, size): self.size size def __rfloordiv__(self, other): return other // self.size s Step(3) print(10 // s) # 3等价于 10 // 3一旦把self.size // other写进去输出就变成了 0而且不报错属于最难查的一类逻辑错误。2.2 返回值必须遵守的约定__rfloordiv__的返回值应该是一个数值类型最好是整数或浮点数。Python 不会强制你做类型转换但你返回的类型会直接成为表达式的最终结果。比如10 // Step(3)返回3类型是int如果other是浮点数10.5 // Step(3)就会返回3.0类型是float。这种隐式的类型转换不一定有问题但在做数值库时最好心里有数。更要命的是漏写return。一个没有return的方法会返回None如果这一步发生表达式会静默拿到None程序不报错后续计算直接炸成TypeError: unsupported operand type(s) for //: int and NoneType。这种错误从堆栈上看往往离真正出错的方法十万八千里排查起来特别耗时。class BadStep: def __init__(self, size): self.size size def __rfloordiv__(self, other): result other // self.size # 忘了 return result print(10 // BadStep(3)) # 不报错但值是 None空口无凭跑一下就明白了。2.3 负数与零整除的边界行为Python 的//执行的是向下取整而不是向零取整。7 // 3是 2-7 // 3是 -37 // -3也是 -3。如果你在__rfloordiv__内部图省事写成int(other / self.value)负数场景下就会出错因为int()是向零截断的-7 / 3 得到 -2.333截断成 -2跟-7 // 3的 -3 对不上。这算是我在实现自定义数值运算时踩过的最隐蔽的坑之一。正确处理方式很简单__rfloordiv__内部直接复用 Python 的//运算符让解释器自己处理取整逻辑不要用除法加int()手动截断。对于除零__rfloordiv__也没法豁免。如果self.size为 0other // 0会自然抛出ZeroDivisionError。我建议不要在这里拦截并返回什么特殊值让异常自然往外抛就好调用方才能第一时间发现问题。3. 实操三个能直接跑的业务案例3.1 案例一点数转手数的封装在量化交易或者行情计算里经常遇到“每个点对应多少钱”的概念。假设某个合约的点值是 500 元我想根据资金量快速算出能买多少个整点这时候自定义一个PointValue类很自然。class PointValue: def __init__(self, value_per_point): self.value_per_point value_per_point def __repr__(self): return fPointValue({self.value_per_point}) def __floordiv__(self, other): # self // other每个点 500分给 other 个单位 return self.value_per_point // other def __rfloordiv__(self, other): # other // self总资金 other 能拆成多少个整点 return other // self.value_per_point pv PointValue(500) print(1600 // pv) # 31600 元能覆盖 3 个整点 print(pv // 3) # 166500 元均分给 3 份 print(1050.0 // pv) # 2.0float 运算自动返回 float1600 // pv这个写法在没实现__rfloordiv__之前会直接报错因为int.__floordiv__根本不知道PointValue是什么。补上__rfloordiv__后表达式语义就很清楚了other是资金量self是点值结果是能买进的整数点数。这里我还故意演示了浮点数场景。1050.0 // pv会先走float.__floordiv__它发现对面是自定义对象就返回NotImplemented接着调用PointValue.__rfloordiv__内部执行1050.0 // 500结果是2.0。类型跟着左侧操作数走了这个行为在__floordiv__和__rfloordiv__里保持一致不会出现一边返回int一边返回float的割裂感。3.2 案例二K线周期与交易时段的整除换算再举个例子做行情分析时经常要把交易时段总分钟数换算成“多少根指定周期的 K 线”。例如一上午交易 180 分钟每根 30 分钟 K 线我们需要知道能组成 6 根。这种业务用普通函数写也够但封装成类以后代码的可读性会提升一个档次。class BarSize: def __init__(self, minutes): self.minutes minutes def __repr__(self): return fBarSize({self.minutes}min) def __floordiv__(self, other): # self // other给定周期分钟数等分成 other 分钟一段 return self.minutes // other def __rfloordiv__(self, other): # other // self总分钟数能切成多少根该周期的K线 return other // self.minutes bar BarSize(30) print(180 // bar) # 6 print(bar // 45) # 030 分钟段按 45 分钟切不够一根 print(75 // bar) # 275 分钟能覆盖 2 根 30 分钟K线这个案例和第一个本质上都是“单位换算”但业务语义完全不同。BarSize的__rfloordiv__回答的问题是“总量能容纳多少个单位”而__floordiv__回答的是“单位能等分成多少份”。两者方向相反用途不同必须在类里同时实现这样无论用户是把自定义对象写在左边还是右边表达式都能工作。我在写这类类时有一个习惯每个方法开头先用一行注释写明算子语义比如# other // self总分钟数能切成多少根该周期的K线。这种注释一开始觉得多余过三个月再看比任何文档都管用。3.3 案例三区间拆分的镜像实现第三个案例更贴近工程场景。假设在排产或者布局系统里有一个Segment类表示“一段固定长度”现在要计算一个总长度能容纳多少段以及一段本身能细分出多少个更小的段。class Segment: def __init__(self, length): self.length length def __repr__(self): return fSegment({self.length}) def __floordiv__(self, other): # self // other一段长度能切成多少个 other 长度的小段 if isinstance(other, Segment): return self.length // other.length if isinstance(other, (int, float)): return self.length // other return NotImplemented def __rfloordiv__(self, other): # other // self总长度 other 能容纳多少个 self 段 if isinstance(other, Segment): return other.length // self.length if isinstance(other, (int, float)): return other // self.length return NotImplemented seg Segment(7) print(27 // seg) # 327 能容纳 3 个 7 print(seg // 2) # 37 能切成 3 个 2 print(Segment(30) // seg) # 430 能容纳 4 个 7这个例子比前两个更进一步我在__floordiv__和__rfloordiv__里同时处理了Segment和普通数两种右侧类型并把处理不了的情况返回NotImplemented。当左侧和右侧都是Segment时它的查找过程是先调左侧Segment.__floordiv__内部做self.length // other.length正常返回 4右侧的__rfloordiv__根本不会被调用。这再一次验证了分派顺序左侧有能处理的方法右边就彻底没机会参与。3.4 用 operator 模块加速验证写完后想快速验证双向运算除了直接跑表达式外用operator.floordiv会更规范也更方便做参数化测试。import operator seg Segment(7) assert operator.floordiv(27, seg) 3 assert operator.floordiv(seg, 2) 3 assert operator.floordiv(Segment(30), seg) 4operator.floordiv(a, b)和a // b等价但它是一个普通函数能传入map、filter或者其他高阶函数里这在写测试用例时会方便很多。用 assert 把关键行为固化成测试后续改动类内部逻辑时一跑就知道有没有破坏契约。4. 常用组合与进阶玩法4.1 对称性设计成对实现才是完整方案很多人在类里实现了__floordiv__却忘了__rfloordiv__导致obj // 10能跑、10 // obj直接崩。反过来只实现__rfloordiv__又会导致常规方向不可用。规范的做法是成对实现并且保证两者语义一致。比如PointValue里pv // 3走__floordiv__1600 // pv走__rfloordiv__两者的核心运算其实都是“把value作为分子或分母去做整除”只是self和other的角色对调。如果内部业务逻辑复杂建议抽出私有方法_divide_unit(a, b)两个魔术方法都调它既减少重复代码也避免两边逻辑不一致。class PointValue: def __init__(self, value): self.value value def _divide_unit(self, numerator, denominator): # 统一的整除单元换算 return numerator // denominator def __floordiv__(self, other): return self._divide_unit(self.value, other) def __rfloordiv__(self, other): return self._divide_unit(other, self.value)4.2 与__ifloordiv__的配合a // b这种增强赋值对应的魔术方法是__ifloordiv__它和__floordiv__的调用时机不同。如果__ifloordiv__没有定义Python 会退回到普通的__floordiv__加赋值操作。对不可变类型来说这通常没问题对可变类型来说讲求效率的场景可以单独实现__ifloordiv__在原对象上修改并返回self。class MutableBox: def __init__(self, value): self.value value def __ifloordiv__(self, other): self.value // other return self def __floordiv__(self, other): return MutableBox(self.value // other) box MutableBox(10) box // 3 print(box.value) # 3不过要注意上下文__ifloordiv__真正发挥作用是在“左侧就是当前对象”的增强赋值场景它和__rfloordiv__是两个维度的方法一个管“就地更新”一个管“反向运算”并不冲突。4.3 继承场景下的反射陷阱如果子类没有实现__floordiv__会直接继承父类的方法但如果父类返回了NotImplemented子类即使想接管也可能在方法解析顺序上踩坑。class Base: def __floordiv__(self, other): return NotImplemented class Child(Base): def __rfloordiv__(self, other): return child rfloordiv c Child() print(c // 10) # 结果如何这里c // 10会调用Child继承自Base的__floordiv__它返回NotImplemented于是解释器转去查type(10)的__rfloordiv__而int没有针对Child的反向方法最终抛TypeError。Child.__rfloordiv__虽然是实现了但它是给10 // c这种方向准备的救不了c // 10。这提醒我们继承体系里写魔术方法时最好把成对方法放在同一个层级的类里并多做一次双向测试。5. 常见问题与排查技巧实录5.1 问题速查表现象可能原因解决办法10 // obj报 TypeError类里没定义__rfloordiv__或返回值不是数值成对实现__floordiv__与__rfloordiv__obj // 10正常但反向报错只实现了__floordiv__没实现__rfloordiv__补全反向方法反向计算得到None方法漏写 return检查所有分支都有return负数场景结果不对内部用int(other / x)截断改用other // x自定义对象和内置类型混算时静默返回错误结果方向写反把other // self写成了self // other用注释标明语义子类中定义的方法没被调用父类方法先接管且没有返回 NotImplemented在父类方法返回NotImplemented或重写方法这张表看起来简单每一条我都在真实代码里见过不止一次。特别是第二条很多人只写__floordiv__就觉得完事了等到项目里出现total // unit的形式才发现崩了。5.2 两行代码打印分派过程排查双向整除问题时最快的办法是在方法里插入print直接观察解释器到底调用了谁。class DebugStep: def __init__(self, size): self.size size def __floordiv__(self, other): print(f[__floordiv__] self{self!r}, other{other!r}) return self.size // other def __rfloordiv__(self, other): print(f[__rfloordiv__] self{self!r}, other{other!r}) return other // self.size print(10 // DebugStep(3)) print(DebugStep(3) // 10)输出会清楚显示第一个表达式走__rfloordiv__第二个走__floordiv__。方向是否搞错、参数顺序是否正确一目了然。这个问题排查完记得把 print 删掉或者加一个日志开关。5.3 用 NotImplemented 做协议探测有一种比较进阶的调试手法让自定义类的方法只打印日志并返回NotImplemented然后观察解释器接下来会做什么。这能帮你确认“对家是否真的会接管”。class Probe: def __floordiv__(self, other): print(Probe.__floordiv__ returns NotImplemented) return NotImplemented def __rfloordiv__(self, other): print(Probe.__rfloordiv__ returns NotImplemented) return NotImplemented try: Probe() // Probe() except TypeError as e: print(type(e).__name__, e)这种方式适合深入理解 CPython 的二元运算协议也适合在引入新依赖时快速判断某个第三方类型和你的类型到底谁先谁后。回头总结__rfloordiv__的本质就是给自定义类型一张“反向操作入场券”。它和__floordiv__一起构成了完整的整除语义闭环理解它的关键在于记住分派顺序、方向约定和NotImplemented的协商机制。我个人写代码时习惯把成对方法放在一起每个方法开头先写清楚other // self的语义注释然后统一用一个私有辅助方法处理核心换算最后用operator.floordiv写一组双向断言。这套流程帮我省掉了大量跟运算符相关的隐性 Bug也推荐你试一试。下一篇我会继续沿着算术运算家族的路线把其他反向运算符一并串起来聊。