dis: FOR_ITER says it no longer pops the stack in 3.12 but it still does when the iterator ended normally

Documentation

The FOR_ITER docs in the dis module say "Up until 3.11 the iterator was popped when it was exhausted". This sounds like in 3.12+ the iterator is not popped anymore:

https://github.com/python/cpython/blob/cecd6012b0ed5dca3916ae341e705ae44172991d/Doc/library/dis.rst?plain=1#L1334-L1342

Instead there is a new opcode END_FOR, which takes care of popping the iterator off the stack. This surprised me because in 3.12 END_FOR is supposed to remove 2 elements from the top of the stack. But if the iterator ends normally, there will only be the iterator at the top. I tried to document my thought process in this godbolt repro.

Reading the generated code for FOR_ITER, specifically:

https://github.com/python/cpython/blob/cecd6012b0ed5dca3916ae341e705ae44172991d/Python/generated_cases.c.h#L3069

https://github.com/python/cpython/blob/cecd6012b0ed5dca3916ae341e705ae44172991d/Python/generated_cases.c.h#L3085-L3087

it looks like there are 2 cases:

• If the iterator ends normally, FOR_ITER pops the iterator off the stack, then it skips the next END_FOR (and in 3.13 POP_TOP) instructions.
• Otherwise (I'm not sure when that happens?), the iterator ends with both the iter and iter() on the stack, which are both popped by END_FOR (and in 3.13 POP_TOP).

Is it worth documenting the 2 different cases?

先查看 Doc/library/dis.rst 中关于 FOR_ITER 的措辞，并将其与 issue 引用的 Python/generated_cases.c.h 中的 FOR_ITER 和 END_FOR 情况进行比较。在 Python 3.12 和 3.13 中验证迭代器耗尽时的正常路径和备用路径；如果两种栈行为都得到确认且能够清晰解释，则更新文档。