我最早接触 Python 时对满屏的__xxx__是有点发怵的。明明写业务逻辑用不到几个但看框架源码、看别人封装库时满眼都是这些奇怪的双下划线。后来在某个项目里需要写一个极简的可迭代缓存对象被IndexError和无限递归折磨到怀疑人生之后我才真正意识到这不是语法糖炫技而是 Python 对象模型的地基。这一篇就把我摸爬滚打后对双下划线魔术方法的理解掰开揉碎讲清楚顺便补上大量我自己踩过的坑。这个标题看起来是个基础话题但能问出双下划线魔术方法到底怎么用的人往往已经不是停留在__init__的初学者了而是开始写类、写框架、写装饰器、甚至试图理解标准库源码的进阶者。这篇文章适合你如果你想搞清楚__repr__和__str__到底该实现谁、为什么obj other有时候会失效、怎么让自定义对象表现得像列表或字典、以及with语句背后到底发生了什么那么接下来的内容就是为你准备的。1. 魔术方法到底是什么从语法糖到底层协议的转变在讲具体方法之前我觉得有个认知必须先建立起来魔术方法不是魔法它是 Python 在语言层面预留的行为协议。你写a b解释器不会知道你a和b到底是什么类型但它会固定地尝试去调用a.__add__(b)。如果你没实现再尝试b.__radd__(a)都失败就抛TypeError。这一整套决策流程是写死在解释器里的你的代码只是在按协议响应。1.1 双下划线不是私有的标记很多从其他语言转过来的朋友第一反应是双下划线是不是表示私有这确实是一个长期存在的混淆点。Python 中真正的私有化约定是单下划线_private双下划线__name在类定义里会触发名称改写name mangling变成_ClassName__name这是为了防止子类意外覆盖父类的变量但它跟私有的语义并不完全等价。而魔术方法里的双下划线比如__init__、__len__、__getitem__它们不是私有方法的标志而是解释器保留协议的记号。Python 官方文档把这组方法统称为特殊方法special methods魔术方法只是社区里的昵称。弄明白这个区别之后你就不会再去纠结为什么这么多公有方法要写成双下划线这种问题了。1.2 协议机制给自定义类带来的能力边界为什么理解协议这个视角很重要因为 Python 的很多高级特性比如for循环、切片、with语句、字典访问、集合去重本质上都不是内置类型专属特权而是任何类都可以通过实现特定方法去接入的语言级能力。换句话说内置类型之所以有那些行为是因为它们实现了那些协议而不是因为它们天生特殊。举个例子for x in obj这个语法Python 解释器会先尝试调用iter(obj)也就是obj.__iter__()如果这个类没有定义__iter__解释器会退回去调用__getitem__(0)、__getitem__(1)一直到__getitem__抛出IndexError为止。这个退化机制意味着你哪怕只实现了一个__getitem__你的对象就已经具备被for遍历的能力。这种协议优先、语法糖次之的理解方式才是真正读懂 Python 对象模型的开端。2. 对象生命周期__new__、__init__、__del__的三角关系对象的生命周期是每个写 Python 的人都会接触的但很多人的理解停留在__init__是构造函数。严格来说这句话是错的__init__是初始化方法真正的构造函数是__new__。__new__负责创建并返回一个实例__init__负责对这个实例做初始化两者在生产环境中的职责完全不同。2.1__new__和__init__的调用顺序与参数传递当你写MyClass(*args, **kwargs)时Python 实际执行顺序是先调用type.__call__它会去调用MyClass.__new__(MyClass, *args, **kwargs)__new__返回一个实例如果返回的实例是MyClass的实例再调用MyClass.__init__(instance, *args, **kwargs)如果__new__返回的是别的类型的对象__init__不会被调用这就是为什么不可变类型如tuple可以在__new__里完成初始化因为对象一旦创建就不能变了__init__阶段已经太晚了。我之前在实现一个内部缓存标识类时所有字段都在__new__里确定目的就是为了让实例创建后不可能被外部修改这是一种不可变性的强制手段。那什么时候需要自己重写__new__常见场景有三个单例模式、不可变对象、以及需要返回类缓存实例的工厂。但要注意重写__new__时必须合理处理参数转发class Config: _instance None def __new__(cls, *args, **kwargs): if cls._instance is None: cls._instance super().__new__(cls) return cls._instance这段代码是最简单的单例写法。__new__第一个参数是类本身后面的参数是实例化时传入的一定要原样转发给super().__new__(cls, *args, **kwargs)。如果你在__init__里接收了参数但__new__没有把参数传给父类某些场景下会出现奇怪的TypeError这种问题排查起来非常隐蔽。2.2__del__并不是你想象中那样可靠的析构函数很多从 C 或 Java 转过来的朋友会理所当然地把__del__当成析构函数认为对象销毁时一定会执行。大错特错。__del__是在对象的引用计数降为零时由垃圾回收机制调用的调用时机完全受内存管理算法的控制甚至程序退出时也不一定保证触发。你如果在__del__里做资源释放、文件关闭这类关键操作极有可能在真实运行环境中漏掉。我见过最典型的错误是在__del__里去操作全局变量或试图打印日志结果程序退出时相关模块已经被销毁抛出的异常会被直接忽略。正确的做法是资源释放应该放在上下文管理器__enter__/__exit__里或者用with语句显式管理生命周期。__del__顶多做个兜底别把它当主路径。2.3__init__返回值的问题为什么它必须返回 None__init__的返回值有一个硬性约束必须返回None。如果你在__init__里写了return somethingPython 会直接抛TypeError。这一点在重写父类__init__时尤其容易踩坑比如class Base: def __init__(self): self.data [] class Child(Base): def __init__(self): super().__init__() # return self # 这一行写出来就直接 TypeError为什么这么设计因为__init__的存在只是为了初始化实例的产生是__new__的职责如果__init__可以返回别的对象整个对象创建流程就混乱了。理解了__new__负责造对象、__init__只负责装修这个分工你就不会再犯这种错误。3. 让对象可打印__repr__和__str__的双轨制调试代码时最常见的动作就是把对象打印出来看看。这个打印背后就是一整套魔术方法在起作用。print 一个对象时Python 会调用str(obj)而在交互式终端里直接输入对象名显示的是repr(obj)。两个入口对应两个不同的方法而且它们的回退关系很容易被忽略。3.1 为什么说__repr__比__str__更底层__str__没定义时str(obj)会回退到__repr__而__repr__没定义时str(obj)和repr(obj)都会返回一个类似__main__.Foo object at 0x7f...的默认内存地址字符串。所以从兜底能力来看__repr__是更基础的那一个。社区里还有个有名的建议__repr__应该输出一个无歧义、可用于重建对象的字符串也就是所谓的eval(repr(obj)) obj理想效果。虽然不必强求所有类都做到这一点有些对象内部状态太复杂但至少__repr__要能反映出这个对象的类型和关键状态方便你在日志里肉眼判断这是哪个实例、值是什么。class Point: def __init__(self, x, y): self.x x self.y y def __repr__(self): return fPoint(x{self.x}, y{self.y}) def __str__(self): return f({self.x}, {self.y}) p Point(1, 2) print(p) # (1, 2) —— 走 __str__ str(p) # (1, 2) —— 走 __str__ repr(p) # Point(x1, y2) —— 走 __repr__3.2 在日志和异常信息里__repr__才是主角一个很容易忽视的细节当对象出现在列表、字典、集合里时打印整个容器容器会调用元素对象的__repr__而不是__str__。比如print([p])显示的是[Point(x1, y2)]而不是[(1, 2)]。所以如果你只实现其中一个优先实现__repr__因为你调试容器内容时看到的一定是它。我在做后端日志结构体时几乎每个实体类都实现了__repr__但未必实现__str__。日志里打印一串实体列表时每一行都至少能看到类型名和主键排查问题效率高非常多。这个习惯强烈建议你直接抄走。接上回我们已经在对象创建和打印这两个基础环节建立了协议式思维。接下来要聊的运算符重载是把自定义对象真正融入 Python 语法的最直观部分。很多人觉得只能用于数字、*只能用于序列但其实通过__add__、__mul__这些方法你的业务对象完全可以让表达合并语义让in表达包含语义。这就是为什么说 Python 语法是高度可扩展的。但正因为可扩展才更要小心。运算符重载在业务代码里是把双刃剑用得好了代码语义清晰得像在写领域语言用滥了到底是想表达数学加法、列表拼接还是业务合并只有写代码的人自己知道。我在第四部分会把常见的运算符协议、为什么需要处理反射运算、以及如何避免重载失控一次性讲透。4. 运算符重载让、、in懂你的业务对象假设你有一个金额类型直接amount1 amount2就是合并金额这就是运算符重载最直观的价值。但这里面的门道远不止实现一个__add__那么简单。你需要考虑两个不同类型的对象相加怎么办a b和b a的结果一致吗比较的到底是内存地址还是业务主键这些问题在生产中会一个个跳出来。4.1__add__、__sub__等算术方法背后的反射机制当你写a b时Python 优先调用type(a).__add__(a, b)。如果a没实现__add__或者实现了但返回了NotImplemented注意不是TypeError解释器会转向调用type(b).__radd__(b, a)。这就是反射运算reflected arithmetic方法存在的意义让运算符右侧的对象有机会决定如何运算。class Money: def __init__(self, amount): self.amount amount def __add__(self, other): if isinstance(other, Money): return Money(self.amount other.amount) return NotImplemented def __radd__(self, other): if isinstance(other, (int, float)): return Money(other self.amount) return NotImplemented money Money(100) total 50 money # 触发 __radd__这里的关键点是NotImplemented。很多初学者以为返回None或者直接抛异常就行但实际上协议要求你返回NotImplemented表示我不支持这种运算让解释器继续给另一方机会。如果在__radd__里出现了None或错误类型你会看到非常难懂的报错信息。4.2__eq__与__hash__为什么重写相等比较后要一起重写哈希自定义对象的相等比较是最容易被忽视的深坑。默认情况下两个对象只有在同一个对象时才相等也就是内存地址相同。当你重写__eq__想让金额相同且货币相同的两个对象相等时Python 会做出一个关键决定自动把该类的__hash__设为None不可哈希。这意味着这个对象不能放进set也不能作为dict的 key。这个设计背后是有数学逻辑的如果a b那么hash(a) hash(b)必须成立否则对象放进哈希集合后查找时会出现明明相等却找不到的诡异问题。所以当你重写了__eq__而又的确需要对象可哈希时必须同时重写__hash__class Money: def __init__(self, amount, currency): self.amount amount self.currency currency def __eq__(self, other): if not isinstance(other, Money): return NotImplemented return (self.amount, self.currency) (other.amount, other.currency) def __hash__(self): return hash((self.amount, self.currency))我踩过的坑是一对一的实体类只重写了__eq__结果在某个缓存模块里它被当成dict的 key一运行就报TypeError: unhashable type。排查半天才意识到是等值比较和哈希的一致性出了问题。所以你在做实体类设计时__eq__和__hash__要当成一个组合来考虑别拆开处理。4.3__bool__、__len__与条件判断的隐式调用另一个容易被忽略的隐式协议是布尔判断。当你写if obj:时Python 会先尝试调用bool(obj)。如果类没有定义__bool__则尝试调用__len__如果len(obj)返回 0则视为False如果__len__也没定义则对象默认视为True。这个退化链路解释了为什么一个只实现了__len__的容器对象放进if语句里就能自动表达是否为空。但也要注意只搞定__bool__而不考虑__len__会导致某些地方行为不一致。我建议实现容器类时__len__和__bool__保持语义一致避免出现列表里明明有元素但if obj却是 False这种诡异逻辑。讲完运算符重载我们可以更进一步了。有了前面这些基础你已经能给自定义对象加上算术、比较和容器行为。但 Python 对象模型最有意思的部分之一是属性访问本身也可以被拦截和改写。obj.attr这个看起来不能再简单的表达式背后藏着__getattribute__、__getattr__、__setattr__、__delattr__四个方法它们共同构成了属性访问协议。合理利用这套协议能做出动态代理、懒加载、只读字段等非常优雅的设计但也是最容易翻车的领域之一。5. 属性访问协议拦截.后面的每一个动作很多框架代码让你摸不着头脑就是因为你在obj.attr上只看到结果看不到过程。比如某些 ORM 框架里user.name这一句看起来就是读字段实际上它可能触发了数据库查询、缓存判断和数据格式转换。这一切都发生在属性访问协议里面。5.1__getattr__和__getattribute__的区别一个管缺失一个管全部这两个方法的区别经常被搞混我一句话说清__getattr__只在正常的属性查找失败之后才会被调用可以说它是个兜底而__getattribute__在每一次属性访问时都会先被调用不管属性存不存在。因为__getattribute__拦得最彻底实现的时候稍有不慎就会无限递归。class Proxy: def __init__(self, target): self._target target def __getattr__(self, name): return getattr(self._target, name) def __setattr__(self, name, value): if name.startswith(_): super().__setattr__(name, value) else: setattr(self._target, name, value)这个例子是一个典型的透明代理外部访问proxy.any_attr如果实例自身没有这个属性__getattr__就会转发给背后的target对象。但注意__setattr__里我用super().__setattr__(name, value)直接调用了object层次的方法而不是self.__dict__[name] value。为什么因为如果在__setattr__里写self._target target这句话本身会再次触发__setattr__然后就递归到天荒地老。这个递归陷阱是属性拦截最经典的翻车点。5.2 只在__setattr__里写了self._target target会发生什么我确实见过有人写出这样的代码class BadProxy: def __init__(self, target): self._target target # 这里触发了 __setattr__ def __setattr__(self, name, value): self.__dict__[name] value这段代码反而没问题因为self.__dict__是真实的实例字典写入它不会再触发__setattr__。但如果把最后一行误写成self.name value那就无限递归了。更隐蔽的是如果你在__getattr__里访问了self.__dict__而这个属性的类本身重写成了别的行为也会绕进死循环。我的建议很简单在属性拦截方法里操作内部状态时要么用object.__setattr__(self, name, value)要么直接操作self.__dict__并且永远不要在拦截方法里使用self.xxx的普通写法。5.3 利用属性协议做只读字段和懒加载属性访问协议最实用的两个生产场景是只读字段和懒加载。假设你有一个配置对象希望在实例化之后就不允许修改关键字段但又不想写一堆property和setter可以通过__setattr__统一拦截class ImmutablePoint: def __init__(self, x, y): object.__setattr__(self, x, x) object.__setattr__(self, y, y) object.__setattr__(self, _frozen, True) def __setattr__(self, name, value): if getattr(self, _frozen, False): raise AttributeError(f{name} is read-only) object.__setattr__(self, name, value)懒加载则是把重计算延迟到属性第一次被访问时。比如一个对象有一个report属性生成它需要耗时数秒你可以不预先计算而是在__getattr__或普通属性访问里判断_report是否存在不存在就现场计算并缓存class LazyReport: def __init__(self, data): self.data data self._report None property def report(self): if self._report is None: self._report self._generate_report() return self._report这里用property比__getattr__更清晰因为没有必要拦截所有属性的访问。我的经验是能用property解决的就别上__getattr__后者是最后的底牌用多了会让代码的可读性大打折扣。属性访问协议讲透了之后我们进入 Python 容器协议的世界。如果说属性拦截是让对象在点操作层面变得动态那么容器协议就是让对象在括号操作层面变得像内置的列表和字典。自定义容器是在业务代码中最高频使用魔术方法的地方也是最能直接提升代码体验的部分。你在写一个数据模型、一个分页对象、一个缓存结构时如果它天然支持下标访问、长度计算、成员判断上层业务代码将会变得极其顺手。6. 自定义容器类让对象像列表和字典一样被使用很多人一想到自定义容器会觉得必须继承list或dict这其实是过度使用继承的惯性思维。Python 的容器能力来自协议而不是继承关系。你的类可以实现__getitem__、__setitem__、__delitem__、__len__、__iter__、__contains__这几个方法从而获得完整且灵活的容器行为同时保留自己独特的内部结构。6.1__getitem__不只是索引访问它还撑起了切片、for循环和in判断__getitem__是整个容器协议的核心它的职责很朴素根据key返回对应的值。但这个方法的灵活性在于key不一定只是整数索引。当你写obj[1:3]时传入__getitem__的其实是一个slice对象当你写obj[key]时传入的是字符串。你能容纳的 key 类型越多你的容器就越贴近真实业务。class Page: def __init__(self, items, total, page_no, page_size): self.items items self.total total self.page_no page_no self.page_size page_size def __getitem__(self, key): if isinstance(key, slice): return Page(self.items[key], self.total, self.page_no, self.page_size) return self.items[key] def __len__(self): return len(self.items) def __iter__(self): return iter(self.items) def __contains__(self, item): return item in self.items这个Page类没有继承任何容器基类但它已经可以page[0]获取元素、page[1:2]切片、len(page)获取当前页大小、for item in page遍历、item in page判断成员。对一个分页对象来说这种体验非常自然。这里的slice分支是我在实际项目中补充的因为直接返回裸列表会丢失分页上下文返回Page对象反而能链式操作。6.2 实现__setitem__和__delitem__时的边界处理如果你想让自己的容器支持obj[key] value和del obj[key]就要实现__setitem__和__delitem__。这两个方法容易踩的坑是类型校验。比如你设计的容器只允许整数下标但外部可能传入字符串、slice或者自定义类型最好在方法开头做一次明确的类型校验def __setitem__(self, key, value): if not isinstance(key, (int, slice)): raise TypeError(fUnsupported key type: {type(key).__name__}) self.items[key] value为什么一定要加这个校验因为默认的内置列表在不合法下标时抛的是TypeError或IndexError如果你的自定义容器对非法 key 采取了静默忽略的策略上层业务会在很晚的时候才暴露出问题排查成本极高。反之提前把错误类型抛清楚是让调用方第一时间发现问题的最好方式。6.3 字典的__missing__钩子解决 KeyError 的优雅方式字典协议里有个很隐蔽但极其有用的钩子__missing__。它的触发条件是当你在一个dict的子类里访问不存在的 key 时Python 不会直接抛KeyError而是会调用__missing__(key)并把它的返回值作为结果返回。这在实现默认值字典时非常好用class DefaultListDict(dict): def __missing__(self, key): value [] self[key] value return value d DefaultListDict() d[group_a].append(item1) # 不会抛 KeyError这段代码解决了 每次访问不存在的 key 都要先判断或初始化 的痛点。但注意__missing__只在dict的子类中生效普通类实现__getitem__时并不会自动调用__missing__。我见过有人在一个不继承dict的类里定义了__missing__然后困惑为什么没用就是这个原因。如果你想在普通类里达到类似效果需要在__getitem__里手动处理缺失分支。容器协议到这里基本覆盖了日常所需但这还没到魔术方法的尽头。真正让 Python 在各种 DSL领域特定语言和框架中大放异彩的是__call__和上下文管理器协议。这两个协议让对象可以像函数一样被调用也可以像资源管理器一样配合with语句。如果你写过装饰器、写过策略模式、写过需要自动开关资源的类你应该能感受到这两个协议的威力。7.__call__与上下文管理器让实例化身函数和资源管理器obj()这种写法在 Python 里很常见但你知道它背后的机制吗当你执行obj()时Python 会调用type(obj).__call__(obj, ...)。对于普通类实例来说只要类里定义了__call__这个实例就可以变得可调用和函数的行为保持高度一致。很多框架把这类对象称为 callable object它的优点在于对象是以函数的形式被调用但内部可以持有状态。这一点是普通函数做不到的。7.1 为什么需要把一个对象设计成可调用函数在 Python 里是一等公民但函数本身是无状态的除非借助闭包或全局变量。当你需要一种可调用且带状态的东西时最直观的方案是用类。但类实例默认不可调用你需要显式实现__call__。最经典的例子就是装饰器。一个带参数的装饰器通常用两层函数实现但如果你希望装饰器内部还能记录调用次数、缓存结果用带__call__的类会更清晰class CountCalls: def __init__(self, func): self.func func self.calls 0 def __call__(self, *args, **kwargs): self.calls 1 print(fcalls: {self.calls}) return self.func(*args, **kwargs) CountCalls def hello(name): return fhello {name}这个设计让调用函数和统计调用次数天然地融合在一起。如果换成纯函数实现你需要借助nonlocal变量而且可读性明显弱于这个类版本。实际项目里还有一种常见用法就是策略注册表用一个__call__对象保存所有策略调用时根据条件分发这比写一长串if-elif要优雅得多。7.2 上下文管理器协议的完整链路with语句是现代 Python 中管理资源最推荐的方式它背后的协议只有两个方法__enter__和__exit__。当执行with obj as x:时Python 先调用obj.__enter__()把返回值赋给x然后执行代码块无论代码块是否正常结束都会调用obj.__exit__(exc_type, exc_value, traceback)。__exit__的三个参数分别对应异常类型、异常实例和 traceback 对象。当代码块没有异常时这三个值都是None。如果你想在with代码块里吞噬某个异常让程序继续往下走可以在__exit__里返回True。这看起来很灵活但我强烈建议不要轻易返回True因为吞异常会让外层很难发现问题。更合理的做法是让__exit__始终返回None或False让异常继续向上传播。class ManagedConnection: def __enter__(self): print(acquiring resource) return self def __exit__(self, exc_type, exc_value, traceback): print(releasing resource) return False with ManagedConnection() as conn: print(doing work)7.3 用 contextlib 减少上下文管理器的样板代码如果每次写上下文管理器都要定义完整的类代码量确实有点大。Python 的contextlib模块提供了contextmanager装饰器可以把一个生成器函数直接包装成上下文管理器from contextlib import contextmanager contextmanager def managed_resource(): print(acquire) try: yield resource finally: print(release)这里的关键是yield。yield之前的部分对应__enter__yield之后的部分对应__exit__finally块保证了即使在with代码块里抛异常资源也一定会被释放。这个方式写起来比手写__enter__/__exit__类要轻量得多我写临时资源管理时几乎总是优先用contextmanager。但如果你需要非常精细的异常处理逻辑比如区分异常类型再决定是否吞掉手写类会更合适。讲到这里常见的几大类魔术方法已经覆盖了大半。但我在实际工作和带人的过程中发现真正能区分掌握魔术方法和只是背过魔术方法的往往是那些边界条件和组合效应。很多人看起来每个方法都见过写代码时却不断掉进同样的坑里。所以在最后这半部分我会把最常见也最危险的几个坑集中梳理一遍然后给出排查方法和一个完整的重构案例。8. 与魔术方法相关的五大常见误区这部分是我最想写的因为绝大多数魔术方法好难的抱怨其实都来自这几个典型误区而不是方法本身复杂。我按踩坑频率从高到低排个序基本上你把这些坑都认清日常写代码的自信心能涨一大截。8.1 误区一靠记忆硬背方法名单初学 Python 时很多人会去背那一长串双下划线方法的名称和触发条件结果今天背明天忘。其实正确做法是带着场景去学。比如你写了一个配置类想让它支持config[key]的读取方式自然就需要__getitem__你想让它支持with config:进入上下文自然就需要__enter__/__exit__。以需求驱动方法名只是顺手记住的结果。如果确实需要查全量名单建议直接看官方文档 data model 章节里面有完整的触发条件和示例。把文档当词典而不是教材效率会高很多。我自己也从来不会去背完整方法表但每个高频方法的语义和触发链都了然于胸因为每天都在用。8.2 误区二在业务类里重写内置类型的魔术方法有些同学读了几篇重写add实现向量相加的文章后就在订单类里重写add试图让两个订单对象直接相加。这种写法在技术上可行但会让代码的可读性和可维护性大幅下降。魔术方法的核心价值是让自定义类型参与到 Python 的语言级语法中而不是让你把所有业务逻辑都塞进运算符里。更合理的做法是只在类型确实像某种内置类型数值、容器、上下文管理器、迭代器时才考虑实现对应的魔术方法否则就用普通方法如order.merge(other)表达语义会更清晰。判断标准很简单a b这行代码一个不熟悉内部实现的人能不能一眼看出它是什么意思如果不能那你就是在滥用运算符重载。8.3 误区三分不清__str__和__repr__这是出现频率极高的问题也是面试爱问的。简单说__repr__面向开发者目标是无歧义__str__面向用户目标是可读。一个常见的实践是只实现__repr__因为当对象没有__str__时print 会回退到__repr__而且在调试、日志、交互式终端中使用的都是__repr__。class Point: def __repr__(self): return fPoint(x{self.x}, y{self.y})如果坚持只实现其中一个优先__repr__这是 Python 社区的普遍建议。你在 DEBUG 时看到的信息量会完全不同。比如一个列表里放了十个对象如果实现了__repr__你一眼能看到每个对象的类型和关键属性如果没实现你看到的是一堆__main__.Foo object at 0x...还得一个个去查效率天差地别。8.4 误区四覆盖__eq__却忘了__hash__自定义类如果只重写__eq__而不处理__hash__对象放进 set 或作为 dict 的 key 时会非常危险。Python 的规则是类中一旦定义了__eq__该类的__hash__会被自动设为 None也就是不可哈希。如果你希望对象既支持等值比较又支持哈希需要同时实现两者并且保证相等对象的哈希值相同。class Money: def __init__(self, amount, currency): self.amount amount self.currency currency def __eq__(self, other): if not isinstance(other, Money): return NotImplemented return (self.amount, self.currency) (other.amount, other.currency) def __hash__(self): return hash((self.amount, self.currency))这里的经验是做实体类时明确这两点比堆功能更重要因为这直接关系到对象能否安全地用于集合去重和缓存键。还有一个细节__eq__里遇到类型不匹配的other时应该返回NotImplemented而不是直接return False这样能让解释器有机会尝试对方的反向比较方法避免在两个不同类型对象比较时给出不准确的结果。8.5 误区五做了一层能跑就停止深挖很多人在实现了一个魔术方法、跑通测试后就觉得自己掌握了它。实际上很多魔术方法都有边界条件和组合效应。比如__getattr__和__getattribute__如何避免无限递归__getitem__对负索引和切片参数的处理__enter__返回值与 with 语句 as 变量的关系。真正深入的标准是能解释清楚这个方法的调用链、异常路径和退化行为这才叫掌握。如果时间有限我的建议是优先吃透最常遇到的十个左右方法把它们的各种边界情况逐一验证。搞懂十个方法背后的机制比囫囵吞枣地把三十个方法名背下来收获更大。因为大部分方法之间的关系是相互联动的你真正理解了__getitem____iter__的退化机制自然就懂了理解了__eq____hash__的存在意义也就顺理成章了。9. 调试与排查如何快速定位是哪个魔术方法在生效魔术方法最大的特点就是隐式调用。你写的是obj[key]实际执行的是obj.__getitem__(key)。当程序出错时报错栈里其实给了你非常直接的线索关键是你得知道怎么读。9.1 从报错栈里读出的线索Python 在调用魔术方法时报错栈顶层往往直接显示方法名。比如在 Jupyter 中写df[df[a] 1]报错栈里会显示__getitem__相关帧当自定义对象打印乱码时第一反应应该是查看它有没有实现__repr__。这是排查的第一步从异常信息反推哪个协议方法被触发了。更隐蔽的情况是隐式调用链。例如for x in obj会先尝试__iter__没有则退化为调用__getitem__(0)、__getitem__(1)直到IndexError。理解这一退化机制能帮你解释很多看似没定义却能用的现象。某次我在排查一个可迭代对象为何性能奇差时发现它没有实现__iter__每次循环都通过__getitem__逐一下标访问浪费了大量时间。加了__iter__后性能直接提升了一个数量级。9.2 在魔术方法里下断点写单元测试或调试时给魔术方法加日志或断点是最直接的方式。例如def __getitem__(self, key): print(f[DEBUG] __getitem__ called with key{key}) return self.data[key]这种方法在排查 CRUD 框架或 ORM 的查询缓存问题时特别有效。你很快会发现框架在背后悄悄调用了无数次__getitem__从而定位性能瓶颈或意外触发的路径。我在某次排查线上接口响应变慢时就是靠给__getitem__加日志发现了问题一个看起来只做了一次索引访问的地方实际在框架内部触发了上百次下标操作。9.3 绕过魔术方法直接访问底层在某些需要规避自定义逻辑的场景下可以用object.__getattribute__(obj, attr)跳过重写后的行为。这个技巧在元编程、序列化、深拷贝等场景中很有用但也要谨慎使用。绕过魔术方法意味着丢弃了自定义类型的所有保护性逻辑容易引入隐患。比如你明明实现了属性校验序列化时直接绕过了等于把校验拱手让出。另外想查看一个对象当前实现了哪些魔术方法可以配合dir()或者inspect.getmembers()检查。面对为什么这个对象能使用切片但另一个不行这类问题用dir()对比两个对象的属性列表往往一眼就能看出差异。这个排查思路比翻文档更快因为对象是活的dir()给你的是这一时刻最真实的答案。10. 生产环境中的真实案例用魔术方法重构一段糟糕代码理论讲再多不如看一次真实项目的重构过程。下面这个案例来自一个模拟数据同步模块我给它做了脱敏处理但核心逻辑完全保留。这段代码的糟糕之处、重构思路和最终收益应该能让你直观感受到魔术方法在实战中的价值。10.1 背景一段令人头疼的 if-else 长函数某系统负责把内部数据同步到外部平台其中有一段核心函数专门负责将不同来源的字段映射成目标平台要求的嵌套字典。当时的代码是这样的根据source_type写了一大段if-else每个分支里都手工构造 dict缩进越来越深新增一个来源就要在函数里再添一个分支测试时几乎要把整个函数跑一遍才知道改没改坏。def build_payload(source_type, data): if source_type order: return { order_id: data[id], amount: data[total], items: [{name: i[name]} for i in data[items]], } elif source_type user: return { user_id: data[uid], name: data[nickname], } elif source_type refund: return { refund_id: data[rid], reason: data[reason], } # 每新增一个来源就多一个 elif这段代码的问题很明显横向蔓延、重复模式多、难以单测、新增成本高。每个分支都是把一种业务数据翻译成另一种结构它本质上就是一个映射协议问题。正因为它具有按类型分发 返回统一结构的特征非常适合用__call__和__getitem__重构。10.2 重构用__call__和__getitem__建立统一的映射协议重构方案是定义一个PayloadBuilder类让不同来源的构建规则注册到同一套映射协议上。类本身实现__call__使实例可以像函数一样被调用内部用__getitem__支持按source_type获取对应的构建器。新增一种来源时不需要改动现有函数只需要注册一个新的构建规则。class PayloadBuilder: def __init__(self): self._builders {} def register(self, source_type, builder): self._builders[source_type] builder def __getitem__(self, source_type): return self._builders[source_type] def __call__(self, source_type, data): builder self._builders[source_type] return builder(data) builder PayloadBuilder() builder.register(order, lambda d: { order_id: d[id], amount: d[total], }) builder.register(user, lambda d: { user_id: d[uid], name: d[nickname], }) builder.register(refund, lambda d: { refund_id: d[rid], reason: d[reason], })重构之后调用方只需payload builder(source_type, data)。新来源的扩展从修改函数变成注册规则单个规则的测试也可以独立进行。最关键的变化是业务语义从一大段if-else变成了清晰的注册模式代码行数减少、嵌套消失、可读性明显提升。10.3 收益与局限什么时候不该用这个模式这次重构带来的收益是实实在在的核心函数从 70 多行缩减到约 30 行新增来源的平均耗时从约半天降低到一小时内单测用例从覆盖所有分支变成逐个注册规则验证更容易写满覆盖率。但也要说清楚它的局限。如果映射规则彼此之间耦合极深、分支条件复杂例如 A 规则依赖 B 规则的输出那么强行统一协议反而会引入额外复杂度。魔术方法是工具不是银弹。用它的标准应该是让代码表达更贴近问题的本质而不是为了秀技巧。这个案例里之所以能成功是因为按类型构建统一负载结构这个需求本身就是一个天然的分发协议所以用__call__和__getitem__是顺理成章的选择。11. 总结与我的实操建议最后说点实在的。这个标题虽然是双下划线魔术方法但真正到了项目里你不需要记住全部。我这里列一下目前我在生产代码里最高频使用的清单供参考__init__/__new__对象生命周期控制__repr__调试信息可读性__eq__/__hash__实体对象比较与去重__getitem__/__setitem__/__len__/__iter__/__contains__自定义容器__enter__/__exit__资源管理与上下文__call__函数式接口封装__getattr__/__setattr__动态属性与拦截__str__用户可读输出__bool__/__format__条件判断与格式化学习方法上我个人的体会是不要死记方法大全而是找一个真实项目里让你不舒服的重复代码尝试用魔术方法来消除它。当你真的用__call__重构掉一段if-elif长链或者用__getitem__让数据访问变得像字典一样自然时这些方法在你的记忆里就再也丢不掉了。还有一个小技巧想分享给你。写自定义类时我会先问自己三个问题这个类的实例会被打印吗会被放进集合或作为字典 key 吗会被for遍历或用下标访问吗只要有一个回答是肯定的对应的__repr__、__eq__/__hash__、__iter__/__getitem__就该被安排上。这种从使用场景反推方法的思路比看着方法大全无从下手要高效得多。双下划线魔术方法的核心是让你的对象更懂 Python 的语法。这个标题背后真正要传达的就是这件事。理解到这一层双下划线就不再是玄学而是顺手好用的语言级工具。希望这篇长文能帮你跳过那些我踩过的坑直接站到会用、敢用、用得对的层次上来。 
长河君 · 2026/10/15 7:20:54 · 阅读 1.2k Python双下划线魔术方法深度解析：从__init__到__getitem__
我最早接触 Python 时对满屏的__xxx__是有点发怵的。明明写业务逻辑用不到几个但看框架源码、看别人封装库时满眼都是这些奇怪的双下划线。后来在某个项目里需要写一个极简的可迭代缓存对象被IndexError和无限递归折磨到怀疑人生之后我才真正意识到这不是语法糖炫技而是 Python 对象模型的地基。这一篇就把我摸爬滚打后对双下划线魔术方法的理解掰开揉碎讲清楚顺便补上大量我自己踩过的坑。这个标题看起来是个基础话题但能问出双下划线魔术方法到底怎么用的人往往已经不是停留在__init__的初学者了而是开始写类、写框架、写装饰器、甚至试图理解标准库源码的进阶者。这篇文章适合你如果你想搞清楚__repr__和__str__到底该实现谁、为什么obj other有时候会失效、怎么让自定义对象表现得像列表或字典、以及with语句背后到底发生了什么那么接下来的内容就是为你准备的。1. 魔术方法到底是什么从语法糖到底层协议的转变在讲具体方法之前我觉得有个认知必须先建立起来魔术方法不是魔法它是 Python 在语言层面预留的行为协议。你写a b解释器不会知道你a和b到底是什么类型但它会固定地尝试去调用a.__add__(b)。如果你没实现再尝试b.__radd__(a)都失败就抛TypeError。这一整套决策流程是写死在解释器里的你的代码只是在按协议响应。1.1 双下划线不是私有的标记很多从其他语言转过来的朋友第一反应是双下划线是不是表示私有这确实是一个长期存在的混淆点。Python 中真正的私有化约定是单下划线_private双下划线__name在类定义里会触发名称改写name mangling变成_ClassName__name这是为了防止子类意外覆盖父类的变量但它跟私有的语义并不完全等价。而魔术方法里的双下划线比如__init__、__len__、__getitem__它们不是私有方法的标志而是解释器保留协议的记号。Python 官方文档把这组方法统称为特殊方法special methods魔术方法只是社区里的昵称。弄明白这个区别之后你就不会再去纠结为什么这么多公有方法要写成双下划线这种问题了。1.2 协议机制给自定义类带来的能力边界为什么理解协议这个视角很重要因为 Python 的很多高级特性比如for循环、切片、with语句、字典访问、集合去重本质上都不是内置类型专属特权而是任何类都可以通过实现特定方法去接入的语言级能力。换句话说内置类型之所以有那些行为是因为它们实现了那些协议而不是因为它们天生特殊。举个例子for x in obj这个语法Python 解释器会先尝试调用iter(obj)也就是obj.__iter__()如果这个类没有定义__iter__解释器会退回去调用__getitem__(0)、__getitem__(1)一直到__getitem__抛出IndexError为止。这个退化机制意味着你哪怕只实现了一个__getitem__你的对象就已经具备被for遍历的能力。这种协议优先、语法糖次之的理解方式才是真正读懂 Python 对象模型的开端。2. 对象生命周期__new__、__init__、__del__的三角关系对象的生命周期是每个写 Python 的人都会接触的但很多人的理解停留在__init__是构造函数。严格来说这句话是错的__init__是初始化方法真正的构造函数是__new__。__new__负责创建并返回一个实例__init__负责对这个实例做初始化两者在生产环境中的职责完全不同。2.1__new__和__init__的调用顺序与参数传递当你写MyClass(*args, **kwargs)时Python 实际执行顺序是先调用type.__call__它会去调用MyClass.__new__(MyClass, *args, **kwargs)__new__返回一个实例如果返回的实例是MyClass的实例再调用MyClass.__init__(instance, *args, **kwargs)如果__new__返回的是别的类型的对象__init__不会被调用这就是为什么不可变类型如tuple可以在__new__里完成初始化因为对象一旦创建就不能变了__init__阶段已经太晚了。我之前在实现一个内部缓存标识类时所有字段都在__new__里确定目的就是为了让实例创建后不可能被外部修改这是一种不可变性的强制手段。那什么时候需要自己重写__new__常见场景有三个单例模式、不可变对象、以及需要返回类缓存实例的工厂。但要注意重写__new__时必须合理处理参数转发class Config: _instance None def __new__(cls, *args, **kwargs): if cls._instance is None: cls._instance super().__new__(cls) return cls._instance这段代码是最简单的单例写法。__new__第一个参数是类本身后面的参数是实例化时传入的一定要原样转发给super().__new__(cls, *args, **kwargs)。如果你在__init__里接收了参数但__new__没有把参数传给父类某些场景下会出现奇怪的TypeError这种问题排查起来非常隐蔽。2.2__del__并不是你想象中那样可靠的析构函数很多从 C 或 Java 转过来的朋友会理所当然地把__del__当成析构函数认为对象销毁时一定会执行。大错特错。__del__是在对象的引用计数降为零时由垃圾回收机制调用的调用时机完全受内存管理算法的控制甚至程序退出时也不一定保证触发。你如果在__del__里做资源释放、文件关闭这类关键操作极有可能在真实运行环境中漏掉。我见过最典型的错误是在__del__里去操作全局变量或试图打印日志结果程序退出时相关模块已经被销毁抛出的异常会被直接忽略。正确的做法是资源释放应该放在上下文管理器__enter__/__exit__里或者用with语句显式管理生命周期。__del__顶多做个兜底别把它当主路径。2.3__init__返回值的问题为什么它必须返回 None__init__的返回值有一个硬性约束必须返回None。如果你在__init__里写了return somethingPython 会直接抛TypeError。这一点在重写父类__init__时尤其容易踩坑比如class Base: def __init__(self): self.data [] class Child(Base): def __init__(self): super().__init__() # return self # 这一行写出来就直接 TypeError为什么这么设计因为__init__的存在只是为了初始化实例的产生是__new__的职责如果__init__可以返回别的对象整个对象创建流程就混乱了。理解了__new__负责造对象、__init__只负责装修这个分工你就不会再犯这种错误。3. 让对象可打印__repr__和__str__的双轨制调试代码时最常见的动作就是把对象打印出来看看。这个打印背后就是一整套魔术方法在起作用。print 一个对象时Python 会调用str(obj)而在交互式终端里直接输入对象名显示的是repr(obj)。两个入口对应两个不同的方法而且它们的回退关系很容易被忽略。3.1 为什么说__repr__比__str__更底层__str__没定义时str(obj)会回退到__repr__而__repr__没定义时str(obj)和repr(obj)都会返回一个类似__main__.Foo object at 0x7f...的默认内存地址字符串。所以从兜底能力来看__repr__是更基础的那一个。社区里还有个有名的建议__repr__应该输出一个无歧义、可用于重建对象的字符串也就是所谓的eval(repr(obj)) obj理想效果。虽然不必强求所有类都做到这一点有些对象内部状态太复杂但至少__repr__要能反映出这个对象的类型和关键状态方便你在日志里肉眼判断这是哪个实例、值是什么。class Point: def __init__(self, x, y): self.x x self.y y def __repr__(self): return fPoint(x{self.x}, y{self.y}) def __str__(self): return f({self.x}, {self.y}) p Point(1, 2) print(p) # (1, 2) —— 走 __str__ str(p) # (1, 2) —— 走 __str__ repr(p) # Point(x1, y2) —— 走 __repr__3.2 在日志和异常信息里__repr__才是主角一个很容易忽视的细节当对象出现在列表、字典、集合里时打印整个容器容器会调用元素对象的__repr__而不是__str__。比如print([p])显示的是[Point(x1, y2)]而不是[(1, 2)]。所以如果你只实现其中一个优先实现__repr__因为你调试容器内容时看到的一定是它。我在做后端日志结构体时几乎每个实体类都实现了__repr__但未必实现__str__。日志里打印一串实体列表时每一行都至少能看到类型名和主键排查问题效率高非常多。这个习惯强烈建议你直接抄走。接上回我们已经在对象创建和打印这两个基础环节建立了协议式思维。接下来要聊的运算符重载是把自定义对象真正融入 Python 语法的最直观部分。很多人觉得只能用于数字、*只能用于序列但其实通过__add__、__mul__这些方法你的业务对象完全可以让表达合并语义让in表达包含语义。这就是为什么说 Python 语法是高度可扩展的。但正因为可扩展才更要小心。运算符重载在业务代码里是把双刃剑用得好了代码语义清晰得像在写领域语言用滥了到底是想表达数学加法、列表拼接还是业务合并只有写代码的人自己知道。我在第四部分会把常见的运算符协议、为什么需要处理反射运算、以及如何避免重载失控一次性讲透。4. 运算符重载让、、in懂你的业务对象假设你有一个金额类型直接amount1 amount2就是合并金额这就是运算符重载最直观的价值。但这里面的门道远不止实现一个__add__那么简单。你需要考虑两个不同类型的对象相加怎么办a b和b a的结果一致吗比较的到底是内存地址还是业务主键这些问题在生产中会一个个跳出来。4.1__add__、__sub__等算术方法背后的反射机制当你写a b时Python 优先调用type(a).__add__(a, b)。如果a没实现__add__或者实现了但返回了NotImplemented注意不是TypeError解释器会转向调用type(b).__radd__(b, a)。这就是反射运算reflected arithmetic方法存在的意义让运算符右侧的对象有机会决定如何运算。class Money: def __init__(self, amount): self.amount amount def __add__(self, other): if isinstance(other, Money): return Money(self.amount other.amount) return NotImplemented def __radd__(self, other): if isinstance(other, (int, float)): return Money(other self.amount) return NotImplemented money Money(100) total 50 money # 触发 __radd__这里的关键点是NotImplemented。很多初学者以为返回None或者直接抛异常就行但实际上协议要求你返回NotImplemented表示我不支持这种运算让解释器继续给另一方机会。如果在__radd__里出现了None或错误类型你会看到非常难懂的报错信息。4.2__eq__与__hash__为什么重写相等比较后要一起重写哈希自定义对象的相等比较是最容易被忽视的深坑。默认情况下两个对象只有在同一个对象时才相等也就是内存地址相同。当你重写__eq__想让金额相同且货币相同的两个对象相等时Python 会做出一个关键决定自动把该类的__hash__设为None不可哈希。这意味着这个对象不能放进set也不能作为dict的 key。这个设计背后是有数学逻辑的如果a b那么hash(a) hash(b)必须成立否则对象放进哈希集合后查找时会出现明明相等却找不到的诡异问题。所以当你重写了__eq__而又的确需要对象可哈希时必须同时重写__hash__class Money: def __init__(self, amount, currency): self.amount amount self.currency currency def __eq__(self, other): if not isinstance(other, Money): return NotImplemented return (self.amount, self.currency) (other.amount, other.currency) def __hash__(self): return hash((self.amount, self.currency))我踩过的坑是一对一的实体类只重写了__eq__结果在某个缓存模块里它被当成dict的 key一运行就报TypeError: unhashable type。排查半天才意识到是等值比较和哈希的一致性出了问题。所以你在做实体类设计时__eq__和__hash__要当成一个组合来考虑别拆开处理。4.3__bool__、__len__与条件判断的隐式调用另一个容易被忽略的隐式协议是布尔判断。当你写if obj:时Python 会先尝试调用bool(obj)。如果类没有定义__bool__则尝试调用__len__如果len(obj)返回 0则视为False如果__len__也没定义则对象默认视为True。这个退化链路解释了为什么一个只实现了__len__的容器对象放进if语句里就能自动表达是否为空。但也要注意只搞定__bool__而不考虑__len__会导致某些地方行为不一致。我建议实现容器类时__len__和__bool__保持语义一致避免出现列表里明明有元素但if obj却是 False这种诡异逻辑。讲完运算符重载我们可以更进一步了。有了前面这些基础你已经能给自定义对象加上算术、比较和容器行为。但 Python 对象模型最有意思的部分之一是属性访问本身也可以被拦截和改写。obj.attr这个看起来不能再简单的表达式背后藏着__getattribute__、__getattr__、__setattr__、__delattr__四个方法它们共同构成了属性访问协议。合理利用这套协议能做出动态代理、懒加载、只读字段等非常优雅的设计但也是最容易翻车的领域之一。5. 属性访问协议拦截.后面的每一个动作很多框架代码让你摸不着头脑就是因为你在obj.attr上只看到结果看不到过程。比如某些 ORM 框架里user.name这一句看起来就是读字段实际上它可能触发了数据库查询、缓存判断和数据格式转换。这一切都发生在属性访问协议里面。5.1__getattr__和__getattribute__的区别一个管缺失一个管全部这两个方法的区别经常被搞混我一句话说清__getattr__只在正常的属性查找失败之后才会被调用可以说它是个兜底而__getattribute__在每一次属性访问时都会先被调用不管属性存不存在。因为__getattribute__拦得最彻底实现的时候稍有不慎就会无限递归。class Proxy: def __init__(self, target): self._target target def __getattr__(self, name): return getattr(self._target, name) def __setattr__(self, name, value): if name.startswith(_): super().__setattr__(name, value) else: setattr(self._target, name, value)这个例子是一个典型的透明代理外部访问proxy.any_attr如果实例自身没有这个属性__getattr__就会转发给背后的target对象。但注意__setattr__里我用super().__setattr__(name, value)直接调用了object层次的方法而不是self.__dict__[name] value。为什么因为如果在__setattr__里写self._target target这句话本身会再次触发__setattr__然后就递归到天荒地老。这个递归陷阱是属性拦截最经典的翻车点。5.2 只在__setattr__里写了self._target target会发生什么我确实见过有人写出这样的代码class BadProxy: def __init__(self, target): self._target target # 这里触发了 __setattr__ def __setattr__(self, name, value): self.__dict__[name] value这段代码反而没问题因为self.__dict__是真实的实例字典写入它不会再触发__setattr__。但如果把最后一行误写成self.name value那就无限递归了。更隐蔽的是如果你在__getattr__里访问了self.__dict__而这个属性的类本身重写成了别的行为也会绕进死循环。我的建议很简单在属性拦截方法里操作内部状态时要么用object.__setattr__(self, name, value)要么直接操作self.__dict__并且永远不要在拦截方法里使用self.xxx的普通写法。5.3 利用属性协议做只读字段和懒加载属性访问协议最实用的两个生产场景是只读字段和懒加载。假设你有一个配置对象希望在实例化之后就不允许修改关键字段但又不想写一堆property和setter可以通过__setattr__统一拦截class ImmutablePoint: def __init__(self, x, y): object.__setattr__(self, x, x) object.__setattr__(self, y, y) object.__setattr__(self, _frozen, True) def __setattr__(self, name, value): if getattr(self, _frozen, False): raise AttributeError(f{name} is read-only) object.__setattr__(self, name, value)懒加载则是把重计算延迟到属性第一次被访问时。比如一个对象有一个report属性生成它需要耗时数秒你可以不预先计算而是在__getattr__或普通属性访问里判断_report是否存在不存在就现场计算并缓存class LazyReport: def __init__(self, data): self.data data self._report None property def report(self): if self._report is None: self._report self._generate_report() return self._report这里用property比__getattr__更清晰因为没有必要拦截所有属性的访问。我的经验是能用property解决的就别上__getattr__后者是最后的底牌用多了会让代码的可读性大打折扣。属性访问协议讲透了之后我们进入 Python 容器协议的世界。如果说属性拦截是让对象在点操作层面变得动态那么容器协议就是让对象在括号操作层面变得像内置的列表和字典。自定义容器是在业务代码中最高频使用魔术方法的地方也是最能直接提升代码体验的部分。你在写一个数据模型、一个分页对象、一个缓存结构时如果它天然支持下标访问、长度计算、成员判断上层业务代码将会变得极其顺手。6. 自定义容器类让对象像列表和字典一样被使用很多人一想到自定义容器会觉得必须继承list或dict这其实是过度使用继承的惯性思维。Python 的容器能力来自协议而不是继承关系。你的类可以实现__getitem__、__setitem__、__delitem__、__len__、__iter__、__contains__这几个方法从而获得完整且灵活的容器行为同时保留自己独特的内部结构。6.1__getitem__不只是索引访问它还撑起了切片、for循环和in判断__getitem__是整个容器协议的核心它的职责很朴素根据key返回对应的值。但这个方法的灵活性在于key不一定只是整数索引。当你写obj[1:3]时传入__getitem__的其实是一个slice对象当你写obj[key]时传入的是字符串。你能容纳的 key 类型越多你的容器就越贴近真实业务。class Page: def __init__(self, items, total, page_no, page_size): self.items items self.total total self.page_no page_no self.page_size page_size def __getitem__(self, key): if isinstance(key, slice): return Page(self.items[key], self.total, self.page_no, self.page_size) return self.items[key] def __len__(self): return len(self.items) def __iter__(self): return iter(self.items) def __contains__(self, item): return item in self.items这个Page类没有继承任何容器基类但它已经可以page[0]获取元素、page[1:2]切片、len(page)获取当前页大小、for item in page遍历、item in page判断成员。对一个分页对象来说这种体验非常自然。这里的slice分支是我在实际项目中补充的因为直接返回裸列表会丢失分页上下文返回Page对象反而能链式操作。6.2 实现__setitem__和__delitem__时的边界处理如果你想让自己的容器支持obj[key] value和del obj[key]就要实现__setitem__和__delitem__。这两个方法容易踩的坑是类型校验。比如你设计的容器只允许整数下标但外部可能传入字符串、slice或者自定义类型最好在方法开头做一次明确的类型校验def __setitem__(self, key, value): if not isinstance(key, (int, slice)): raise TypeError(fUnsupported key type: {type(key).__name__}) self.items[key] value为什么一定要加这个校验因为默认的内置列表在不合法下标时抛的是TypeError或IndexError如果你的自定义容器对非法 key 采取了静默忽略的策略上层业务会在很晚的时候才暴露出问题排查成本极高。反之提前把错误类型抛清楚是让调用方第一时间发现问题的最好方式。6.3 字典的__missing__钩子解决 KeyError 的优雅方式字典协议里有个很隐蔽但极其有用的钩子__missing__。它的触发条件是当你在一个dict的子类里访问不存在的 key 时Python 不会直接抛KeyError而是会调用__missing__(key)并把它的返回值作为结果返回。这在实现默认值字典时非常好用class DefaultListDict(dict): def __missing__(self, key): value [] self[key] value return value d DefaultListDict() d[group_a].append(item1) # 不会抛 KeyError这段代码解决了 每次访问不存在的 key 都要先判断或初始化 的痛点。但注意__missing__只在dict的子类中生效普通类实现__getitem__时并不会自动调用__missing__。我见过有人在一个不继承dict的类里定义了__missing__然后困惑为什么没用就是这个原因。如果你想在普通类里达到类似效果需要在__getitem__里手动处理缺失分支。容器协议到这里基本覆盖了日常所需但这还没到魔术方法的尽头。真正让 Python 在各种 DSL领域特定语言和框架中大放异彩的是__call__和上下文管理器协议。这两个协议让对象可以像函数一样被调用也可以像资源管理器一样配合with语句。如果你写过装饰器、写过策略模式、写过需要自动开关资源的类你应该能感受到这两个协议的威力。7.__call__与上下文管理器让实例化身函数和资源管理器obj()这种写法在 Python 里很常见但你知道它背后的机制吗当你执行obj()时Python 会调用type(obj).__call__(obj, ...)。对于普通类实例来说只要类里定义了__call__这个实例就可以变得可调用和函数的行为保持高度一致。很多框架把这类对象称为 callable object它的优点在于对象是以函数的形式被调用但内部可以持有状态。这一点是普通函数做不到的。7.1 为什么需要把一个对象设计成可调用函数在 Python 里是一等公民但函数本身是无状态的除非借助闭包或全局变量。当你需要一种可调用且带状态的东西时最直观的方案是用类。但类实例默认不可调用你需要显式实现__call__。最经典的例子就是装饰器。一个带参数的装饰器通常用两层函数实现但如果你希望装饰器内部还能记录调用次数、缓存结果用带__call__的类会更清晰class CountCalls: def __init__(self, func): self.func func self.calls 0 def __call__(self, *args, **kwargs): self.calls 1 print(fcalls: {self.calls}) return self.func(*args, **kwargs) CountCalls def hello(name): return fhello {name}这个设计让调用函数和统计调用次数天然地融合在一起。如果换成纯函数实现你需要借助nonlocal变量而且可读性明显弱于这个类版本。实际项目里还有一种常见用法就是策略注册表用一个__call__对象保存所有策略调用时根据条件分发这比写一长串if-elif要优雅得多。7.2 上下文管理器协议的完整链路with语句是现代 Python 中管理资源最推荐的方式它背后的协议只有两个方法__enter__和__exit__。当执行with obj as x:时Python 先调用obj.__enter__()把返回值赋给x然后执行代码块无论代码块是否正常结束都会调用obj.__exit__(exc_type, exc_value, traceback)。__exit__的三个参数分别对应异常类型、异常实例和 traceback 对象。当代码块没有异常时这三个值都是None。如果你想在with代码块里吞噬某个异常让程序继续往下走可以在__exit__里返回True。这看起来很灵活但我强烈建议不要轻易返回True因为吞异常会让外层很难发现问题。更合理的做法是让__exit__始终返回None或False让异常继续向上传播。class ManagedConnection: def __enter__(self): print(acquiring resource) return self def __exit__(self, exc_type, exc_value, traceback): print(releasing resource) return False with ManagedConnection() as conn: print(doing work)7.3 用 contextlib 减少上下文管理器的样板代码如果每次写上下文管理器都要定义完整的类代码量确实有点大。Python 的contextlib模块提供了contextmanager装饰器可以把一个生成器函数直接包装成上下文管理器from contextlib import contextmanager contextmanager def managed_resource(): print(acquire) try: yield resource finally: print(release)这里的关键是yield。yield之前的部分对应__enter__yield之后的部分对应__exit__finally块保证了即使在with代码块里抛异常资源也一定会被释放。这个方式写起来比手写__enter__/__exit__类要轻量得多我写临时资源管理时几乎总是优先用contextmanager。但如果你需要非常精细的异常处理逻辑比如区分异常类型再决定是否吞掉手写类会更合适。讲到这里常见的几大类魔术方法已经覆盖了大半。但我在实际工作和带人的过程中发现真正能区分掌握魔术方法和只是背过魔术方法的往往是那些边界条件和组合效应。很多人看起来每个方法都见过写代码时却不断掉进同样的坑里。所以在最后这半部分我会把最常见也最危险的几个坑集中梳理一遍然后给出排查方法和一个完整的重构案例。8. 与魔术方法相关的五大常见误区这部分是我最想写的因为绝大多数魔术方法好难的抱怨其实都来自这几个典型误区而不是方法本身复杂。我按踩坑频率从高到低排个序基本上你把这些坑都认清日常写代码的自信心能涨一大截。8.1 误区一靠记忆硬背方法名单初学 Python 时很多人会去背那一长串双下划线方法的名称和触发条件结果今天背明天忘。其实正确做法是带着场景去学。比如你写了一个配置类想让它支持config[key]的读取方式自然就需要__getitem__你想让它支持with config:进入上下文自然就需要__enter__/__exit__。以需求驱动方法名只是顺手记住的结果。如果确实需要查全量名单建议直接看官方文档 data model 章节里面有完整的触发条件和示例。把文档当词典而不是教材效率会高很多。我自己也从来不会去背完整方法表但每个高频方法的语义和触发链都了然于胸因为每天都在用。8.2 误区二在业务类里重写内置类型的魔术方法有些同学读了几篇重写add实现向量相加的文章后就在订单类里重写add试图让两个订单对象直接相加。这种写法在技术上可行但会让代码的可读性和可维护性大幅下降。魔术方法的核心价值是让自定义类型参与到 Python 的语言级语法中而不是让你把所有业务逻辑都塞进运算符里。更合理的做法是只在类型确实像某种内置类型数值、容器、上下文管理器、迭代器时才考虑实现对应的魔术方法否则就用普通方法如order.merge(other)表达语义会更清晰。判断标准很简单a b这行代码一个不熟悉内部实现的人能不能一眼看出它是什么意思如果不能那你就是在滥用运算符重载。8.3 误区三分不清__str__和__repr__这是出现频率极高的问题也是面试爱问的。简单说__repr__面向开发者目标是无歧义__str__面向用户目标是可读。一个常见的实践是只实现__repr__因为当对象没有__str__时print 会回退到__repr__而且在调试、日志、交互式终端中使用的都是__repr__。class Point: def __repr__(self): return fPoint(x{self.x}, y{self.y})如果坚持只实现其中一个优先__repr__这是 Python 社区的普遍建议。你在 DEBUG 时看到的信息量会完全不同。比如一个列表里放了十个对象如果实现了__repr__你一眼能看到每个对象的类型和关键属性如果没实现你看到的是一堆__main__.Foo object at 0x...还得一个个去查效率天差地别。8.4 误区四覆盖__eq__却忘了__hash__自定义类如果只重写__eq__而不处理__hash__对象放进 set 或作为 dict 的 key 时会非常危险。Python 的规则是类中一旦定义了__eq__该类的__hash__会被自动设为 None也就是不可哈希。如果你希望对象既支持等值比较又支持哈希需要同时实现两者并且保证相等对象的哈希值相同。class Money: def __init__(self, amount, currency): self.amount amount self.currency currency def __eq__(self, other): if not isinstance(other, Money): return NotImplemented return (self.amount, self.currency) (other.amount, other.currency) def __hash__(self): return hash((self.amount, self.currency))这里的经验是做实体类时明确这两点比堆功能更重要因为这直接关系到对象能否安全地用于集合去重和缓存键。还有一个细节__eq__里遇到类型不匹配的other时应该返回NotImplemented而不是直接return False这样能让解释器有机会尝试对方的反向比较方法避免在两个不同类型对象比较时给出不准确的结果。8.5 误区五做了一层能跑就停止深挖很多人在实现了一个魔术方法、跑通测试后就觉得自己掌握了它。实际上很多魔术方法都有边界条件和组合效应。比如__getattr__和__getattribute__如何避免无限递归__getitem__对负索引和切片参数的处理__enter__返回值与 with 语句 as 变量的关系。真正深入的标准是能解释清楚这个方法的调用链、异常路径和退化行为这才叫掌握。如果时间有限我的建议是优先吃透最常遇到的十个左右方法把它们的各种边界情况逐一验证。搞懂十个方法背后的机制比囫囵吞枣地把三十个方法名背下来收获更大。因为大部分方法之间的关系是相互联动的你真正理解了__getitem____iter__的退化机制自然就懂了理解了__eq____hash__的存在意义也就顺理成章了。9. 调试与排查如何快速定位是哪个魔术方法在生效魔术方法最大的特点就是隐式调用。你写的是obj[key]实际执行的是obj.__getitem__(key)。当程序出错时报错栈里其实给了你非常直接的线索关键是你得知道怎么读。9.1 从报错栈里读出的线索Python 在调用魔术方法时报错栈顶层往往直接显示方法名。比如在 Jupyter 中写df[df[a] 1]报错栈里会显示__getitem__相关帧当自定义对象打印乱码时第一反应应该是查看它有没有实现__repr__。这是排查的第一步从异常信息反推哪个协议方法被触发了。更隐蔽的情况是隐式调用链。例如for x in obj会先尝试__iter__没有则退化为调用__getitem__(0)、__getitem__(1)直到IndexError。理解这一退化机制能帮你解释很多看似没定义却能用的现象。某次我在排查一个可迭代对象为何性能奇差时发现它没有实现__iter__每次循环都通过__getitem__逐一下标访问浪费了大量时间。加了__iter__后性能直接提升了一个数量级。9.2 在魔术方法里下断点写单元测试或调试时给魔术方法加日志或断点是最直接的方式。例如def __getitem__(self, key): print(f[DEBUG] __getitem__ called with key{key}) return self.data[key]这种方法在排查 CRUD 框架或 ORM 的查询缓存问题时特别有效。你很快会发现框架在背后悄悄调用了无数次__getitem__从而定位性能瓶颈或意外触发的路径。我在某次排查线上接口响应变慢时就是靠给__getitem__加日志发现了问题一个看起来只做了一次索引访问的地方实际在框架内部触发了上百次下标操作。9.3 绕过魔术方法直接访问底层在某些需要规避自定义逻辑的场景下可以用object.__getattribute__(obj, attr)跳过重写后的行为。这个技巧在元编程、序列化、深拷贝等场景中很有用但也要谨慎使用。绕过魔术方法意味着丢弃了自定义类型的所有保护性逻辑容易引入隐患。比如你明明实现了属性校验序列化时直接绕过了等于把校验拱手让出。另外想查看一个对象当前实现了哪些魔术方法可以配合dir()或者inspect.getmembers()检查。面对为什么这个对象能使用切片但另一个不行这类问题用dir()对比两个对象的属性列表往往一眼就能看出差异。这个排查思路比翻文档更快因为对象是活的dir()给你的是这一时刻最真实的答案。10. 生产环境中的真实案例用魔术方法重构一段糟糕代码理论讲再多不如看一次真实项目的重构过程。下面这个案例来自一个模拟数据同步模块我给它做了脱敏处理但核心逻辑完全保留。这段代码的糟糕之处、重构思路和最终收益应该能让你直观感受到魔术方法在实战中的价值。10.1 背景一段令人头疼的 if-else 长函数某系统负责把内部数据同步到外部平台其中有一段核心函数专门负责将不同来源的字段映射成目标平台要求的嵌套字典。当时的代码是这样的根据source_type写了一大段if-else每个分支里都手工构造 dict缩进越来越深新增一个来源就要在函数里再添一个分支测试时几乎要把整个函数跑一遍才知道改没改坏。def build_payload(source_type, data): if source_type order: return { order_id: data[id], amount: data[total], items: [{name: i[name]} for i in data[items]], } elif source_type user: return { user_id: data[uid], name: data[nickname], } elif source_type refund: return { refund_id: data[rid], reason: data[reason], } # 每新增一个来源就多一个 elif这段代码的问题很明显横向蔓延、重复模式多、难以单测、新增成本高。每个分支都是把一种业务数据翻译成另一种结构它本质上就是一个映射协议问题。正因为它具有按类型分发 返回统一结构的特征非常适合用__call__和__getitem__重构。10.2 重构用__call__和__getitem__建立统一的映射协议重构方案是定义一个PayloadBuilder类让不同来源的构建规则注册到同一套映射协议上。类本身实现__call__使实例可以像函数一样被调用内部用__getitem__支持按source_type获取对应的构建器。新增一种来源时不需要改动现有函数只需要注册一个新的构建规则。class PayloadBuilder: def __init__(self): self._builders {} def register(self, source_type, builder): self._builders[source_type] builder def __getitem__(self, source_type): return self._builders[source_type] def __call__(self, source_type, data): builder self._builders[source_type] return builder(data) builder PayloadBuilder() builder.register(order, lambda d: { order_id: d[id], amount: d[total], }) builder.register(user, lambda d: { user_id: d[uid], name: d[nickname], }) builder.register(refund, lambda d: { refund_id: d[rid], reason: d[reason], })重构之后调用方只需payload builder(source_type, data)。新来源的扩展从修改函数变成注册规则单个规则的测试也可以独立进行。最关键的变化是业务语义从一大段if-else变成了清晰的注册模式代码行数减少、嵌套消失、可读性明显提升。10.3 收益与局限什么时候不该用这个模式这次重构带来的收益是实实在在的核心函数从 70 多行缩减到约 30 行新增来源的平均耗时从约半天降低到一小时内单测用例从覆盖所有分支变成逐个注册规则验证更容易写满覆盖率。但也要说清楚它的局限。如果映射规则彼此之间耦合极深、分支条件复杂例如 A 规则依赖 B 规则的输出那么强行统一协议反而会引入额外复杂度。魔术方法是工具不是银弹。用它的标准应该是让代码表达更贴近问题的本质而不是为了秀技巧。这个案例里之所以能成功是因为按类型构建统一负载结构这个需求本身就是一个天然的分发协议所以用__call__和__getitem__是顺理成章的选择。11. 总结与我的实操建议最后说点实在的。这个标题虽然是双下划线魔术方法但真正到了项目里你不需要记住全部。我这里列一下目前我在生产代码里最高频使用的清单供参考__init__/__new__对象生命周期控制__repr__调试信息可读性__eq__/__hash__实体对象比较与去重__getitem__/__setitem__/__len__/__iter__/__contains__自定义容器__enter__/__exit__资源管理与上下文__call__函数式接口封装__getattr__/__setattr__动态属性与拦截__str__用户可读输出__bool__/__format__条件判断与格式化学习方法上我个人的体会是不要死记方法大全而是找一个真实项目里让你不舒服的重复代码尝试用魔术方法来消除它。当你真的用__call__重构掉一段if-elif长链或者用__getitem__让数据访问变得像字典一样自然时这些方法在你的记忆里就再也丢不掉了。还有一个小技巧想分享给你。写自定义类时我会先问自己三个问题这个类的实例会被打印吗会被放进集合或作为字典 key 吗会被for遍历或用下标访问吗只要有一个回答是肯定的对应的__repr__、__eq__/__hash__、__iter__/__getitem__就该被安排上。这种从使用场景反推方法的思路比看着方法大全无从下手要高效得多。双下划线魔术方法的核心是让你的对象更懂 Python 的语法。这个标题背后真正要传达的就是这件事。理解到这一层双下划线就不再是玄学而是顺手好用的语言级工具。希望这篇长文能帮你跳过那些我踩过的坑直接站到会用、敢用、用得对的层次上来。