https://github.com/python/cpython/commit/d8d560b950489995c407c7488caabc6fa03cc84f
commit: d8d560b950489995c407c7488caabc6fa03cc84f
branch: main
author: Andrew Svetlov <[email protected]>
committer: asvetlov <[email protected]>
date: 2026-11-13T14:37:38+01:00
summary:

gh-145667: Update dis docs for GET_ITER, FOR_ITER and SEND changes (#161867)

* gh-145667: Update dis docs for GET_ITER, FOR_ITER and SEND changes

Document the (iterator, index or NULL) pair pushed by GET_ITER and
consumed by FOR_ITER, SEND, END_SEND and POP_ITER, and the yield_from
argument of GET_ITER that replaced GET_YIELD_FROM_ITER in 3.15.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

* Exclude removed GET_YIELD_FROM_ITER anchor from the HTML ID check

Co-Authored-By: Claude Opus 5.5 <[email protected]>

---------

Co-authored-by: Claude Opus 5.5 <[email protected]>

files:
M Doc/library/dis.rst
M Doc/tools/removed-ids.txt

diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst
index 5a93a328d48728..16c2dab5b8adba 100644
--- a/Doc/library/dis.rst
+++ b/Doc/library/dis.rst
@@ -621,10 +621,14 @@ operations on it as if it was a Python list. The top of 
the stack corresponds to
 
 .. opcode:: POP_ITER
 
-   Removes the iterator from the top of the stack.
+   Removes the iterator and the value pushed with it by :opcode:`GET_ITER`
+   from the top of the stack.
 
    .. versionadded:: 3.14
 
+   .. versionchanged:: 3.15
+      Two values are now removed.
+
 
 .. opcode:: POP_TOP
 
@@ -644,11 +648,15 @@ operations on it as if it was a Python list. The top of 
the stack corresponds to
 
 .. opcode:: END_SEND
 
-   Implements ``del STACK[-2]``.
+   Implements ``del STACK[-3:-1]``.
    Used to clean up when a generator exits.
 
    .. versionadded:: 3.12
 
+   .. versionchanged:: 3.15
+      The receiver and the value pushed with it by :opcode:`GET_ITER` are
+      removed, instead of only the receiver.
+
 
 .. opcode:: COPY (i)
 
@@ -712,17 +720,23 @@ result back on the stack.
    Implements ``STACK[-1] = ~STACK[-1]``.
 
 
-.. opcode:: GET_ITER
-
-   Implements ``STACK[-1] = iter(STACK[-1])``.
+.. opcode:: GET_ITER (yield_from)
 
+   Replaces ``STACK[-1]`` with an iterator for it and pushes a second value,
+   which is used by :opcode:`FOR_ITER`, :opcode:`SEND` and :opcode:`POP_ITER`.
 
-.. opcode:: GET_YIELD_FROM_ITER
+   For some built-in sequence types, such as :class:`list` and :class:`tuple`,
+   the object itself is left on the stack as a "virtual iterator" and the
+   index to start iterating from is pushed.  Otherwise, implements
+   ``STACK[-1] = iter(STACK[-1])`` and pushes ``NULL``.
 
-   If ``STACK[-1]`` is a :term:`generator iterator` or :term:`coroutine` object
-   it is left as is.  Otherwise, implements ``STACK[-1] = iter(STACK[-1])``.
+   If *yield_from* is non-zero, the instruction is used for ``yield from``:
+   a :term:`coroutine` object is left as is, unless the current code is
+   a regular generator, in which case :exc:`TypeError` is raised.
 
-   .. versionadded:: 3.5
+   .. versionchanged:: 3.15
+      A second value is now pushed after the iterator.  The *yield_from*
+      argument was added, replacing the ``GET_YIELD_FROM_ITER`` instruction.
 
 
 .. opcode:: TO_BOOL
@@ -1425,7 +1439,10 @@ iterations of the loop.
 
 .. opcode:: FOR_ITER (delta)
 
-   ``STACK[-1]`` is an :term:`iterator`.  Call its :meth:`~iterator.__next__` 
method.
+   ``STACK[-2]`` is an :term:`iterator` (or a virtual iterator, see
+   :opcode:`GET_ITER`) and ``STACK[-1]`` is the value pushed with it by
+   :opcode:`GET_ITER`.  Get the next item, calling the iterator's
+   :meth:`~iterator.__next__` method if needed.
    If this yields a new value, push it on the stack (leaving the iterator below
    it).  If the iterator indicates it is :term:`exhausted` then the byte code 
counter is
    incremented by *delta*.
@@ -1433,6 +1450,10 @@ iterations of the loop.
    .. versionchanged:: 3.12
       Up until 3.11 the iterator was popped when it was exhausted.
 
+   .. versionchanged:: 3.15
+      The iterator is now followed on the stack by the value pushed with it
+      by :opcode:`GET_ITER`.
+
 .. opcode:: LOAD_GLOBAL (namei)
 
    Loads the global named ``co_names[namei>>1]`` onto the stack.
@@ -1810,8 +1831,10 @@ iterations of the loop.
 
 .. opcode:: SEND (delta)
 
-   Equivalent to ``STACK[-1] = STACK[-2].send(STACK[-1])``. Used in ``yield 
from``
-   and ``await`` statements.
+   Equivalent to ``STACK[-1] = STACK[-3].send(STACK[-1])``. Used in ``yield 
from``
+   and ``await`` statements.  ``STACK[-2]`` is the value pushed with the
+   receiver by :opcode:`GET_ITER`; if the receiver is a virtual iterator,
+   it is advanced as by :opcode:`FOR_ITER`.
 
    If the call raises :exc:`StopIteration`, pop the top value from the stack,
    push the exception's ``value`` attribute, and increment the bytecode counter
@@ -1819,6 +1842,10 @@ iterations of the loop.
 
    .. versionadded:: 3.11
 
+   .. versionchanged:: 3.15
+      The receiver is now at ``STACK[-3]``, followed by the value pushed with
+      it by :opcode:`GET_ITER`.
+
 
 .. opcode:: HAVE_ARGUMENT
 
diff --git a/Doc/tools/removed-ids.txt b/Doc/tools/removed-ids.txt
index f846e4b8dc1524..bc9546eb0336b1 100644
--- a/Doc/tools/removed-ids.txt
+++ b/Doc/tools/removed-ids.txt
@@ -34,6 +34,7 @@ library/asyncio-task.html: terminating-a-task-group
 library/dis.html: opcode-DELETE_ATTR
 library/dis.html: opcode-DELETE_GLOBAL
 library/dis.html: opcode-DELETE_NAME
+library/dis.html: opcode-GET_YIELD_FROM_ITER
 library/asyncio-llapi-index.html: event-loop-policies
 
 deprecations/index.html: pending-removal-in-python-3-15

_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3//lists/python-checkins.python.org
Member address: [email protected]

Reply via email to