从源码级别剖析__iter__：Python迭代器协议的稀缺技术内幕

第一章：从源码看Python迭代器协议的基石

Python 的迭代器协议是其容器类型能够被遍历的核心机制。该协议基于两个简单但关键的方法：`__iter__()` 和 `__next__()`。任何实现了这两个方法的对象，都可以被视为迭代器。

迭代器协议的基本构成

• __iter__()：返回迭代器对象本身，使得对象可以在 for 循环中使用
• __next__()：返回容器中的下一个元素，当没有更多元素时，抛出 StopIteration 异常

例如，一个简单的自定义迭代器可以这样实现：

class CountDown:
    def __init__(self, start):
        self.current = start

    def __iter__(self):
        return self

    def __next__(self):
        if self.current <= 0:
            raise StopIteration
        else:
            num = self.current
            self.current -= 1
            return num

# 使用示例
for n in CountDown(3):
    print(n)
# 输出: 3, 2, 1

底层机制与 CPython 源码关联

在 CPython 解释器中，迭代操作通过调用内置的 `PyObject_GetIter()` 函数触发，该函数会查找对象的 `__iter__` 方法。若存在，则返回迭代器；否则尝试构建默认迭代器（如序列类型）。一旦获得迭代器，解释器持续调用其 `__next__` 方法直至捕获 `StopIteration`。

方法	作用	触发方式
__iter__()	获取迭代器对象	iter(obj) 或隐式在 for 中调用
__next__()	获取下一个值	next(iterator) 或解释器内部循环调用

graph TD A[for item in obj] --> B{obj.__iter__() } B --> C[返回迭代器] C --> D[调用 __next__()] D --> E{有下一个值?} E -->|是| F[返回值] E -->|否| G[抛出 StopIteration] F --> D G --> H[循环结束]

第二章：__iter__ 方法的核心机制解析

2.1 迭代器协议的定义与 CPython 实现原理

迭代器协议是 Python 中实现可迭代对象的核心机制，其本质要求对象实现 `__iter__()` 和 `__next__()` 两个特殊方法。当对象具备这两个方法时，即可被 `for` 循环或内置函数如 `next()` 驱动。

底层执行流程

CPython 在遍历过程中首先调用 `__iter__()` 获取迭代器对象，随后不断调用其 `__next__()` 方法获取元素，直至抛出 `StopIteration` 异常终止。

class Counter:
    def __init__(self, low, high):
        self.current = low
        self.high = high

    def __iter__(self):
        return self

    def __next__(self):
        if self.current > self.high:
            raise StopIteration
        else:
            self.current += 1
            return self.current - 1

上述代码中，`__iter__()` 返回自身以满足协议要求；`__next__()` 控制值的生成逻辑，超出范围时触发 `StopIteration`，由解释器捕获并结束迭代。

CPython 内部处理机制

在字节码层面，`for` 循环被编译为 `GET_ITER` 和 `FOR_ITER` 指令，后者隐式调用 `__next__()` 并处理异常，体现了语言层与虚拟机的紧密协作。

2.2 __iter__ 在内置类型中的底层实现分析

Python 中的 `__iter__` 方法是迭代协议的核心，内置类型如列表、字典、元组等均通过 CPython 的底层 C 代码实现该方法。

常见内置类型的迭代器实现

• list：返回一个 listiterator 对象，内部维护索引位置，逐个访问元素；
• dict：返回 dict_keyiterator（默认迭代键），支持 keys/values/items 的变体；
• str：字符序列迭代，每次返回一个 Unicode 字符。

代码示例与底层行为对比

my_list = [1, 2, 3]
it = iter(my_list)
print(type(it))  # <class 'list_iterator'>

上述代码中，iter() 调用对象的 __iter__ 方法。在 CPython 源码中，这会触发对应类型所绑定的 tp_iter 函数指针，例如 list_iter() 返回新的迭代器实例。

