在 Python 的魔法方法Magic Methods列表里__lshift__属于那种平时不常被点名、一旦被点名就会让代码风格完全变样的方法。它对应的是位运算里的左移操作符但真正让人兴奋的地方不在于整数位移而在于你完全可以让任意自定义类型在左边做自己的事。这个系列走到第 50 个魔法方法刚好可以用 Python 3.12 的语法环境把__lshift__的前因后果一次聊透。不管你是刚接触 Python 的自学开发者还是已经在维护开源库的资深玩家这篇文章都值得看到最后。我会从操作符查找顺序讲到__rlshift__和__ilshift__再给你两个可以直接抄的实战类最后把我在真实代码里踩过的坑整理成排查清单。你不需要死记硬背只需要理解一个核心结论从来不只是“把二进制位往左挪”它是 Python 留给每个类的一扇门。1. 从一行a b说起操作符怎么变成魔法方法1.1 一条表达式背后的完整调用链当我们把任意对象放在左边解释器并不会真的检查它是不是整数。Python 的二进制运算符都是靠魔法方法分发的a b在 Python 3.12 里的标准行为是先尝试调用type(a).__lshift__(a, b)也就是a.__lshift__(b)。这里有个关键点特殊方法的查找是基于类型的而不是基于实例。你如果给某个对象动态绑定一个__lshift__属性解释器不会理它。魔法方法必须定义在类本体上这一点和普通属性访问完全不同也是很多新手第一次被绕晕的地方。举个最直白的例子class Demo: def __lshift__(self, other): return f{other} 被塞进了左边 d Demo() print(d 数据)这段代码完全合法输出 “数据 被塞进了左边”。在这个类里不代表位移而是代表你自己定义的任何行为。int类型的仍然是位移自定义类型则开启自己的语义。整个操作符重载体系的基础就是解释器不判断语义它只负责把表达式分发到对应的魔法方法。1.2 Python 3.12 里为什么还要专门研究它Python 3.12 并没有为二进制运算魔法方法引入新的查找规则数据模型文档里的分发顺序和 3.10、3.11 基本保持一致。那为什么还要单独讲__lshift__因为很多第三方库已经把它当成一套隐形的 DSL 入口。比如并发库里用task_queue job表示“把任务丢进队列”日志库用logger message表示“写一条日志”硬件模拟库用register bit表示“把 bit 移入寄存器”。这些写法的灵感或多或少来自 C 的 iostream 和 shell 里的重定向符号。你在阅读这类库的源码时如果不懂__lshift__看到obj something第一反应是“这什么鬼”但一旦理解了就会觉得这种 API 非常自然。所以我给这篇文章定的目标是不只讲清楚__lshift__怎么用还要讲清楚它跟__rlshift__、__ilshift__的配合关系。因为真正会写出优雅代码的人往往不是只定义一个方法而是把三种方法放在一起考虑。2.__lshift__的两个搭档__rlshift__与__ilshift__2.1 三者的签名和职责一个完整的左移运算符体系通常涉及三个魔法方法它们的职责完全不同方法对应表达式职责__lshift__(self, other)a b左操作数处理右操作数__rlshift__(self, other)b a右操作数反向处理左操作数在左侧不支持时被调用__ilshift__(self, other)a b原地左移赋值通常用于修改对象自身很多教程只提__lshift__不提后面两个。但在实际使用中__rlshift__往往是让 API 变得更顺手的关键。比如你想让用户既可以写pipeline data也可以写data pipeline如果没有__rlshift__后一种写法就会直接抛出一个看不懂的 TypeError。2.2 完整查找顺序与代码示例对于a bPython 的解释顺序大致是这样的看type(a)有没有__lshift__有就调用看返回结果。如果a.__lshift__(b)返回NotImplemented解释器再看type(b)有没有__rlshift__有就调用b.__rlshift__(a)。如果两边都不支持或者都返回NotImplemented最终抛出TypeError: unsupported operand type(s) for 。这里的“反向”很奇怪但逻辑其实很直接左边对象说“我搞不定”右边对象就得接过这个烫手山芋。我们用一个Box类来演示class Box: def __init__(self): self.items [] def __lshift__(self, other): self.items.append(other) return self def __rlshift__(self, other): return self.__lshift__(other) b Box() b left chained right b print(b.items)注意最后一行right b。字符串类型没有__lshift__方法Python 尝试完左边之后发现Box实现了__rlshift__于是把字符串交了过来。最终Box会得到三个元素链式调用也没有断。2.3 NotImplemented 不抛异常在魔法方法里返回NotImplemented是一种约定表示“我不支持这种操作”。它跟NotImplementedError完全是两回事NotImplemented是一个单例值会让解释器继续尝试反射方法NotImplementedError是异常一旦抛出就会中断程序。我遇到过不少同事把这两个搞混在__lshift__里写了raise NotImplementedError结果明明想让 Python 去尝试右侧对象的__rlshift__却被异常直接打断。正确的写法是def __lshift__(self, other): if isinstance(other, int): return self.value other return NotImplemented如果你只是写一个演示类不返回东西Python 会把None当成运算结果。这在链式调用里非常危险后面马上会讲到。3. 实战把改造成数据的入站口3.1 适用场景任务队列与日志管道我最推荐的__lshift__实践场景是把它定义成一个“入站口”。这里的语义可以类比成水流进管道pipeline item意思是“把 item 推入 pipeline”。对于日志系统、任务队列、事件总线这类组件这种写法比调用push()或submit()更短也更直观。不过直接使用也意味着使用者必须熟悉这个约定。如果你在一个团队里维护公共库我建议先通过代码评审确认大家都能接受再放进正式 API。否则可能变成“只有作者看得懂”的语法糖。3.2 一个可以直接抄的 Pipeline下面这个类实现了一个非常小的数据管道支持传入 handler 消费每条数据也支持先攒在缓冲区里统一处理class Pipeline: def __init__(self, handlerNone): self._handler handler self._pending [] def __lshift__(self, item): if self._handler is not None: self._handler(item) else: self._pending.append(item) return self def __rlshift__(self, item): return self.__lshift__(item) def drain(self): pending, self._pending self._pending, [] for item in pending: if self._handler: self._handler(item) def handle(item): print(freceive: {item}) pipeline Pipeline(handle) pipeline {event: login} [1, 2, 3] queue Pipeline() queue first second queue.drain()这段代码里的pipeline.__lshift__返回self所以pipeline a b c可以一路链下去。如果你忘了返回self第一个的返回值就成了None下一轮解释器只能去None上找__lshift__最终抛出的错误会让排查的人一头雾水。3.3 为什么还要补一个__rlshift__在 3.2 的Pipeline里正常链式调用的左边永远是pipeline对象__lshift__就够用了。但如果你希望 API 更灵活允许用户把pipeline放在右边比如log_content pipeline就必须补上__rlshift__。__rlshift__本质上是对“左侧类型无法处理”的兜底。我在项目里见过一个反例只实现了__lshift__结果用户顺手写了一句prefix logger直接得到TypeError。加上__rlshift__以后这个错误就消失了代码也更符合直觉。代价是你要额外考虑这种“反向推入”是否合理越灵活的 API 越需要清晰的文档约束。4. 实战位运算语义的移位寄存器4.1 ShiftRegister 设计最原始的语义还是位运算里的左移。如果你要写硬件模拟、协议解析或者二进制流处理可以让移动的“位”累加到一个寄存器里。下面这个类把“移入一位”设计成了register 0/1class ShiftRegister: def __init__(self, width8): self.width width self.value 0 def __lshift__(self, bit): bit 1 if bit else 0 self.value ((self.value 1) | bit) ((1 self.width) - 1) return self def __ilshift__(self, bit): return self.__lshift__(bit) def __repr__(self): return fShiftRegister(width{self.width}, value0b{self.value:0{self.width}b}) sr ShiftRegister(8) sr 1 0 1 print(sr)运行结果里value会变成0b00000101。从左往右推入的三个位最终按顺序落到了寄存器里。这和物理移位寄存器的行为一模一样的直觉语义得到了最大程度的保留。这个例子里还实现了__ilshift__所以sr 1也会原地修改寄存器。如果你不加__ilshift__sr 1会退化成先算sr 1再赋值也算能用但少了一层“原地修改”的语义表达。4.2 可变与不可变两种风格上面是可变版本每次都修改同一个对象。还有一种更接近整数风格的不可变版本每次返回一个新对象class ShiftRegisterImmutable: def __init__(self, width8, value0): self.width width self.value value def __lshift__(self, bit): bit 1 if bit else 0 new_value ((self.value 1) | bit) ((1 self.width) - 1) return ShiftRegisterImmutable(self.width, new_value) def __repr__(self): return fShiftRegisterImmutable(width{self.width}, value0b{self.value:0{self.width}b})不可变版本适合在函数式风格的代码里使用缺点是不能直接链式修改同一变量。拿sr sr 1 0 1来写虽然多敲了几个字符但副作用更可控。我的建议是如果你的类本身就是容器或者状态机用可变版本如果你的类表示的是一个数值、一个位集合优先用不可变版本。5. 常见问题排查与避坑清单5.1 症状、原因和解决方案速查表我在调试这类魔法方法时常用的排查表大概是这样的症状可能原因解决思路NoneType没有__lshift____lshift__忘记返回self或新对象在方法末尾明确return selfunsupported operand type(s) for 左侧不支持右侧没有__rlshift__在右侧类里补__rlshift____lshift__里抛了NotImplementedError把NotImplementedError和NotImplemented混淆返回NotImplemented而不是抛异常a b的结果莫名其妙是None__lshift__没有return补上返回语句a b之后a变成None__ilshift__没有返回新对象或self原地修改后return self链式调用时第二个操作符报错第一个__lshift__返回了错误类型确认返回类型与左操作数兼容这张表覆盖了我见过的绝大多数问题。尤其是第二种它特别隐蔽左侧是内置类型int右侧是你自己写的类结果int.__lshift__一碰到不认识的类型就返回NotImplemented于是你的类必须接住__rlshift__这个球。如果只看报错信息你完全想不到问题出在自己类里少了一个方法。5.2 两个经常被忽略的底层细节第一个细节是特殊方法查找不看实例。也就是说你不能在运行时给某个实例临时塞一个__lshift__属性来让运算符生效。魔法方法必须在类定义时出现在type上这是 Python 解释器层面的优化和约定。想绕过它只能创建新的子类或动态生成新类。第二个细节是operator.lshift可以帮你做更干净的调试。operator.lshift(a, b)和a b等价但它是一个普通函数可以包进print或者inspect。当你怀疑运算符分发有问题时直接跑一下import operator print(operator.lshift(my_obj, 2))如果这一行能跑通说明__lshift__本身没问题问题大概率出在类型查找顺序或者返回值上。这个技巧在排查复杂类层次时非常好用比在表达式外面套try/except更直接。6. 我的实操建议什么时候值得用__lshift__6.1 适合与不适合的场景对照__lshift__是一种非常强的表达工具但越强的工具越需要克制。我自己的判断标准很简单如果你能用普通方法名把意图表达得更清楚就不要强行用运算符如果这个运算符在你们的领域里已经有了稳定语义就可以放心用。场景建议任务/日志管道可以用表示“推入”语义清晰硬件模拟/寄存器可以用表示“移入”保留位移含义只是想让 API 少几个字不推荐方法名更安全面向新人的公共库要慎重尽量同时保留.push()与位运算无关的纯业务逻辑避免使用容易让人误解除了这张表我还会在类定义旁边写清楚每个魔法方法到底承诺了什么。比如__lshift__是修改自身还是返回新对象链式调用是否保证返回同一种类型这些细节如果不在文档里写明使用者只能靠猜。6.2 实践经验我在自己的一个小型任务调度器里曾经想把submit(task)直接改成task_queue task。代码确实短了但团队里有人看到task job的时候完全分不清是“提交任务”还是“位移”。后来我保留了submit()方法同时让成为它的语法糖入口。这样一来熟悉运算符的人可以写得更快不熟悉的人也有一个安全的显式方法可以依赖。最后再分享一个小技巧给自己类加魔法方法时最好顺手写一个冒烟测试把__lshift__、__rlshift__、__ilshift__三个方向各覆盖一次。别小看这个测试我踩过几次坑之后发现很多看起来“玄学”的运算符问题其实都是因为只测了最舒服的那条调用路径忘记了反向和原地赋值也会被解释器触发。弄清楚这三兄弟你的 Python 3.12 代码就能在上玩出真正顺手的花样。 Python魔法方法__lshift__：操作符重载实战与避坑指南
在 Python 的魔法方法Magic Methods列表里__lshift__属于那种平时不常被点名、一旦被点名就会让代码风格完全变样的方法。它对应的是位运算里的左移操作符但真正让人兴奋的地方不在于整数位移而在于你完全可以让任意自定义类型在左边做自己的事。这个系列走到第 50 个魔法方法刚好可以用 Python 3.12 的语法环境把__lshift__的前因后果一次聊透。不管你是刚接触 Python 的自学开发者还是已经在维护开源库的资深玩家这篇文章都值得看到最后。我会从操作符查找顺序讲到__rlshift__和__ilshift__再给你两个可以直接抄的实战类最后把我在真实代码里踩过的坑整理成排查清单。你不需要死记硬背只需要理解一个核心结论从来不只是“把二进制位往左挪”它是 Python 留给每个类的一扇门。1. 从一行a b说起操作符怎么变成魔法方法1.1 一条表达式背后的完整调用链当我们把任意对象放在左边解释器并不会真的检查它是不是整数。Python 的二进制运算符都是靠魔法方法分发的a b在 Python 3.12 里的标准行为是先尝试调用type(a).__lshift__(a, b)也就是a.__lshift__(b)。这里有个关键点特殊方法的查找是基于类型的而不是基于实例。你如果给某个对象动态绑定一个__lshift__属性解释器不会理它。魔法方法必须定义在类本体上这一点和普通属性访问完全不同也是很多新手第一次被绕晕的地方。举个最直白的例子class Demo: def __lshift__(self, other): return f{other} 被塞进了左边 d Demo() print(d 数据)这段代码完全合法输出 “数据 被塞进了左边”。在这个类里不代表位移而是代表你自己定义的任何行为。int类型的仍然是位移自定义类型则开启自己的语义。整个操作符重载体系的基础就是解释器不判断语义它只负责把表达式分发到对应的魔法方法。1.2 Python 3.12 里为什么还要专门研究它Python 3.12 并没有为二进制运算魔法方法引入新的查找规则数据模型文档里的分发顺序和 3.10、3.11 基本保持一致。那为什么还要单独讲__lshift__因为很多第三方库已经把它当成一套隐形的 DSL 入口。比如并发库里用task_queue job表示“把任务丢进队列”日志库用logger message表示“写一条日志”硬件模拟库用register bit表示“把 bit 移入寄存器”。这些写法的灵感或多或少来自 C 的 iostream 和 shell 里的重定向符号。你在阅读这类库的源码时如果不懂__lshift__看到obj something第一反应是“这什么鬼”但一旦理解了就会觉得这种 API 非常自然。所以我给这篇文章定的目标是不只讲清楚__lshift__怎么用还要讲清楚它跟__rlshift__、__ilshift__的配合关系。因为真正会写出优雅代码的人往往不是只定义一个方法而是把三种方法放在一起考虑。2.__lshift__的两个搭档__rlshift__与__ilshift__2.1 三者的签名和职责一个完整的左移运算符体系通常涉及三个魔法方法它们的职责完全不同方法对应表达式职责__lshift__(self, other)a b左操作数处理右操作数__rlshift__(self, other)b a右操作数反向处理左操作数在左侧不支持时被调用__ilshift__(self, other)a b原地左移赋值通常用于修改对象自身很多教程只提__lshift__不提后面两个。但在实际使用中__rlshift__往往是让 API 变得更顺手的关键。比如你想让用户既可以写pipeline data也可以写data pipeline如果没有__rlshift__后一种写法就会直接抛出一个看不懂的 TypeError。2.2 完整查找顺序与代码示例对于a bPython 的解释顺序大致是这样的看type(a)有没有__lshift__有就调用看返回结果。如果a.__lshift__(b)返回NotImplemented解释器再看type(b)有没有__rlshift__有就调用b.__rlshift__(a)。如果两边都不支持或者都返回NotImplemented最终抛出TypeError: unsupported operand type(s) for 。这里的“反向”很奇怪但逻辑其实很直接左边对象说“我搞不定”右边对象就得接过这个烫手山芋。我们用一个Box类来演示class Box: def __init__(self): self.items [] def __lshift__(self, other): self.items.append(other) return self def __rlshift__(self, other): return self.__lshift__(other) b Box() b left chained right b print(b.items)注意最后一行right b。字符串类型没有__lshift__方法Python 尝试完左边之后发现Box实现了__rlshift__于是把字符串交了过来。最终Box会得到三个元素链式调用也没有断。2.3 NotImplemented 不抛异常在魔法方法里返回NotImplemented是一种约定表示“我不支持这种操作”。它跟NotImplementedError完全是两回事NotImplemented是一个单例值会让解释器继续尝试反射方法NotImplementedError是异常一旦抛出就会中断程序。我遇到过不少同事把这两个搞混在__lshift__里写了raise NotImplementedError结果明明想让 Python 去尝试右侧对象的__rlshift__却被异常直接打断。正确的写法是def __lshift__(self, other): if isinstance(other, int): return self.value other return NotImplemented如果你只是写一个演示类不返回东西Python 会把None当成运算结果。这在链式调用里非常危险后面马上会讲到。3. 实战把改造成数据的入站口3.1 适用场景任务队列与日志管道我最推荐的__lshift__实践场景是把它定义成一个“入站口”。这里的语义可以类比成水流进管道pipeline item意思是“把 item 推入 pipeline”。对于日志系统、任务队列、事件总线这类组件这种写法比调用push()或submit()更短也更直观。不过直接使用也意味着使用者必须熟悉这个约定。如果你在一个团队里维护公共库我建议先通过代码评审确认大家都能接受再放进正式 API。否则可能变成“只有作者看得懂”的语法糖。3.2 一个可以直接抄的 Pipeline下面这个类实现了一个非常小的数据管道支持传入 handler 消费每条数据也支持先攒在缓冲区里统一处理class Pipeline: def __init__(self, handlerNone): self._handler handler self._pending [] def __lshift__(self, item): if self._handler is not None: self._handler(item) else: self._pending.append(item) return self def __rlshift__(self, item): return self.__lshift__(item) def drain(self): pending, self._pending self._pending, [] for item in pending: if self._handler: self._handler(item) def handle(item): print(freceive: {item}) pipeline Pipeline(handle) pipeline {event: login} [1, 2, 3] queue Pipeline() queue first second queue.drain()这段代码里的pipeline.__lshift__返回self所以pipeline a b c可以一路链下去。如果你忘了返回self第一个的返回值就成了None下一轮解释器只能去None上找__lshift__最终抛出的错误会让排查的人一头雾水。3.3 为什么还要补一个__rlshift__在 3.2 的Pipeline里正常链式调用的左边永远是pipeline对象__lshift__就够用了。但如果你希望 API 更灵活允许用户把pipeline放在右边比如log_content pipeline就必须补上__rlshift__。__rlshift__本质上是对“左侧类型无法处理”的兜底。我在项目里见过一个反例只实现了__lshift__结果用户顺手写了一句prefix logger直接得到TypeError。加上__rlshift__以后这个错误就消失了代码也更符合直觉。代价是你要额外考虑这种“反向推入”是否合理越灵活的 API 越需要清晰的文档约束。4. 实战位运算语义的移位寄存器4.1 ShiftRegister 设计最原始的语义还是位运算里的左移。如果你要写硬件模拟、协议解析或者二进制流处理可以让移动的“位”累加到一个寄存器里。下面这个类把“移入一位”设计成了register 0/1class ShiftRegister: def __init__(self, width8): self.width width self.value 0 def __lshift__(self, bit): bit 1 if bit else 0 self.value ((self.value 1) | bit) ((1 self.width) - 1) return self def __ilshift__(self, bit): return self.__lshift__(bit) def __repr__(self): return fShiftRegister(width{self.width}, value0b{self.value:0{self.width}b}) sr ShiftRegister(8) sr 1 0 1 print(sr)运行结果里value会变成0b00000101。从左往右推入的三个位最终按顺序落到了寄存器里。这和物理移位寄存器的行为一模一样的直觉语义得到了最大程度的保留。这个例子里还实现了__ilshift__所以sr 1也会原地修改寄存器。如果你不加__ilshift__sr 1会退化成先算sr 1再赋值也算能用但少了一层“原地修改”的语义表达。4.2 可变与不可变两种风格上面是可变版本每次都修改同一个对象。还有一种更接近整数风格的不可变版本每次返回一个新对象class ShiftRegisterImmutable: def __init__(self, width8, value0): self.width width self.value value def __lshift__(self, bit): bit 1 if bit else 0 new_value ((self.value 1) | bit) ((1 self.width) - 1) return ShiftRegisterImmutable(self.width, new_value) def __repr__(self): return fShiftRegisterImmutable(width{self.width}, value0b{self.value:0{self.width}b})不可变版本适合在函数式风格的代码里使用缺点是不能直接链式修改同一变量。拿sr sr 1 0 1来写虽然多敲了几个字符但副作用更可控。我的建议是如果你的类本身就是容器或者状态机用可变版本如果你的类表示的是一个数值、一个位集合优先用不可变版本。5. 常见问题排查与避坑清单5.1 症状、原因和解决方案速查表我在调试这类魔法方法时常用的排查表大概是这样的症状可能原因解决思路NoneType没有__lshift____lshift__忘记返回self或新对象在方法末尾明确return selfunsupported operand type(s) for 左侧不支持右侧没有__rlshift__在右侧类里补__rlshift____lshift__里抛了NotImplementedError把NotImplementedError和NotImplemented混淆返回NotImplemented而不是抛异常a b的结果莫名其妙是None__lshift__没有return补上返回语句a b之后a变成None__ilshift__没有返回新对象或self原地修改后return self链式调用时第二个操作符报错第一个__lshift__返回了错误类型确认返回类型与左操作数兼容这张表覆盖了我见过的绝大多数问题。尤其是第二种它特别隐蔽左侧是内置类型int右侧是你自己写的类结果int.__lshift__一碰到不认识的类型就返回NotImplemented于是你的类必须接住__rlshift__这个球。如果只看报错信息你完全想不到问题出在自己类里少了一个方法。5.2 两个经常被忽略的底层细节第一个细节是特殊方法查找不看实例。也就是说你不能在运行时给某个实例临时塞一个__lshift__属性来让运算符生效。魔法方法必须在类定义时出现在type上这是 Python 解释器层面的优化和约定。想绕过它只能创建新的子类或动态生成新类。第二个细节是operator.lshift可以帮你做更干净的调试。operator.lshift(a, b)和a b等价但它是一个普通函数可以包进print或者inspect。当你怀疑运算符分发有问题时直接跑一下import operator print(operator.lshift(my_obj, 2))如果这一行能跑通说明__lshift__本身没问题问题大概率出在类型查找顺序或者返回值上。这个技巧在排查复杂类层次时非常好用比在表达式外面套try/except更直接。6. 我的实操建议什么时候值得用__lshift__6.1 适合与不适合的场景对照__lshift__是一种非常强的表达工具但越强的工具越需要克制。我自己的判断标准很简单如果你能用普通方法名把意图表达得更清楚就不要强行用运算符如果这个运算符在你们的领域里已经有了稳定语义就可以放心用。场景建议任务/日志管道可以用表示“推入”语义清晰硬件模拟/寄存器可以用表示“移入”保留位移含义只是想让 API 少几个字不推荐方法名更安全面向新人的公共库要慎重尽量同时保留.push()与位运算无关的纯业务逻辑避免使用容易让人误解除了这张表我还会在类定义旁边写清楚每个魔法方法到底承诺了什么。比如__lshift__是修改自身还是返回新对象链式调用是否保证返回同一种类型这些细节如果不在文档里写明使用者只能靠猜。6.2 实践经验我在自己的一个小型任务调度器里曾经想把submit(task)直接改成task_queue task。代码确实短了但团队里有人看到task job的时候完全分不清是“提交任务”还是“位移”。后来我保留了submit()方法同时让成为它的语法糖入口。这样一来熟悉运算符的人可以写得更快不熟悉的人也有一个安全的显式方法可以依赖。最后再分享一个小技巧给自己类加魔法方法时最好顺手写一个冒烟测试把__lshift__、__rlshift__、__ilshift__三个方向各覆盖一次。别小看这个测试我踩过几次坑之后发现很多看起来“玄学”的运算符问题其实都是因为只测了最舒服的那条调用路径忘记了反向和原地赋值也会被解释器触发。弄清楚这三兄弟你的 Python 3.12 代码就能在上玩出真正顺手的花样。