Add module ignoring functionality to debugger (#14973)

krassowski · web-flow · commit cc81ca15f550 · 2025-09-26T14:20:13.000+01:00
This PR adds two new commands to ignore (and unignore) specific modules when navigating frames in the IPython debugger, similar to how the debugger already skips hidden frames. It will work with all the commands that implies moving between frames like `up`, `down`, `step` and `next`. It is useful when you don't want the debugger to enter third party code. Closes #1665
diff --git a/IPython/core/debugger.py b/IPython/core/debugger.py
@@ -1107,17 +1107,32 @@ def stop_here(self, frame):
                         ]
                     )
                 )
+        if self.skip and self.is_skipped_module(frame.f_globals.get("__name__", "")):
+            print(
+                self.theme.format(
+                    [
+                        (
+                            Token.ExcName,
+                            "    [... skipped 1 ignored module(s)]",
+                        ),
+                        (Token, "\n"),
+                    ]
+                )
+            )
+
+            return False
+
         return super().stop_here(frame)
 
     def do_up(self, arg):
         """u(p) [count]
         Move the current frame count (default one) levels up in the
         stack trace (to an older frame).
 
-        Will skip hidden frames.
+        Will skip hidden frames and ignored modules.
         """
         # modified version of upstream that skips
-        # frames with __tracebackhide__
+        # frames with __tracebackhide__ and ignored modules
         if self.curindex == 0:
             self.error("Oldest frame")
             return
@@ -1126,35 +1141,49 @@ def do_up(self, arg):
         except ValueError:
             self.error("Invalid frame count (%s)" % arg)
             return
-        skipped = 0
+
+        hidden_skipped = 0
+        module_skipped = 0
+
         if count < 0:
             _newframe = 0
         else:
             counter = 0
             hidden_frames = self.hidden_frames(self.stack)
+
             for i in range(self.curindex - 1, -1, -1):
-                if hidden_frames[i] and self.skip_hidden:
-                    skipped += 1
+                should_skip_hidden = hidden_frames[i] and self.skip_hidden
+                should_skip_module = self.skip and self.is_skipped_module(
+                    self.stack[i][0].f_globals.get("__name__", "")
+                )
+
+                if should_skip_hidden or should_skip_module:
+                    if should_skip_hidden:
+                        hidden_skipped += 1
+                    if should_skip_module:
+                        module_skipped += 1
                     continue
                 counter += 1
                 if counter >= count:
                     break
             else:
                 # if no break occurred.
                 self.error(
-                    "all frames above hidden, use `skip_hidden False` to get get into those."
+                    "all frames above skipped (hidden frames and ignored modules). Use `skip_hidden False` for hidden frames or unignore_module for ignored modules."
                 )
                 return
 
             _newframe = i
         self._select_frame(_newframe)
