1. 从一行 print 说起为什么你的对象输出是“天书”很多刚上手 Python 的朋友都踩过同一个坑辛辛苦苦定义了一个类实例化之后想打印出来看看里面到底装了什么结果终端里蹦出来一行__main__.Point object at 0x7f8b1c0a3d90。这串东西除了能看出它是个对象、大概在内存哪个位置之外几乎没有任何信息量。你想要的可能是Point(x3, y5)这种一眼就能看懂的结果但 Python 默认给你的却是这串“天书”。这个问题的根源就在于 Python 的魔术方法Magic Method也叫双下划线方法、Dunder Method没有被正确实现。所谓魔术方法就是那些以双下划线开头和结尾的特殊方法比如__init__、__str__、__repr__、__len__等等。它们不是你主动去调用的而是 Python 在特定场景下自动触发的。打印对象这件事背后触发的就是__str__和__repr__这两个方法。这篇文章我想聊的就是这个看似很小、但实际影响很大的话题如何通过实现魔术方法让你的对象实例打印出来是人话而不是天书。内容会从最基础的__str__和__repr__讲起一路延伸到__format__、调试场景下的取舍、以及我在实际项目里踩过的那些坑。不管你是刚学完类和对象的新手还是写了几年 Python 但一直没认真研究过魔术方法的老手相信都能从中拿到一些可以直接抄作业的东西。先说清楚适用人群如果你写过class关键字、知道什么是实例化、能看懂self的含义那这篇文章你就能顺畅读下去。如果你连类都还没定义过建议先把基础语法过一遍再回来不然有些地方会有点吃力。整篇内容我会尽量用生活化的类比来解释同时给出可以直接复制运行的代码保证你看完就能动手改自己的项目。2. 打印对象背后的机制str与repr到底谁在干活2.1 一次 print 调用到底经历了什么要搞清楚为什么打印出来是“天书”得先弄明白print(obj)这一行代码在底层做了什么。流程大致是这样的print函数接收到一个对象后会去调用内置的str()函数把它转成字符串而str()又会去找这个对象所属类里有没有定义__str__方法。如果定义了就用它的返回值如果没定义Python 会退而求其次去找__repr__如果连__repr__也没定义那就只能使用object基类提供的默认实现也就是那串类名 object at 内存地址。这里有个关键点很多人会忽略__str__没定义时会回退到__repr__但反过来不成立。也就是说如果你只定义了__repr__那么print()和直接在交互式环境里敲对象名输出是一样的但如果你只定义了__str__那么在交互式环境里直接敲对象名看到的还是那串“天书”因为交互式环境用的是repr()而不是str()。我用一个简单的例子来说明这个回退关系。假设定义了一个Book类只实现__repr__class Book: def __init__(self, title, pages): self.title title self.pages pages def __repr__(self): return fBook(title{self.title!r}, pages{self.pages}) b Book(Python入门, 320) print(b) # 输出 Book(titlePython入门, pages320) b # 交互式环境同样输出 Book(titlePython入门, pages320)可以看到只实现__repr__的情况下print和交互式输出是一致的。这就是为什么很多教程会建议如果你只想实现一个那就实现__repr__因为它能覆盖更多场景。2.2str和repr的定位差异虽然两者都能控制对象的字符串表现但它们的设计意图是不一样的这一点在 Python 官方文档里有明确说明但很多人没注意到。__str__面向的是最终用户追求的是可读性。比如一个日期对象__str__返回2024-01-15就很合适用户一看就懂。而__repr__面向的是开发者追求的是准确性和无歧义理想情况下它的返回值应该是一段能够重新创建这个对象的代码。还是日期对象__repr__可能返回datetime.date(2024, 1, 15)这样开发者一看就知道怎么构造出同样的对象。用生活化的类比来说__str__像是商品的外包装说明写给消费者看的通俗易懂__repr__像是商品的内部规格标签写给工程师看的精确到型号参数。两者服务对象不同所以内容风格也应该不同。我在实际项目里总结出一条经验法则__repr__尽量做到“可重建”__str__尽量做到“好阅读”。如果两者内容恰好一样那完全可以只写__repr__然后让__str__ __repr__省得重复。但如果你的对象有复杂的内部状态两者还是分开写更合适。2.3 默认实现为什么长那样object基类提供的默认__repr__实现返回的格式是模块名.类名 object at 十六进制地址。这个设计其实是有意为之的它明确告诉你“这是一个对象位于某个内存地址”但故意不暴露任何内部状态。这样做的好处是安全——不会因为打印一个对象就泄露敏感数据坏处就是调试时非常不方便。理解了这一点你就明白为什么自定义__repr__是调试效率的关键。每次你在调试器里看到一堆xxx object at 0x...都得手动去展开属性那效率低得让人抓狂。花五分钟给核心类加上__repr__能省下后面无数次的调试时间这笔账怎么算都划算。3. 动手实现给自定义类加上可读的打印输出3.1 最小可用版本三行代码搞定先看一个最朴素的实现。假设我们在做一个几何计算的小工具定义了一个表示点的类class Point: def __init__(self, x, y): self.x x self.y y def __repr__(self): return fPoint(x{self.x}, y{self.y})就这么三行效果立竿见影p Point(3, 5) print(p) # Point(x3, y5)对比一下不加__repr__时的输出__main__.Point object at 0x7f...可读性提升不是一点半点。这里用了 f-string把属性值直接嵌进去格式清晰。注意我在属性值两边加了x和y这样的标签这样即使属性多了也不会看混。有个细节值得说一下f-string 里的!r转换符。如果你写fPoint(x{self.x!r}, y{self.y!r})那么字符串属性会带上引号比如Point(xa, yb)这样能区分字符串和数字。对于调试用途我强烈建议加上!r因为它能避免“字符串3和数字3看起来一样”这种歧义。这个小技巧在排查类型相关的 bug 时特别有用。3.2 处理嵌套对象让打印结果层层展开单个对象好办但如果对象里嵌套了另一个自定义对象呢比如一个Rectangle类内部持有两个Point对象class Rectangle: def __init__(self, top_left, bottom_right): self.top_left top_left self.bottom_right bottom_right def __repr__(self): return fRectangle(top_left{self.top_left!r}, bottom_right{self.bottom_right!r})因为Point已经实现了__repr__所以Rectangle的打印结果会自动层层展开r Rectangle(Point(0, 10), Point(10, 0)) print(r) # Rectangle(top_leftPoint(x0, y10), bottom_rightPoint(x10, y0))这就是实现__repr__的复利效应你只需要在每个类里各写一次嵌套结构就能自动获得可读的输出。如果Point没实现__repr__那Rectangle打印出来就会夹杂着__main__.Point object at 0x...非常难看。这里有个坑要提醒嵌套层级过深时__repr__可能触发无限递归。比如一个对象持有对自身的引用或者两个对象互相引用直接递归调用repr()会导致栈溢出。解决办法是在__repr__里用reprlib.recursive_repr装饰器或者手动控制递归深度。这个后面在问题排查章节会详细讲。3.3 用 dataclass 自动生成省事的现代写法如果你用的是 Python 3.7 及以上版本那有个更省事的办法dataclasses模块会自动帮你生成__repr__。看代码from dataclasses import dataclass dataclass class Point: x: int y: int就这么几行Point(3, 5)打印出来就是Point(x3, y5)和手写的效果一模一样。dataclass默认会生成__repr__而且格式相当规范。如果你不想要自动生成的可以传reprFalse关掉。不过dataclass也不是万能的。它的自动__repr__只包含字段不包含计算属性如果你的类有复杂的初始化逻辑或者需要隐藏某些敏感字段还是得手写。另外dataclass生成的__repr__默认不带!r字符串字段打印出来不带引号这点和手写时加!r的习惯略有差异需要留意。我个人的选择标准是纯数据容器用dataclass有行为逻辑的类手写__repr__。前者省事后者可控。4. 进阶玩法format与格式化输出4.1 为什么还需要format__str__和__repr__解决的是“打印出来长什么样”但如果你用过 f-string 的格式说明符比如f{value:.2f}就会遇到另一个问题自定义对象能不能支持格式说明符答案是能但需要实现__format__方法。默认情况下object基类的__format__会忽略格式说明符直接返回str(self)。也就是说如果你写f{p:20}期望右对齐宽度 20但实际输出还是str(p)格式说明符被无声无息地丢掉了。要实现真正的格式化就得自己写__format__。4.2 一个支持格式说明符的实现还是用Point举例假设我们希望支持f{p:.1f}这样的精度控制让坐标保留一位小数class Point: def __init__(self, x, y): self.x x self.y y def __repr__(self): return fPoint(x{self.x!r}, y{self.y!r}) def __format__(self, spec): if spec : return str(self) # 把格式说明符分别应用到 x 和 y 上 return f({format(self.x, spec)}, {format(self.y, spec)}) def __str__(self): return f({self.x}, {self.y})测试一下p Point(3.14159, 2.71828) print(f{p}) # (3.14159, 2.71828) print(f{p:.2f}) # (3.14, 2.72) print(f{p:20}) # 整个字符串右对齐到宽度 20这个实现的关键在于把接收到的spec透传给内部的数值让数值自己去处理格式化。这样Point就自动支持了所有数值类型支持的格式说明符扩展性很好。4.3 格式说明符的解析技巧__format__接收的spec是一个字符串可能包含填充字符、对齐方式、宽度、精度、类型码等多个部分。如果你想让自定义对象支持更复杂的格式比如f{p:10.2f}这种组合就需要解析这个字符串。Python 标准库里的string模块提供了一个Formatter类可以帮你解析格式说明符。不过对于大多数场景直接把spec透传给内部数值就够了不需要自己解析。只有当你想对不同的部分做不同处理时才需要手动解析。这里分享一个我踩过的坑__format__里不要忘记处理空字符串的情况。当用户写f{p}不带任何格式说明符时spec是空字符串。如果你直接format(self.x, )对于数字类型是没问题的但对于某些自定义类型可能会报错。稳妥的做法是先判断spec是否为空为空时返回str(self)。5. 调试场景下的取舍什么时候该用哪个5.1 调试器里的表现差异在调试器比如 pdb 或者 IDE 内置的调试面板里查看对象时用的通常是repr()而不是str()。这意味着如果你只实现了__str__调试器里看到的还是那串“天书”。这一点非常关键因为很多人写完__str__就觉得万事大吉了结果调试时依然一脸懵。所以我的建议很明确优先实现__repr__。它覆盖的场景更广包括调试器、容器打印、日志输出等。__str__可以作为补充在需要面向最终用户展示时提供更友好的格式。5.2 日志输出中的选择写日志的时候用%r还是%s也是个小有讲究的问题。%r调用的是repr()%s调用的是str()。对于调试日志我倾向于用%r因为它能暴露更多细节比如字符串的引号、类型信息等。对于面向用户的日志用%s更合适。举个实际例子假设你在记录一个用户对象__repr__返回User(id42, name张三)__str__返回张三。调试日志里用%r能看到 id方便定位问题用户日志里用%s只显示名字更简洁。5.3 敏感信息的处理这里要特别提醒一个安全问题__repr__里不要包含敏感信息。因为__repr__会在很多你意想不到的地方被调用比如异常堆栈、调试器、日志系统。如果你的对象持有密码、令牌之类的敏感字段直接放进__repr__里可能会导致信息泄露。正确的做法是在__repr__里对这些字段做脱敏处理比如显示成password***。或者干脆不包含这些字段。这一点在写涉及认证、支付的代码时尤其重要我见过不止一个项目因为__repr__泄露了敏感数据而出了问题。6. 常见问题与排查技巧实录6.1 打印出来还是“天书”怎么办这是最常见的问题。排查思路按顺序来第一确认你实现的方法名拼写正确。是__repr__不是__rep__是双下划线不是单下划线。Python 不会因为你拼错了就报错它只会默默地用默认实现。我见过有人写成_repr_调试了半天才发现。第二确认方法定义在正确的类里。如果你有继承关系子类没实现__repr__会继承父类的实现。如果父类的实现不合适子类需要覆盖。第三确认你打印的是实例而不是类。print(Point)打印的是类对象用的是type的__repr__和你定义的实例方法无关。要打印实例得用print(Point(3, 5))。第四检查是否有__slots__或者元类干扰。某些高级用法可能会影响方法查找不过这种情况比较少见。6.2 递归调用导致栈溢出前面提到过嵌套对象互相引用时__repr__可能无限递归。看这个例子class Node: def __init__(self, name): self.name name self.parent None def __repr__(self): return fNode(name{self.name!r}, parent{self.parent!r})如果两个节点互相设为对方的 parent打印时就会无限递归。解决办法是用reprlib.recursive_repr装饰器from reprlib import recursive_repr class Node: def __init__(self, name): self.name name self.parent None recursive_repr() def __repr__(self): return fNode(name{self.name!r}, parent{self.parent!r})这个装饰器会检测递归调用第二次进入时返回...避免栈溢出。这个技巧在处理树形结构、图结构时特别有用。6.3 性能问题repr写得太重__repr__会在很多地方被调用如果里面做了耗时操作比如查数据库、读文件、复杂计算会严重拖慢程序。我见过有人在__repr__里做了一次网络请求结果日志系统一打印就卡住。原则很简单__repr__只做字符串拼接不做任何副作用操作。它应该是纯函数快速返回。如果需要展示复杂信息可以在__repr__里只放关键字段详细信息通过其他方法获取。6.4 常见问题速查表问题现象可能原因解决办法打印出来是xxx object at 0x...没实现__repr__或__str__实现__repr__交互式环境是“天书”print 正常只实现了__str__补上__repr__格式说明符被忽略没实现__format__实现__format__并透传 spec打印时栈溢出对象循环引用用recursive_repr装饰器日志打印很慢__repr__里有耗时操作移除副作用只做拼接敏感信息泄露__repr__包含敏感字段脱敏或排除敏感字段7. 我在实际项目中的几点体会聊了这么多技术细节最后分享几个我在实际项目里总结的经验都是踩过坑之后才明白的。第一个体会是给核心数据类加__repr__的投入产出比极高。一个项目里真正需要__repr__的类可能就十几个每个花五分钟写一下后面调试时省下的时间是以小时计的。我现在养成了一个习惯定义完一个类之后顺手就把__repr__写上已经成为肌肉记忆了。第二个体会是__repr__的格式要统一。如果一个项目里有的类写成Point(3, 5)有的写成Point x3 y5看起来会很乱。我一般统一用类名(字段值, 字段值)的格式和dataclass的默认风格保持一致这样整个项目的输出风格是统一的。第三个体会是不要过度设计。有些人喜欢在__repr__里搞很多花活比如根据环境变量切换格式、动态计算字段等。这些都会增加复杂度和出错概率。__repr__就应该简单直接一眼能看懂就行。第四个体会是测试里可以断言__repr__。给__repr__写个单元测试确保格式符合预期。这样以后重构时如果不小心改坏了测试会立刻发现。这个习惯在团队协作中特别有价值因为别人可能不知道你精心设计的格式约定。关于后续扩展如果你对魔术方法感兴趣可以顺着这条线继续研究__eq__、__hash__、__lt__这些比较相关的魔术方法它们和__repr__一样都是让自定义对象融入 Python 生态的关键。把这些方法用好了你写的类用起来就和内置类型一样自然。