性能差异简析

类型	迭代器获取速度	内存开销
list	快	低
dict	中	中
set	慢	高

2.3 用户自定义类中 __iter__ 的正确实现模式

在 Python 中，通过实现 `__iter__` 方法，可使自定义类支持迭代协议。最推荐的实现模式是：`__iter__` 返回一个具备 `__next__` 方法的迭代器对象，通常返回自身，并在类中实现 `__next__`。

标准实现结构

class CountDown:
    def __init__(self, start):
        self.start = start

    def __iter__(self):
        return self

    def __next__(self):
        if self.start <= 0:
            raise StopIteration
        self.start -= 1
        return self.start + 1

上述代码中，`__iter__` 返回 `self`，表明该实例自身即为迭代器。`__next__` 负责状态维护与值生成，当条件满足时抛出 `StopIteration` 以终止迭代。

关键设计原则

• 单一职责：确保迭代器的状态管理清晰独立
• 资源释放：若涉及外部资源，应在 `StopIteration` 后妥善清理
• 可重用性：若需多次迭代，可在 `__iter__` 中返回新迭代器实例而非自身

2.4 从字节码层面观察 for 循环如何调用 __iter__

Python 的 `for` 循环在底层通过字节码指令调用对象的 `__iter__` 方法。使用 `dis` 模块可以查看其执行过程。

字节码执行流程

当遍历一个列表时，CPython 虚拟机会生成如下关键字节码：

import dis

def traverse_list():
    for item in [1, 2, 3]:
        print(item)

dis.dis(traverse_list)

输出中关键指令包括：

• GET_ITER：调用对象的 __iter__ 方法获取迭代器；
• FOR_ITER：不断调用迭代器的 __next__，直到抛出 StopIteration。

核心机制解析

任何对象只要实现了 `__iter__`，其返回值具备 `__next__` 方法，即可被 `for` 循环驱动。字节码层屏蔽了类型差异，统一通过协议调用。

2.5 实践：构建一个可被 for 遍历的容器类

为了让自定义类支持 `for` 循环遍历，必须实现 Python 的迭代器协议，即提供 `__iter__()` 和 `__next__()` 方法。

实现可迭代的容器

class IterableContainer:
    def __init__(self, data):
        self.data = data

    def __iter__(self):
        self.index = 0
        return self

    def __next__(self):
        if self.index >= len(self.data):
            raise StopIteration
        value = self.data[self.index]
        self.index += 1
        return value

该类在 __iter__() 中重置索引并返回自身，在 __next__() 中逐个返回元素，到达末尾时抛出 StopIteration 异常以终止循环。

使用示例

• 实例化容器：container = IterableContainer([1, 2, 3])
• 通过 for 遍历：for item in container: print(item)

此设计模式适用于封装数据集合，并提供统一的遍历接口。

第三章：迭代器与可迭代对象的源码差异

3.1 可迭代对象与迭代器的类型学区分

在Python中，可迭代对象（Iterable）与迭代器（Iterator）虽密切相关，却属于不同的类型学范畴。可迭代对象是任何可以通过 iter() 函数产生迭代器的对象，例如列表、元组和字符串。

核心区别解析

• 可迭代对象：实现 __iter__() 方法，返回一个迭代器。
• 迭代器：同时实现 __iter__() 和 __next__() 方法，具备状态保持能力。

class Counter:
    def __init__(self, low, high):
        self.current = low
        self.high = high

    def __iter__(self):
        return self

    def __next__(self):
        if self.current > self.high:
            raise StopIteration
        else:
            self.current += 1
            return self.current - 1

上述代码定义了一个自定义迭代器 Counter。其 __iter__() 返回自身，表明它既是可迭代对象也是迭代器。每次调用 __next__() 时，返回当前值并递增，直到超出上限触发 StopIteration。这种设计模式体现了迭代器的惰性求值特性，适用于处理大规模或无限数据流。

