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?

Bắt đầu với phần mô tả FOR_ITER trong Doc/library/dis.rst và so sánh với các trường hợp FOR_ITER và END_FOR trong Python/generated_cases.c.h được issue dẫn chiếu. Xác minh các đường đi thông thường và thay thế khi iterator cạn trong Python 3.12 và 3.13, sau đó cập nhật tài liệu nếu cả hai hành vi của stack đều được xác nhận và có thể giải thích rõ ràng.