Python __index__ 深度解析：从 __int__ 到切片索引的无损整数协议

很多人在掌握 __int__ 之后，都会在一个地方栽跟头：明明自己的类已经能传给 int() 了，为什么扔进列表下标、range() 参数里，解释器还是甩过来一句 TypeError？这个问题的答案，往往就是 Python 整数协议体系里那个最低调、却最核心的方法：__index__。这篇聊透它，并顺带把 __index__ 和 __int__、__trunc__ 的关系理清楚。

__index__ 是 Python 魔术方法里少有的“系统级协议方法”。它不负责给人看，不负责数值展示，它负责的是让一个任意对象可以被解释器当成“精确整数索引”来使用。无论你是想写一个自定义的数值类型接入列表切片，还是想让自己的类被 range()、operator.index()、甚至 C 扩展里的下标逻辑接受，都得靠它。这就是为什么我把这期的主题放在 Python 3.12 MagicMethods 系列的第 72 个位置——它不是最常用的，却是最容易被误解的。

这篇内容会把这几个问题讲透：为什么 Python 要同时存在 __int__、__index__、__trunc__ 三种“转整数”协议；__index__ 从哪来、如何被 CPython 解释器调用；怎么给自己的类实现 __index__ 并接入真实项目；numpy 和自定义容器场景里它怎么工作；以及 Python 3.12 环境下实践时需要注意的细节和自查规则。

1. 三种“转整数”协议并存，index 为什么独立存在

1.1 int、index、trunc 各管什么

很多 Python 初学者会默认“只要对象能转成 int，就哪都能用”，但解释器的真实规则要严格得多。int(obj)、math.trunc(obj)、obj[n] 三者的底层协议并不互通，至少在语义上被刻意区分开了。

看下面这几个方法：

• __int__：面向“人类可读的数值转换”，允许有损转换。比如 float 转 int 会截断小数位，str 转 int 会做解析，这些都是有损或带解析规则的场景。当调用 int(obj) 时，解释器优先找这个协议。
• __trunc__：面向 math.trunc(obj)，核心语义是向零取整。它解决的问题是“这个对象有没有整数截断形式”。
• __index__：面向“解释器内部需要精确整数索引”的场景，禁止有损转换。返回值必须是真正的 int（技术上可以是 int 子类），浮点、字符串等通通不行。

三者真正的区别不在返回值形式上，而在“能否允许丢精度”。

__int__ 被设计成可以接受各种“近似整数”，比如浮点数可以作为 int() 的参数，但浮点不能作为列表下标。如果让解释器在下标场景自动回退到 __int__，那么 3.7 这种值到底该被当成 3 还是报错？无论选哪种，都会产生反直觉行为。所以 Python 内部把那套“必须精确、不能丢精度”的转换单独抽出来，形成了 __index__ 协议。

从 Python 3.8 开始，官方文档对 __index__ 的表述也变得更严格：它不再只是“为了切片而存在”，而是被定义为“在需要无损整数的地方被调用”。这个口径的变化，说明解释器内部已经把它当作一个通用的“无损失整数协议”来用，而不是一个专门给 list[n] 用的特例补丁。

1.2 只有 int 没有 index 的类型，为什么不能切片

这里用一个最常见的失败案例来展开。假设你写了一个表示页码的类：

python复制class PageNumber:
    def __init__(self, n):
        self.n = n

    def __int__(self):
        print("calling __int__")
        return self.n

在 REPL 里验证它能不能作为列表下标：

python复制data = ["a", "b", "c", "d"]

page = PageNumber(2)

int(page)   # 正常，输出 2
data[page]  # 报错

实际报错内容取决于你访问的是 list 还是其它容器，但常见的 TypeError 文案是：

text复制TypeError: list indices must be integers or slices, not PageNumber

这里有一个很关键的现象：解释器并不会因为你实现了 __int__，就自动“宽宏大量”地把对象当成整数下标。因为 __int__ 的语义允许有损，你不一定知道调用方想截断成多少。所以对容器索引这套逻辑来说，唯一安全的整数来源是 __index__。

