gh-152966: Add a disassembly browser to IDLE

Add a Disassembly Browser command to the Browse menu (Shell and editor).
It shows the disassembled bytecode of the editor content, the Shell input,
or the selection, as collapsible code objects colored by operand kind.
Selecting an instruction highlights the matching source, and selecting
source selects the instructions.

While the debugger is stopped, the browser instead shows the code object
that is executing -- obtained from the subprocess through the debugger RPC
via marshal, not by recompiling the editor -- and marks the current
instruction.

It shares the window skeleton and editor-sync mechanism with the token and
AST browsers.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: serhiy-storchaka

Doc/library/idle.rst

@@ -321,6 +321,22 @@ AST Browser
    Double-click a node, or press :kbd:`Escape`,
    to hide the browser and return to the editor at the node.
 
+Disassembly Browser
+   Open a window showing the disassembled bytecode of the editor content
+   (or, in the Shell, the current input), or of the selection if there is one.
+   Each code object is a collapsible row of its instructions,
+   colored by the kind of operand they use;
+   the one holding the cursor is opened and its instructions selected.
+   Selecting an instruction highlights the matching region in the editor
+   and moves the cursor there;
+   selecting text or moving the cursor in the editor
+   selects the instructions built from it.
+   Double-click a row, or press :kbd:`Escape`,
+   to hide the browser and return to the editor at the instruction.
+   While the debugger is stopped, the browser follows it instead of the
+   editor, showing the code object that is executing
+   and marking the current instruction.
+
 Options menu (Shell and Editor)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

Lib/idlelib/News3.txt

@@ -4,6 +4,15 @@ Released on 2026-10-01
 =========================
 
 
+gh-152966: Add a Disassembly Browser to IDLE, opened from the Browse
+menu.  It shows the disassembled bytecode of the editor content, the
+Shell input, or the selection, as collapsible code objects colored by
+operand kind.  Selecting an instruction highlights the matching source,
+and selecting source selects the instructions.  While the debugger is
+stopped, the browser instead shows the code object that is executing and
+marks the current instruction.  Patch by Serhiy Storchaka and Claude
+Code.
+
 gh-152942: Add an AST Browser to IDLE, opened from the Browse menu.  It
 shows the abstract syntax tree of the editor content, the Shell input,
 or the selection.  Selecting a node highlights the matching region in

Lib/idlelib/debugger.py

@@ -170,6 +170,11 @@ def close(self, event=None):
         # (Causes a harmless extra cycle through close_debugger() if user
         # toggled debugger from pyshell Debug menu)
         self.pyshell.close_debugger()
+        # Tell observers (e.g. the disassembly browser) debugging has ended.
+        try:
+            self.pyshell.text.event_generate("<<debugger-off>>", when="tail")
+        except Exception:
+            pass
         # Now close the debugger control window....
         self.top.destroy()
 
@@ -282,6 +287,9 @@ def interaction(self, message, frame, info=None):
         if self.vsource.get():
             self.sync_source_line()
 
+        # Let observers (e.g. the disassembly browser) react to the stop.
+        self.pyshell.text.event_generate("<<debugger-stopped>>", when="tail")
+
         for b in self.buttons:
             b.configure(state="normal")
 
@@ -313,6 +321,20 @@ def __frame2fileline(self, frame):
         lineno = frame.f_lineno
         return filename, lineno
 
+    def current_frame_code(self):
+        """Return (code object, last-instruction offset) for the current frame.
+
+        The code object is the one actually executing: obtained via marshal
+        from a remote FrameProxy, or directly from a local frame.  Return None
+        when the program is not stopped.
+        """
+        frame = self.frame
+        if frame is None:
+            return None
+        get_code = getattr(frame, "code_object", None)  # A remote FrameProxy.
+        code = get_code() if get_code else frame.f_code  # Else a local frame.
+        return code, frame.f_lasti
+
     def cont(self):
         self.idb.set_continue()
         self.abort_loop()

Lib/idlelib/debugger_r.py

@@ -19,6 +19,7 @@
 barrier, in particular frame and traceback objects.
 
 """
+import marshal
 import reprlib
 import types
 from idlelib import debugger
@@ -144,6 +145,12 @@ def frame_code(self, fid):
         codetable[cid] = code
         return cid
 
+    def frame_code_marshal(self, fid):
+        # A code object cannot be pickled through the RPC, but it can be
+        # marshalled; the two interpreters are the same build, so the bytes
+        # load back into an equivalent code object in the IDLE process.
+        return marshal.dumps(frametable[fid].f_code)
+
     #----------called by a CodeProxy----------
 
     def code_name(self, cid):
@@ -219,6 +226,12 @@ def _get_f_code(self):
         cid = self._conn.remotecall(self._oid, "frame_code", (self._fid,), {})
         return CodeProxy(self._conn, self._oid, cid)
 
+    def code_object(self):
+        "Return the frame's real code object, transported via marshal."
+        blob = self._conn.remotecall(self._oid, "frame_code_marshal",
+                                     (self._fid,), {})
+        return marshal.loads(blob)
+
     def _get_f_globals(self):
         did = self._conn.remotecall(self._oid, "frame_globals",
                                     (self._fid,), {})