gh-152966: Add a disassembly browser to IDLE

Add a Disassembly Browser on the Tools menu, showing the disassembled
bytecode of the editor content, the Shell input, or the selection as
collapsible code objects.  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.

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 Tools
+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 Tools 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/config-extensions.def

@@ -61,6 +61,12 @@ enable= 1
 [ASTBrowser_cfgBindings]
 ast-browser=
 
+# A browser for the disassembled bytecode of the editor, from the Tools menu.
+[DisBrowser]
+enable= 1
+[DisBrowser_cfgBindings]
+disassembly-browser=
+
 # A fake extension for testing and example purposes.  When enabled and
 # invoked, inserts or deletes z-text at beginning of every line.
 [ZzDummy]

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,), {})