一旦你补上这个方法：

python复制class PageNumber:
    def __init__(self, n):
        self.n = n

    def __int__(self):
        return self.n

    def __index__(self):
        print("calling __index__")
        return self.n

再执行 data[PageNumber(2)] 就会正常返回 "c"。

这里的“为什么”，恰恰是 Python 底层设计里非常值得品的一个点：它宁愿让程序明确报错，也不愿意在下标场景里去猜你的对象到底想怎么截断。

2. 从 PEP 357 到 CPython 源码：谁在调用 index

2.1 一段历史：PEP 357 如何催生 index

__index__ 不是最早一批魔术方法，它是在 Python 2.5 时代，由 PEP 357（Allowing Any Object to be Used for Slicing）正式引入的。

当时核心的推动者之一是 numpy 社区。numpy 需要一种机制，让用户可以构造某种对象，并且这个对象可以被放进方括号 arr[obj] 中，直接传递给底层数组做下标。PEP 357 之前，Python 的 sq_index 槽位只面向 C 扩展，Python 层没有对应的魔术方法。于是 PEP 357 做了两个关键决定：把“任何对象都能成为切片下标”的能力开放给 Python 层，也就是 __index__；同时配套增加 operator.index(obj)，让 Python 代码可以显式调用这个协议。

这段历史解释了为什么 __index__ 的返回约束如此严格。PEP 357 明确要求，__index__ 必须返回一个 int，因为它的用途是把对象“压缩成”下标系统中真正需要的整数。如果你返回浮点，下标系统就得做二次截断，那这个协议就退化成 __int__ 了。

2.2 CPython 3.12 内部，索引的必经入口

理解 __index__ 最好的方式，是去 CPython 源码里看几个 C API 入口。Python 层所有“把对象当作索引”的操作，最终几乎都会汇聚到几个 C 层函数上。

第一个是 PyNumber_Index。它在 Objects/abstract.c 中，大概逻辑是这样：

c复制PyObject *
PyNumber_Index(PyObject *item)
{
    PyObject *result;

    if (item == NULL) {
        return null_error();
    }

    if (PyLong_Check(item)) {
        return Py_NewRef(item);
    }

    result = _PyNumber_Index(item);
    if (result != NULL && !PyLong_Check(result)) {
        PyErr_Format(PyExc_TypeError,
                     "__index__ returned non-int (type %.200s)",
                     Py_TYPE(result)->tp_name);
        Py_DECREF(result);
        return NULL;
    }
    return result;
}

如果你的对象本身就是一个 int，它直接返回，不调用任何魔术方法，性能零损耗。如果对象不是 int，则走 _PyNumber_Index，这里面最终会调用类型里的 nb_index 槽位，也就是我们在 Python 层写的 __index__ 方法。返回值如果不是 PyLong，直接抛 TypeError。

第二个是 PyNumber_AsSsize_t。这个函数会把任意“实现了 __index__ 的对象”转成 C 层的 Py_ssize_t，是解释器在 list[n]、del obj[n]、切片解析等场景里实际使用的转换函数。也就是说，我们在 Python 层写的 seq[obj]，底层做的是：先调用 PyNumber_Index 或 PyNumber_AsSsize_t 把 obj 变成整数，再拿这个整数去访问底层数组。

第三个是 PyNumber_Long。这是 int(obj) 真正执行的 C 函数。它会先尝试 nb_int，也就是 __int__；当对象没有 nb_int 时，才会尝试 nb_index；再往后还会尝试 __trunc__ 之类的后备路径。这就是为什么你只实现 __index__ 时，int(obj) 往往也能工作，而容器索引却只认 __index__ 不认 __int__。

2.3 用一个小实验验证调用链

理论说多了容易飘，我们直接跑一个可复现的实验。写一个类，同时定义 __int__ 和 __index__，在两边都打印日志，然后观察不同场景到底调了谁：

python复制import operator