3.2 collections.abc 模块中的抽象基类剖析

抽象基类的核心作用

collections.abc 模块定义了Python中容器类型的抽象基类（ABC），用于规范类的行为并支持接口检测。通过继承这些基类，开发者可明确类是否具备特定协议，如可迭代、映射或序列行为。

常用抽象基类示例

• Iterable：定义 __iter__() 方法，支持迭代
• Sequence：不可变序列，需实现 __getitem__ 和 __len__
• MutableMapping：可变映射类型，如自定义字典

from collections.abc import Sequence

class CustomList(Sequence):
    def __init__(self, items):
        self._items = list(items)
    def __getitem__(self, index):
        return self._items[index]
    def __len__(self):
        return len(self._items)

# 实例自动兼容 isinstance(obj, Sequence)
data = CustomList([1, 2, 3])
print(len(data))  # 输出: 3

上述代码实现了一个符合 Sequence 接口的类。__getitem__ 支持索引访问，__len__ 提供长度信息，使实例能被 isinstance() 正确识别为序列类型。

3.3 实践：通过 isinstance 判断迭代能力的内部逻辑

在 Python 中，`isinstance()` 不仅用于类型判断，还可检测对象是否具备特定协议能力。判断一个对象是否可迭代，本质是检查其是否实现了 `__iter__` 方法或符合迭代器协议。

迭代能力的检测方式

使用 `collections.abc.Iterable` 可抽象判断对象是否支持迭代：

from collections.abc import Iterable

def check_iterable(obj):
    return isinstance(obj, Iterable)

print(check_iterable([1, 2, 3]))  # True
print(check_iterable("hello"))    # True
print(check_iterable(42))         # False

该代码中，`isinstance` 内部调用 `Iterable` 的 `__subclasshook__` 方法，动态判断对象是否定义了 `__iter__` 或 `__getitem__`，从而决定是否视为可迭代对象。

协议与鸭子类型的实际应用

Python 的“鸭子类型”哲学在此体现：只要行为像迭代器，就被视为迭代器。`isinstance` 结合 ABC（抽象基类）机制，使这种动态判断既安全又高效。

第四章：深入CPython解释器中的迭代实现

4.1 PyObject_GetIter 函数在 C 层面的角色解析

`PyObject_GetIter` 是 CPython 解释器中实现迭代协议的核心函数，位于 `Objects/abstract.c` 模块。它负责从任意 Python 对象中提取迭代器，是 `for` 循环和 `iter()` 内建函数在底层的支撑机制。

核心功能与调用流程

该函数首先检查对象是否定义了 `__iter__` 方法，若存在则调用并返回结果；否则尝试构建一个基于 `__getitem__` 的迭代器。

PyObject *
PyObject_GetIter(PyObject *o)
{
    PyTypeObject *t = o->ob_type;
    getiterfunc f;

    if (t->tp_iter != NULL) {
        f = t->tp_iter;
        return f(o);
    }
    // 回退到基于索引的迭代支持
    if (PySequence_Check(o))
        return PySeqIter_New(o);
    ...
}

上述代码表明，`tp_iter` 为类型结构中的第一优先级，若未定义，则通过 `PySequence_Check` 判断是否为序列类型并生成序列迭代器。

关键作用场景

• 解释器执行 `FOR_ITER` 字节码时内部调用
• 实现自定义类型的可迭代能力（需设置 `tp_iter`）
• 桥接高级语法与底层数据结构的迭代需求

4.2 iter() 内置函数的源码路径追踪

Python 中的 `iter()` 函数是内置函数，其实现位于 CPython 解释器的核心源码中。其定义可在 `Python/bltinmodule.c` 文件中找到，对应函数为 `builtin_iter`。

核心实现逻辑

static PyObject *
builtin_iter(PyObject *self, PyObject *args)
{
    PyObject *o;
    if (!PyArg_UnpackTuple(args, "iter", 1, 1, &o))
        return NULL;
    return PyObject_GetIter(o);
}

