https://github.com/python/cpython/commit/011f3cab513e12318f4a6c3292b72a3e323cdcfd
commit: 011f3cab513e12318f4a6c3292b72a3e323cdcfd
branch: 3.15
author: Andrew Svetlov <[email protected]>
committer: asvetlov <[email protected]>
date: 2026-11-14T10:37:29+01:00
summary:

[3.15] gh-145667: Update dis docs for GET_ITER, FOR_ITER and SEND changes 
(GH-161867) (#161935)

* 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.



* Exclude removed GET_YIELD_FROM_ITER anchor from the HTML ID check



---------


(cherry picked from commit d8d560b950489995c407c7488caabc6fa03cc84f)

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 525114aa39e2a1..5579c9c98cce8a 100644
--- a/Doc/library/dis.rst
+++ b/Doc/library/dis.rst
@@ -596,10 +596,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
 
@@ -619,11 +623,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)
 
@@ -687,17 +695,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
@@ -1422,7 +1436,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*.
@@ -1430,6 +1447,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.
@@ -1807,8 +1828,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
@@ -1816,6 +1839,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 795de0e3e2324c..5ead7b5151b6ec 100644
--- a/Doc/tools/removed-ids.txt
+++ b/Doc/tools/removed-ids.txt
@@ -7,6 +7,7 @@ c-api/file.html: deprecated-api
 # Removed sections
 faq/library.html: none-of-my-threads-seem-to-run-why
 library/asyncio-task.html: terminating-a-task-group
+library/dis.html: opcode-GET_YIELD_FROM_ITER
 
 tutorial/modules.html: packages-in-multiple-directories
 

_______________________________________________
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