class Probe:
    def __int__(self):
        print("__int__ called")
        return 2

    def __index__(self):
        print("__index__ called")
        return 2

p = Probe()
data = ["a", "b", "c", "d"]

data[p]              # 输出 __index__ called
operator.index(p)    # 输出 __index__ called
int(p)               # 输出 __int__ called
range(4)[p]          # 输出 __index__ called
bin(p)               # 输出 __index__ called

你会发现一个清晰的边界：凡是需要“精确索引”的，都会绕过 __int__ 直接走 __index__。凡是你显式写 int()，则优先走 __int__。

bin(p) 也走 __index__ 这一点很多人没注意到：bin()、hex()、oct() 需要拿到对象的精确整数值来做进制格式化，所以走了 PyNumber_Index 的路线。

3. 把 index 接进自己的类型：一套能直接用的写法

3.1 最小实现：让自定义类型可以放进任何下标场景

现在假设你在写一个数据处理模块，需要一种“页号”类型。它本身不是 int 子类，但希望用户可以自然地把一个 PageRef 对象用作列表下标：

python复制class PageRef:
    def __init__(self, page: int):
        if not isinstance(page, int):
            raise TypeError("page must be an int")
        self._page = page

    def __index__(self) -> int:
        return self._page

    def __int__(self) -> int:
        return self._page

这时，下面的所有操作都能正常工作：

python复制pages = ["cover", "intro", "chapter1", "chapter2"]

ref = PageRef(2)

pages[ref]              # 'chapter1'
range(10)[ref]          # 2
operator.index(ref)     # 2
int(ref)                # 2

这个最小实现里有一个细节值得说明：通常我会建议同时实现 __int__ 和 __index__，并且让两者保持一致的语义。这样，你的对象既能在“给人读的数值转换”场景工作，也能在“系统内部精确索引”场景工作。二者并不冲突，很多纯 Python 数值类型都是同时定义了的。

3.2 需要边界检查时，检查放在哪一层

如果你需要让自定义索引对象在越界时抛出可读的 IndexError，边界检查不应该放在 __index__ 内部，而应该放在使用方或构造时。__index__ 的角色是“把对象变成整数”，它不知道该整数未来会被拿去访问长度为 3 的列表还是长度为 1000 的数组。

举例来说：

python复制class BoundedPageRef:
    def __init__(self, page: int):
        if page < 0:
            raise ValueError("page must be non-negative")
        self._page = page

    def __index__(self) -> int:
        return self._page

如果你希望它支持“负数表示从末尾倒数”，那么可以在返回前把它调整好。不过要小心：list 本身的负索引语义是容器层处理的，不是 __index__ 处理的。换句话说，__index__ 返回 -1 是合法的，容器拿到 -1 后会自己把它换算成“最后一个元素”。你无需在 __index__ 里去猜“容器长度是多少”。

python复制class FlexiblePageRef:
    def __init__(self, page: int):
        self._page = page

    def __index__(self) -> int:
        return self._page

data = ["a", "b", "c"]
ref = FlexiblePageRef(-1)
data[ref]  # 'c'

这一点很多人会误解，以为 __index__ 一定要返回非负数。其实它返回什么整数都可以，正负取决于你的业务语义。关键是调用方要承担“根据长度修正负数”的职责。

3.3 半截实现的常见错误

实现 __index__ 最常见的半截做法，就是把 __int__ 原样搬过来，但没意识到返回值约束更加严格。例如下面这种写法，运行时会直接炸：

python复制class BadIndex:
    def __index__(self):
        return 1.5

然后随便访问一下：

python复制data = [0, 1, 2]
data[BadIndex()]

解释器会报：

text复制TypeError: __index__ returned non-int (type float)

这句报错本身就是很好的提示：__index__ 不是只要“看起来像整数”就行，它需要的是严格意义上的 int。如果你确实需要对一个浮点数做截断，那么应该显式在方法内 return int(value)，而不是把浮点直接抛出去。