-        if skipped:
+
+        total_skipped = hidden_skipped + module_skipped
+        if total_skipped:
             print(
                 self.theme.format(
                     [
                         (
                             Token.ExcName,
-                            f"    [... skipped {skipped} hidden frame(s)]",
+                            f"    [... skipped {total_skipped} frame(s): {hidden_skipped} hidden frames + {module_skipped} ignored modules]",
                         ),
                         (Token, "\n"),
                     ]
@@ -1166,7 +1195,7 @@ def do_down(self, arg):
         Move the current frame count (default one) levels down in the
         stack trace (to a newer frame).
 
-        Will skip hidden frames.
+        Will skip hidden frames and ignored modules.
         """
         if self.curindex + 1 == len(self.stack):
             self.error("Newest frame")
@@ -1180,28 +1209,39 @@ def do_down(self, arg):
             _newframe = len(self.stack) - 1
         else:
             counter = 0
-            skipped = 0
+            hidden_skipped = 0
+            module_skipped = 0
             hidden_frames = self.hidden_frames(self.stack)
+
             for i in range(self.curindex + 1, len(self.stack)):
-                if hidden_frames[i] and self.skip_hidden:
-                    skipped += 1
+                should_skip_hidden = hidden_frames[i] and self.skip_hidden
+                should_skip_module = self.skip and self.is_skipped_module(
+                    self.stack[i][0].f_globals.get("__name__", "")
+                )
+
+                if should_skip_hidden or should_skip_module:
+                    if should_skip_hidden:
+                        hidden_skipped += 1
+                    if should_skip_module:
+                        module_skipped += 1
                     continue
                 counter += 1
                 if counter >= count:
                     break
             else:
                 self.error(
-                    "all frames below hidden, use `skip_hidden False` to get get into those."
+                    "all frames below skipped (hidden frames and ignored modules). Use `skip_hidden False` for hidden frames or unignore_module for ignored modules."
                 )
                 return
 
-            if skipped:
+            total_skipped = hidden_skipped + module_skipped
+            if total_skipped:
                 print(
                     self.theme.format(
                         [
                             (
                                 Token.ExcName,
-                                f"    [... skipped {skipped} hidden frame(s)]",
+                                f"    [... skipped {total_skipped} frame(s): {hidden_skipped} hidden frames + {module_skipped} ignored modules]",
                             ),
                             (Token, "\n"),
                         ]
@@ -1214,6 +1254,67 @@ def do_down(self, arg):
     do_d = do_down
     do_u = do_up
 
+    def _show_ignored_modules(self):
+        """Display currently ignored modules."""
+        if self.skip:
+            print(f"Currently ignored modules: {sorted(self.skip)}")
+        else:
+            print("No modules are currently ignored.")
+
+    def do_ignore_module(self, arg):
+        """ignore_module <module_name>
+
+        Add a module to the list of modules to skip when navigating frames.
+        When a module is ignored, the debugger will automatically skip over
+        frames from that module.
+
+        Supports wildcard patterns using fnmatch syntax:
+
+        Usage:
+            ignore_module threading     # Skip threading module frames
+            ignore_module asyncio.\\*    # Skip all asyncio submodules
+            ignore_module \\*.tests      # Skip all test modules
+            ignore_module               # List currently ignored modules
+        """
+
+        if self.skip is None:
+            self.skip = set()
+
+        module_name = arg.strip()
+
+        if not module_name:
+            self._show_ignored_modules()
+            return
+
+        self.skip.add(module_name)
+
+    def do_unignore_module(self, arg):
+        """unignore_module <module_name>
+
+        Remove a module from the list of modules to skip when navigating frames.
+        This will allow the debugger to step into frames from the specified module.
+
+        Usage:
+            unignore_module threading   # Stop ignoring threading module frames
+            unignore_module asyncio.\\*  # Remove asyncio.* pattern
+            unignore_module             # List currently ignored modules
+        """
+
+        if self.skip is None:
+            self.skip = set()
+
+        module_name = arg.strip()
+
+        if not module_name:
+            self._show_ignored_modules()
+            return
+
+        try:
+            self.skip.remove(module_name)
+        except KeyError:
+            print(f"Module {module_name} is not currently ignored")
+            self._show_ignored_modules()
+
     def do_context(self, context: str):
         """context number_of_lines
         Set the number of lines of source code to show when displaying
diff --git a/docs/source/interactive/reference.rst b/docs/source/interactive/reference.rst
@@ -820,6 +820,65 @@ And less context on shallower Stack Trace:
     <ipython-input-5-7baadc3d1465>(5)foo()
     ----> 5     return 1/x+foo(x-1)
 
+Module Ignoring Commands
+------------------------
+
+IPython's debugger provides commands to ignore specific modules when navigating
+through stack frames. This is particularly useful when debugging applications
+that use frameworks or libraries where you want to skip over their internal
+code and focus on your application logic.
+
+The module ignoring system supports wildcard patterns using Python's ``fnmatch``
+syntax, allowing you to ignore groups of related modules with a single pattern.
+
+ignore_module <module_name>
+++++++++++++++++++++++++++++
+
+Add a module to the list of modules to skip when navigating frames. When a module
+is ignored, the debugger will automatically skip over frames from that module when
+using the ``next``, ``step``, ``continue``, ``up`` and ``down`` commands.
+
+**Usage:**
+
+.. code::
+
+    ipdb> ignore_module threading
+    ipdb> ignore_module __main__
+    ipdb> ignore_module asyncio.*      # Ignore all asyncio submodules
+    ipdb> ignore_module *.tests        # Ignore all test modules
+    ipdb> ignore_module django.*       # Ignore all django modules
+    ipdb> ignore_module  # List currently ignored modules
+    Currently ignored modules: ['__main__', 'asyncio.*', 'django.*', 'threading']
+
+**Wildcard Pattern Examples:**
+
+- ``asyncio.*`` - Matches ``asyncio.tasks``, ``asyncio.events``, etc.
+- ``*.tests`` - Matches ``myapp.tests``, ``utils.tests``, etc.
+- ``test_*`` - Matches ``test_models``, ``test_views``, etc.
+- ``django.*`` - Matches all Django framework modules
+- ``*pytest*`` - Matches any module containing "pytest"
+
+**Common use cases:**
+
+- Ignore framework code (e.g., ``django.*``, ``flask.*``, ``asyncio.*``)
+- Skip standard library modules (e.g., ``threading``, ``multiprocessing``, ``logging.*``)
+- Hide main module frames (``__main__``) to focus on function implementations
+- Skip test framework internals (``*pytest*``, ``unittest.*``)
+
+unignore_module <module_name>
++++++++++++++++++++++++++++++
+
+Remove a module from the list of modules to skip when navigating frames. This
+allows the debugger to step into frames from the specified module again.
+
+**Usage:**
+
+.. code::
+
+    ipdb> unignore_module threading
+    ipdb> unignore_module asyncio.*    # Remove the pattern
+    ipdb> unignore_module  # List currently ignored modules
+    Currently ignored modules: ['__main__']
 
 Post-mortem debugging
 ---------------------
diff --git a/tests/test_debug_magic.py b/tests/test_debug_magic.py
@@ -75,7 +75,7 @@ def test_debug_magic_passes_through_generators():
     child.expect(ipdb_prompt)
     child.sendline("u")
     child.expect_exact(
-        "*** all frames above hidden, use `skip_hidden False` to get get into those."
+        "*** all frames above skipped (hidden frames and ignored modules). Use `skip_hidden False` for hidden frames or unignore_module for ignored modules."
     )
 
     child.expect(ipdb_prompt)
diff --git a/tests/test_debugger.py b/tests/test_debugger.py

Original file line number	Diff line number	Diff line change
`@@ -75,7 +75,7 @@ def test_debug_magic_passes_through_generators():`
`75`	`75`	`child.expect(ipdb_prompt)`
`76`	`76`	`child.sendline("u")`
`77`	`77`	`child.expect_exact(`
`78`		- "*** all frames above hidden, use `skip_hidden False` to get get into those."
	`78`	+ "*** all frames above skipped (hidden frames and ignored modules). Use `skip_hidden False` for hidden frames or unignore_module for ignored modules."
`79`	`79`	`)`
`80`	`80`
`81`	`81`	`child.expect(ipdb_prompt)`