该函数首先解析传入参数，确保仅接收一个对象。随后调用 `PyObject_GetIter(o)`，此函数在 `Objects/abstract.c` 中定义，负责触发对象的 `__iter__` 方法或回退至 `__getitem__` 协议。

调用链路汇总

• iter(obj) 触发内置函数入口
• 转发至 PyObject_GetIter()
• 检查类型是否支持迭代协议
• 优先调用 tp_iter 或构造迭代器

4.3 迭代结束时 StopIteration 异常的抛出机制

在 Python 的迭代协议中，当迭代器遍历完成所有元素后，继续调用 `__next__()` 方法将触发 `StopIteration` 异常。该异常是控制循环正常终止的核心机制。

异常抛出流程

迭代器内部通过判断是否还有下一个元素来决定行为：若有，则返回值；若无，则显式抛出 `StopIteration`。

class CountIterator:
    def __init__(self, limit):
        self.limit = limit
        self.count = 0

    def __iter__(self):
        return self

    def __next__(self):
        if self.count < self.limit:
            value = self.count
            self.count += 1
            return value
        else:
            raise StopIteration  # 触发迭代结束

上述代码中，当 `self.count` 达到 `limit` 时，`__next__` 方法抛出 `StopIteration`，通知 for 循环停止执行。

底层协同机制

• for 语句隐式调用迭代器的 __next__()
• 解释器捕获 StopIteration 并安全退出循环
• 手动调用需自行处理该异常以避免程序中断

4.4 实践：使用 Cython 模拟 __iter__ 的底层行为

在 Python 中，`__iter__` 方法是实现迭代协议的核心。通过 Cython，我们可以更贴近 C 层级模拟其底层行为，提升性能。

定义可迭代对象

使用 Cython 定义一个简单的整数序列容器，并实现 `__iter__`：

cdef class IntSequence:
    cdef int start, stop

    def __init__(self, start, stop):
        self.start = start
        self.stop = stop

    def __iter__(self):
        cdef int i = self.start
        while i < self.stop:
            yield i
            i += 1

该代码中，`cdef class` 声明了 Cython 类，`__iter__` 使用 `yield` 返回生成器。Cython 将其编译为高效的迭代器对象，避免了解释层的开销。

性能对比

• Cython 版本直接在 C 层执行循环逻辑
• 原生 Python 需频繁进入字节码解释流程
• 对于大数据量遍历，性能提升可达 3-5 倍

第五章：结语——掌握 __iter__ 就是掌握 Python 遍历的本质

理解迭代协议的核心价值

Python 中的遍历能力依赖于迭代协议，而该协议的核心正是 __iter__ 方法。任何对象只要实现了此方法并返回一个迭代器，就能被用于 for 循环、列表推导式甚至内置函数如 sum()。

class CountDown:
    def __init__(self, start):
        self.start = start

    def __iter__(self):
        current = self.start
        while current > 0:
            yield current
            current -= 1

# 实际应用：生成倒计时序列
for num in CountDown(3):
    print(num)  # 输出: 3, 2, 1

实际工程中的灵活应用

在数据处理场景中，自定义可迭代对象能有效降低内存占用。例如从大文件逐行读取日志时，封装一个可迭代类比一次性加载更高效。

• 避免将所有数据载入内存，提升系统稳定性
• 与标准库无缝集成，如配合 itertools 进行链式操作
• 支持懒加载，仅在需要时计算下一项

常见陷阱与调试建议

若对象未正确实现 __iter__，会导致 TypeError: 'X' object is not iterable。确保返回的是迭代器（具有 __next__ 和 __iter__ 方法），或使用 yield 自动生成生成器迭代器。

类型	是否可迭代	判断方式
list	是	hasattr(obj, '__iter__')
generator	是	isinstance(obj, Iterator)