写Python写了几年我越来越觉得判断一个人是不是真的理解这门语言最好的方式就是看他怎么对待双下划线方法。就拿__getitem__和__len__来说很多同学知道它们是让对象支持[]和len()的魔法方法但真到项目里要么不知道怎么用要么用得漏洞百出。这篇文章我想把它们彻底讲透包括背后的协议机制、真实业务场景、从零实现的完整步骤以及我这些年踩过的坑。适合正在学python3基础的初学者也适合想把手头数据类封装得更优雅的进阶开发者。先讲个我自己遇到的案例。前年接手一个数据处理项目同事把一组股票行情数据封装成了一个类内部存的是列表结果外层代码写了data[0][close]一跑直接报错TypeError: StockData object is not subscriptable。我当时的反应就一句话这个类没实现__getitem__。发现问题后五分钟就改完了但同事一脸懵他压根没想到自己定义的类也可以像列表一样用方括号取值。这正是我要写这篇文章的原因。1. 先搞清楚__getitem__和__len__在Python里到底扮演什么角色1.1 从方括号语法说起在Python里obj[key]这种写法并不是只有列表、字典、元组才能用。只要你定义的类实现了__getitem__方法那么实例就可以用方括号访问元素。同理实现了__len__方法之后len(obj)也就合法了。这是Python鸭子类型的一个典型体现不关心对象是什么类只关心对象有没有对应的行为。你可以把__getitem__理解为在类和方括号语法之间搭了一座桥。桥搭好了obj[0]、obj[1:5]、obj[name]全都由你的实现说了算。桥没搭好解释器就只能甩给你一个TypeError。1.2 为什么是双下划线协议是一种约定很多初学者看到__getitem__这串双下划线就觉得神秘。其实这个名字本身有它的含义__开头说明它是Python内部约定好的特殊方法由解释器在特定语法场景下自动调用而不是让你在业务代码里直接调用的。这里我特别强调一个点当你写obj[0]的时候解释器实际做的事情是调用type(obj).__getitem__(obj, 0)。注意是type(obj)也就是从对象的类上取方法而不是从实例上取。这么设计是有讲究的——即使你把实例属性给改了特殊方法依然会从类里找到正确的实现避免了很多诡异的问题。len(obj)同理解释器调用的是type(obj).__len__(obj)。这也是为什么len()是一个内置函数而不是列表的方法它被设计成对所有有长度的对象通用你总不能给每个类都各自发明一个size()、length()、count()吧Python选择了一个统一的入口这就是协议的价值。1.3 为什么有了__getitem__对象就自动能迭代这是很多教程没讲透的一个点。一个类只实现了__getitem__没有实现__iter__按理说它不是可迭代对象。但Python的迭代协议有一个回退机制for循环在迭代时如果找不到__iter__会退而求其次从0开始依次调用obj[0]、obj[1]、obj[2]直到__getitem__抛出IndexError才结束。换句话说只要实现了__getitem__你的对象就自动获得了被for循环遍历的能力x in obj这样的成员判断也能工作了。这个特性我后面会专门演示它既是便利也是隐患——一旦你的__getitem__越界时抛错了异常类型迭代可能就陷入了死循环。2. 实际开发中最常见的几种使用场景2.1 自定义容器类把业务数据变成可访问的数据集最常见的场景就是你有一个类内部封装了一批数据你希望外部代码能用一种自然的方式去读取。比如一个学生成绩册类内部存着所有学生的成绩你希望这样访问grades[0] # 第一个学生的成绩 grades[3:5] # 第3到第4个学生的成绩 len(grades) # 一共有多少条成绩这种需求在业务系统里非常普遍。Django的QuerySet就是典型代表你用queryset[0]取第一条记录用len(queryset)获取总数背后就是__getitem__和__len__在做支撑。你从后端取数据的时候没人关心它到底是不是列表只要能取能数就行。2.2 封装外部数据源懒加载与视图映射比容器更进一步的是对外部数据源的封装。比如你有一个非常大的CSV文件、数据库游标或者远程接口的分页数据你不可能一次性全部加载到内存里。这时候__getitem__就可以做成按需计算的懒加载模式class RemotePage: def __getitem__(self, index): # 根据index请求对应页码的数据 return fetch_page(pageindex // page_size)调用方只需要写data[3]完全不用关心底层是文件、数据库还是HTTP请求。这种封装在Pandas读取大文件、Astropy读取天文FITS数据时都能看到影子——它们把复杂的底层细节隐藏在了方括号语法背后。2.3 无限序列与虚拟序列有些序列在数学上是无限的没法用列表存但你可以用__getitem__按需计算。最经典的例子是斐波那契数列class Fib: def __getitem__(self, i): if i 0: raise IndexError(negative index not supported) a, b 0, 1 for _ in range(i): a, b b, a b return a fib Fib() print(fib[10]) # 55注意这个类我没有实现__len__因为它是无限序列没有长度可言。如果你强行实现__len__要么返回一个固定值要么返回一个巨大到离谱的数字这在语义上都是别扭的。所以记住__getitem__和__len__不一定成对出现要根据你的数据语义来决定。2.4 与内置机制的联动in、切片、reversed、解包自动获得一个类只要实现了__getitem__和__len__很多Python内置操作会自动生效。这里我列一个对照表方便你直观感受操作依赖的特殊方法是否必须成对obj[key]__getitem__单独即可obj[1:5]__getitem__收到slice对象单独即可len(obj)__len__单独即可for x in obj__getitem__回退机制有__getitem__即可x in obj__getitem__迭代查找有__getitem__即可reversed(obj)__len____getitem__需要同时实现bool(obj)__len__回退机制有__len__即可a, b, c obj__getitem__单独即可这个表格的价值在于你不需要去记Python的文档只需要理解协议会触发一系列联动行为。这就像你办了一张健身卡不仅能用跑步机游泳池、团操课也都能用。理解了这个你写出来的类才会真正融入Python的生态而不是一个孤立的假对象。2.5 大库中的影子Pandas、Astropy是怎么想的热词里有人搜python3 pandas和python3 astropy库详解我顺带提一嘴。Pandas的Series和DataFrame你用df[column]取列、用df.iloc[0]取行本质上就是__getitem__的极致应用。但Pandas做的比基础版复杂得多它在__getitem__内部实现了一套索引对齐、标签解析、布尔掩码的逻辑。Astropy读取天文数据的时候fits_data[0]拿到第一层HDUheader[NAXIS]拿到关键字值走的也是同一套协议。你看大牛们并不是发明了什么黑魔法他们只是把Python的协议机制用到了极致。这也是为什么我建议你认真学好这两个方法——它是你理解整个Python数据生态的地基。3. 实操拆解从零实现一个行情数据集类3.1 需求设定明确要支持的访问方式光说不练假把式。这一节我们完整实现一个可以直接抄作业的数据集类。需求是这样的我们做一个本地行情数据集MarketData内部是一个二维表格结构每行是一天的行情记录包含date、open、close、volume四个字段。我希望它支持以下几种访问方式data[0] # 第一天的完整记录 data[0][close] # 第一天的收盘价 data[1:3] # 切片取第二天到第三天的记录 len(data) # 总天数 data[close] # 取所有天的收盘价按列取这个需求模拟的是小型量化分析中常见的内存数据集结构。之所以不用Pandas的DataFrame是因为我希望你把底层原理看清楚——一旦你理解了原理以后用DataFrame、Astropy还是自己造轮子心里都有底。3.2 第一版最简实现先把协议跑通第一版不求功能全先把两个协议方法实现出来让最基本的[]和len()能用class MarketData: def __init__(self, rows): self._rows rows # 每行是一个dict def __len__(self): return len(self._rows) def __getitem__(self, key): return self._rows[key]就这么几行调用方已经可以做这些事md MarketData([ {date: 2024-01-02, open: 10.0, close: 10.5, volume: 10000}, {date: 2024-01-03, open: 10.5, close: 10.2, volume: 12000}, ]) len(md) # 2 md[0] # {date: 2024-01-02, ...} md[0][close] # 10.5 md[1:] # 切片自动可用为什么把key直接传给内部的self._rows就行因为_rows是一个列表列表本身已经实现了完整的__getitem__协议包括切片、负索引、越界抛IndexError。这种委托给内部对象的做法是自定义容器类最偷懒也最不容易出错的写法。记住这个思路能用别人已经实现好的协议就别自己硬造。3.3 增强支持列名访问和二维取数但第一版有个问题data[close]会直接报错因为传给__getitem__的key是字符串close内部列表收到字符串当然不认识。所以第二版要自己判断key的类型class MarketData: def __init__(self, rows, columns): self._rows rows self._columns list(columns) def __len__(self): return len(self._rows) def _get_column(self, col_name): if col_name not in self._columns: raise KeyError(col_name) idx self._columns.index(col_name) return [row[idx] for row in self._rows] def __getitem__(self, key): if isinstance(key, str): return self._get_column(key) return self._rows[key]这里我做了两个关键设计第一columns在初始化时单独传进来并转成列表。这样内部数据_rows不一定要用dict可以直接存元组节省内存性能也更好。很多做量化的人会用array或者numpy.ndarray存行情列名单独维护一套这是一个很常见的工程取舍。第二字符串key走取列逻辑其他情况走取行逻辑。这样data[close]能取到所有天的收盘价data[0]能取到第一天的完整记录。如果你还想支持data[0, close]这种二维写法可以在__getitem__里再判断key是不是tupledef __getitem__(self, key): if isinstance(key, tuple): row_key, col_key key row self._rows[row_key] if isinstance(col_key, str): idx self._columns.index(col_key) return row[idx] return tuple(row[col_key] for col_key in col_key) if isinstance(key, str): return self._get_column(key) return self._rows[key]这样data[0, close]就返回第一天的收盘价data[0, (open, close)]返回第一天的开收两条记录。这种设计在Pandas里叫轴对齐在Astropy里叫多维访问本质都是在一个入口方法里做类型分发。3.4 边界与性能负索引、越界、缓存增强版功能是多了但有几个坑必须提前处理。第一个是负索引。data[-1]取最后一天这个行为由内部列表自动支持没问题。但如果你内部存的是numpy.ndarray负索引也天然支持。可如果你自己实现了一个存储结构比如用两个数组分别存表头和列数据那负索引就得自己处理了。我建议一开始就明确语义支持负索引还是不支持如果不支持记得在__getitem__里对负数直接抛IndexError否则会埋下隐性bug。第二个是越界。列表越界会自动抛IndexError这正好符合Python迭代协议的要求。但如果你在__getitem__里先做了一步转换再取值比如把字符串转成列索引发现列名不存在时抛的是KeyError这时候要区分清楚行越界是IndexError列不存在是KeyError两种异常语义不一样后面我会专门讲。第三个是性能。如果你的_get_column方法每次都对所有行做一次遍历在数据量大时就会很慢。一个常见的优化是加缓存def __init__(self, rows, columns): self._rows rows self._columns list(columns) self._column_cache {} def _get_column(self, col_name): if col_name in self._column_cache: return self._column_cache[col_name] if col_name not in self._columns: raise KeyError(col_name) idx self._columns.index(col_name) result [row[idx] for row in self._rows] self._column_cache[col_name] result return result这是用空间换时间。行情数据通常列数少、行数多缓存的收益非常明显。我在实际项目中一个包含几十万行数据的类加了缓存之后取列操作从几十毫秒降到微秒级。4. 实战中容易踩的坑与排查技巧4.1 迭代无限循环的罪魁祸首越界抛错写错了这是我见过最隐蔽的bug。前面说过for循环在没有__iter__时会回退到__getitem__的索引迭代。这个回退机制依赖一个前提越界时__getitem__必须抛出IndexError。假设你写成了这样def __getitem__(self, index): try: return self._rows[index] except IndexError: return None # 错误越界应该抛异常而不是返回None调用for item in obj时Python会一直问obj[0]、obj[1]、obj[2]……每次越界你都返回None它以为还能继续于是循环永远不会结束最后拿到一堆None。我在排查一个数据管道问题时整整花了半天才定位到是这个原因。所以记住越界就抛IndexError不要返回None更不要返回一个默认值。4.2__len__返回值的坑整数、大小与bool判断__len__的返回值必须是整数不能是浮点数、字符串、None否则len(obj)会直接抛TypeError。这个错误通常一跑就能发现问题不大。但有一个坑是隐性的bool(obj)在没有__bool__方法时会回退到__len__来判断真假。也就是说if obj:等价于if len(obj) 0。如果你实现的__len__做了耗时计算比如统计数据库中的条目数那if obj:就会触发一次全表统计。我的建议是如果判断非空是高频操作额外实现一个__bool__方法来短路判断这样def __bool__(self): return len(self._rows) 0另外__len__的返回值也不能是负数否则bool(obj)的结果会不符合直觉。Python把长度定义为非负整数这是语言层面的约定别去破坏它。4.3 切片忘处理TypeError: unhashable type: slice写自定义容器时初学者最常见的报错就是TypeError: unhashable type: slice。原因很简单obj[1:3]传进来的key是一个slice对象如果你在__getitem__里把这个slice对象当普通键拿去索引一个字典字典就会因为slice不可哈希而报错。解决方案也简单在__getitem__开头判断isinstance(key, slice)单独处理切片逻辑。或者更省事的做法是像我之前展示的把key原样转发给内部列表——列表已经处理好了slice对象。但如果你内部结构不是列表比如是字典那就要自己写切片逻辑了def __getitem__(self, key): if isinstance(key, slice): indices range(*key.indices(len(self))) return [self._rows[i] for i in indices] return self._rows[key]这里用到slice.indices(length)方法它会根据切片的start、stop、step和序列长度算出一组具体索引。这是一个冷门但极其实用的API我推荐大家都去文档里看一眼。4.4 异常语义混乱IndexError与KeyError别混用Python的容器类有一个约定俗成的语义列表用IndexError表示索引越界字典用KeyError表示键不存在。自定义类也应该遵循这个约定因为你无法预料调用方会怎么处理你的异常。举个例子如果你在__getitem__里对所有错误都统一抛KeyError而调用方用for循环遍历你的对象循环机制期待的是IndexError结果拿到KeyError迭代不会正常终止。反过来如果你在实现一个字典风格的类时越界抛了IndexError调用方用d.get(key)的思维去写try...except KeyError就会漏掉异常。我的建议是在__getitem__里区分好key的来源。索引取行、整数越界就抛IndexError字符串取列、列名不存在就抛KeyError。这样两个语义各归各的调用方好处理你的代码也更清晰。4.5 in操作符失灵异常类型不匹配in操作符判断成员关系时如果对象没有实现__contains__Python会通过迭代逐个比较。而迭代又会走__getitem__的索引协议。这意味着如果__getitem__越界时抛的不是IndexErrorin操作符也会出错。比如你写了一个__getitem__越界时抛ValueError(index out of range)那么abc in obj会直接把这个ValueError抛给调用方而不是返回False。这个错误很隐蔽因为代码在平时取值时完全正常只有用in判断时才暴露。我在给一个配置类加成员判断功能时踩过这个坑。所以再次强调__getitem__越界永远抛IndexError这是Python数据模型的基石之一。4.6 性能隐患每次访问都重复计算如果一个类的__getitem__每次都要从磁盘读取、从网络请求、或者做一次全量遍历那么即使功能正确性能也可能差到不可用。我见过一个同事做的日志解析类每次obj[i]都把整个日志文件重新解析一遍取100条数据花了半分钟。优化的思路有三个层次。第一层是加缓存已经计算过的结果存起来这个我在前面演示过。第二层是预计算在初始化时把数据一次性加载好__getitem__只做内存索引。第三层是改变存储结构比如把列表换成numpy数组把字典换成哈希索引。具体用哪种取决于你的数据是读多写少还是写多读少。我的个人经验是90%的场景加个缓存就够用了别过度设计。4.7 快速排查清单最后整理一个速查表遇到问题可以对照检查现象可能原因排查方向TypeError: object is not subscriptable类没实现__getitem__在类中补充方法for循环无限执行__getitem__越界未抛IndexError检查越界分支len(obj)报TypeError__len__返回了非整数检查返回值obj[1:3]报unhashable type切片key未处理增加slice类型判断in判断结果异常迭代协议被异常类型干扰统一越界异常为IndexError数据量大的时候访问慢__getitem__重复计算引入缓存或优化存储5. 我的使用心得与扩展建议写到这里我想分享一个自己的习惯现在我设计任何数据类都会先问三个问题——这个对象能被len()测量吗能通过[]取到某个具体元素吗取到的元素是什么类型、什么语义如果三个问题中有一个答案是能我就会认真考虑实现__getitem__或__len__而不是让调用方去访问什么obj.data[0]之类的内部属性。这种设计思路带来的好处是明显的。最直接的一点是它让类和Python内置语法无缝衔接。你不需要为每一个类发明一套取值API[]和len()就是整个语言通用的约定。调用方不用去看你的类文档就知道怎么拿到数据、怎么判断数据量这降低了团队协作的沟通成本。另外我想强调一个容易被忽略的点__getitem__和__len__不是一个锦上添花的加分项而是雪中送炭的基础设施。我参与过的项目中凡是数据模型封装得好的模块几乎都正确实现了这两个方法凡是让人用得难受的类十有八九是让调用方在外部剥好几层才能拿到数据。Python的协议机制给了我们一个非常优雅的工具问题只在于你愿不愿意把这一层设计做好。如果这篇文章对你有帮助我建议你接下来做两件事第一打开手头某个数据类看看它能不能用len()和[]直接操作不能的话尝试加上第二试着自己写一个带缓存、支持切片、支持列名访问的容器类把今天我讲的坑都踩一遍。写代码这件事看十篇不如动手一遍特别是协议方法这种语法糖背后的机制只有亲手改过代码、亲眼见过报错才能真正把它变成自己的东西。