另外还有一种隐含错误是返回 bool。虽然 bool 是 int 的子类，CPython 底层 PyLong_Check(True) 也会通过，但从语义上我强烈不建议在 __index__ 里返回 True 或 False。它会让调试代码的人产生困惑，而且有些第三方库会做 type(result) is int 这种精确类型判断，到时你会收获一个莫名其妙的 TypeError。

还有一点需要留意：如果类的实例属性被写成了类属性，或者你把它实现成 staticmethod，也会有各种诡异表现。正确写法是定义成普通实例方法，第一个参数是 self。

4. 真实生态：numpy、自定义容器与接口设计的协作

4.1 numpy 与 index 的关系

numpy 是 __index__ 协议最大的受益者之一。numpy 的标量类型，比如 np.int64、np.int32，都实现了 __index__，所以它们可以被直接用作 Python 列表的下标：

python复制import numpy as np

data = ["a", "b", "c"]

idx = np.int64(2)
data[idx]  # 'c'

这不是 numpy 的特权，而是 np.int64 提供 __index__ 之后，Python 底层所有“精确整数”场景都对它开放了。

反过来，如果你在写一个需要 numpy 协作的库，想让自定义类型能被放进 arr[obj] 这种下标表达式里，最稳妥的做法依然是实现 __index__。写一个带业务语义的下标对象，然后在方法内部把它归一成真正的 int，这一招在写数据访问层的时候非常好用。

4.2 自定义容器时，index 应该被谁调用

如果你正在实现一个自定义容器类，那么你的 __getitem__ 方法里会接收 key。很多初学者会这样写：

python复制class MyContainer:
    def __getitem__(self, key):
        if not isinstance(key, int):
            raise TypeError("key must be int")
        return self._data[key]

这种写法在面对自定义下标对象时会显得很“小气”。假设用户传进来的是只实现了 __index__ 的 PageRef 对象，它确实有资格作为合法下标，但你的 isinstance(key, int) 却把它拒之门外。

更合理的做法是模仿内置 list：先判断是不是 slice，然后再把普通 key 通过 operator.index() 做一次协商转换。

python复制import operator

class MyContainer:
    def __getitem__(self, key):
        if isinstance(key, slice):
            start = operator.index(key.start) if key.start is not None else None
            stop = operator.index(key.stop) if key.stop is not None else None
            step = operator.index(key.step) if key.step is not None else None
            return self._data[start:stop:step]

        index = operator.index(key)
        return self._data[index]

这里的关键函数是 operator.index。它相当于显式请求“把对象转成精确整数”，如果对象没有实现 __index__，它会抛出 TypeError。这个行为正好和内置容器保持一致。

4.3 我在实际项目中踩过的三个坑

我自己写数据处理组件时，在这个协议上踩过不少坑，分享几个印象深刻的：

第一个坑是把 __int__ 当成了 __index__ 的“平替”，导致自定义对象无法放进 random.Random().choice() 的下标相关路径里。排查到半天才发现，标准库里很多路径不关心你能否 int()，只关心你能否提供 __index__。

第二个坑是在容器实现里用 isinstance(key, int) 判断，结果把 np.int64、自定义索引、甚至某些第三方库的整数标量全部拒之门外。改了 operator.index(key) 之后，用户传什么合法整数类型都畅通无阻。

第三个坑和继承有关。有一版代码图省事，直接让业务类继承 int，然后只覆盖了部分方法。结果发现 Python 底层在处理 int 子类时，很多地方会做“剥离子类、还原成纯 int”的操作，导致业务类里维护的额外状态在下标转换过程中丢失，行为非常难排查。后来改成组合模式，内部持有一个 int 字段，再通过 __index__ 暴露出去，反而清晰很多。

5. Python 3.12 上的行为细节与五条自查规则

5.1 Python 3.12 中魔术方法查找机制的演进

既然标题定位是“Python 3.12 MagicMethods”，那稍微说说 3.12 内部的变化。

CPython 从 3.10 开始引入了 Py_TPFLAGS_HAVE_INDEX 类型标志。这个标志的含义是：该类型已经实现了 __index__ 协议。解释器在执行 PyIndex_Check(obj) 这类快速判断时，会先查看类型的 flags，如果发现没有设置这个标志，就直接认为对象不能作为索引，省去了查方法字典的额外开销。Python 3.11、3.12 继续在这个方向上优化，把魔术方法的查找从每实例属性查找改成更高效的 slot 查找和缓存路径。

这对我们写纯 Python 代码的人意味着什么？意味着一个自定义类只要实现了 __index__，CPython 的类型系统就能很快地识别它，进而允许它进入各种下标、进制转换、range() 参数等场景。你不需要显式注册任何东西，也不需要继承特定基类。

不过有一点要留意：在 3.12 上，如果你通过动态方式给实例挂了一个 __index__ 方法，比如：

python复制class Foo:
    pass

f = Foo()
f.__index__ = lambda self: 1

这个方法不会生效，因为 CPython 的魔术方法查找是基于类型的，不是基于实例字典的。你必须在类体里定义 __index__，或者用 type() 动态创建新类。这个规则对所有魔术方法都适用，不是 3.12 的新变化，但在 3.12 上更容易踩中，因为它内部对类型标志做了更多缓存优化。

5.2 一个隐藏细节：int 子类与“精确化”操作

在 CPython 内部，当对象实现 __index__ 且返回值是某个 int 子类实例时，底层并不总是直接信任这个子类实例。很多底层路径会做“精确化”处理，会把子类实例再转成真正的 int，以防子类对数值运算做了别的手脚。

这导致一个实际建议：不要在 __index__ 里返回 int 子类实例，更不要返回自定义 int 子类。你就在方法末尾写 return int(value) 或直接返回 self._value，条件是 self._value 本身已经通过构造参数强制成 int 了。这样底层拿到的一定是最干净的 int，后续不管走 C 扩展还是纯 Python 第三方库，都不会出幺蛾子。

我见过一个同学为了让自定义类“更像 int”，让 __index__ 返回了自定义 int 子类实例，结果在某些旧版 C 扩展里出现奇怪的溢出或比较错误。虽然 Python 层大多数时候能兜住，但完全没有必要用这种危险姿势换取“类 int”的感觉。

5.3 开发自定义数值类时的五条自查规则

如果你在写任何“看起来应该能当整数用”的类，可以在提交前用下面五条规则自查。

第一条：确认它是否需要出现在下标或 range() 参数里。如果只需要给人看，只实现 __int__ 就够了；如果需要被解释器当作精确整数，必须实现 __index__。

第二条：__index__ 的返回值必须是真正的 int。最稳妥的做法是在实现内部先 return int(self._value)，不要直接返回可能为浮点的原始值。

第三条：如果你同时实现了 __int__ 和 __index__，确保两者语义一致。例如 int(obj) == operator.index(obj) 应该恒成立，否则会有很多意想不到的 bug。

第四条：在自定义容器里接收下标时，不要用 isinstance(key, int) 一刀切，尽量用 operator.index(key) 做兼容。这样别人辛苦实现好的 __index__ 才能在你的容器里发挥价值。

第五条：如果你决定继承 int 来实现业务数值类型，请慎重。int 子类在大量底层操作中会被“还原成纯 int”，一个不留神就会丢失子类状态。组合一个 _value 字段加上实现 __index__ 往往比继承更可控。

这五条规则基本能覆盖 90% 的自定义数值类型需求。我自己现在写这类代码时，会顺手在单元测试里覆盖这几个高危点：data[obj] 能通、range(10)[obj] 能通、bin(obj) 能通、operator.index(obj) 返回值等于预期。只要这四个用例是绿的，自定义类型和 Python 整数体系的磨合基本就不会翻车。

如果你还遇到过“明明实现了 __int__ 但切片还是报错”这类问题，现在应该能猜到原因了：解释器要的不是“能转整数”，而是“能无损地变成精确索引”。把 __index__ 加上，你会发现自己那些绕了半天的 workaround 突然都可以删掉了。