Skip to content

Commit 401e1e3

Browse files
ktowenktowen
committed
gh-139721: Add ignore_module/unignore_module commands to pdb
Add two new commands to pdb for skipping frames from specified modules: - ignore_module [module_name]: Add modules to skip during debugging - unignore_module [module_name]: Remove modules from skip list When a module is ignored, the debugger automatically skips over its frames during step, next, continue, up, and down commands. Supports wildcard patterns via fnmatch for flexible module matching.
1 parent 75b1afe commit 401e1e3

File tree

4 files changed

+285
-2
lines changed

4 files changed

+285
-2
lines changed

‎Doc/library/pdb.rst‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -438,11 +438,17 @@ can be overridden by the local file.
438438
Move the current frame *count* (default one) levels down in the stack trace
439439
(to a newer frame).
440440

441+
Frames from ignored modules will be skipped. Use :pdbcmd:`ignore_module` to
442+
ignore modules and :pdbcmd:`unignore_module` to stop ignoring them.
443+
441444
.. pdbcommand:: u(p) [count]
442445

443446
Move the current frame *count* (default one) levels up in the stack trace (to
444447
an older frame).
445448

449+
Frames from ignored modules will be skipped. Use :pdbcmd:`ignore_module` to
450+
ignore modules and :pdbcmd:`unignore_module` to stop ignoring them.
451+
446452
.. pdbcommand:: b(reak) [([filename:]lineno | function) [, condition]]
447453

448454
With a *lineno* argument, set a break at line *lineno* in the current file.
@@ -718,6 +724,47 @@ can be overridden by the local file.
718724
:pdbcmd:`interact` directs its output to the debugger's
719725
output channel rather than :data:`sys.stderr`.
720726

727+
.. pdbcommand:: ignore_module [module_name]
728+
729+
Add a module to the list of modules to skip when stepping, continuing, or
730+
navigating frames. When a module is ignored, the debugger will automatically
731+
skip over frames from that module during :pdbcmd:`step`, :pdbcmd:`next`,
732+
:pdbcmd:`continue`, :pdbcmd:`up`, and :pdbcmd:`down` commands.
733+
734+
Supports wildcard patterns using glob-style matching (via :mod:`fnmatch`).
735+
736+
Without *module_name*, list the currently ignored modules.
737+
738+
Examples::
739+
740+
(Pdb) ignore_module threading # Skip threading module frames
741+
(Pdb) ignore_module asyncio.* # Skip all asyncio submodules
742+
(Pdb) ignore_module *.tests # Skip all test modules
743+
(Pdb) ignore_module # List currently ignored modules
744+
745+
Common use cases:
746+
747+
- Skip framework code (``django.*``, ``flask.*``, ``asyncio.*``)
748+
- Skip standard library modules (``threading``, ``multiprocessing``, ``logging.*``)
749+
- Skip test framework internals (``*pytest*``, ``unittest.*``)
750+
751+
.. versionadded:: 3.15
752+
753+
.. pdbcommand:: unignore_module [module_name]
754+
755+
Remove a module from the list of modules to skip when stepping or navigating
756+
frames. This will allow the debugger to step into frames from the specified
757+
module again.
758+
759+
Without *module_name*, list the currently ignored modules.
760+
761+
Example::
762+
763+
(Pdb) unignore_module threading # Stop ignoring threading module frames
764+
(Pdb) unignore_module asyncio.* # Remove the asyncio.* pattern
765+
766+
.. versionadded:: 3.15
767+
721768
.. _debugger-aliases:
722769

723770
.. pdbcommand:: alias [name [command]]

‎Lib/pdb.py‎

Lines changed: 115 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1774,6 +1774,8 @@ def do_up(self, arg):
17741774
17751775
Move the current frame count (default one) levels up in the
17761776
stack trace (to an older frame).
1777+
1778+
Will skip frames from ignored modules.
17771779
"""
17781780
if self.curindex == 0:
17791781
self.error('Oldest frame')
@@ -1786,7 +1788,30 @@ def do_up(self, arg):
17861788
if count < 0:
17871789
newframe = 0
17881790
else:
1789-
newframe = max(0, self.curindex - count)
1791+
# Skip over ignored modules
1792+
counter = 0
1793+
module_skipped = 0
1794+
for i in range(self.curindex - 1, -1, -1):
1795+
frame = self.stack[i][0]
1796+
should_skip_module = (self.skip and
1797+
self.is_skipped_module(frame.f_globals.get('__name__', '')))
1798+
1799+
if should_skip_module:
1800+
module_skipped += 1
1801+
continue
1802+
counter += 1
1803+
if counter >= count:
1804+
break
1805+
else:
1806+
# No valid frames found
1807+
self.error('All frames above are from ignored modules. '
1808+
'Use "unignore_module" to allow stepping into them.')
1809+
return
1810+
1811+
newframe = i
1812+
if module_skipped:
1813+
self.message(f'[... skipped {module_skipped} frame(s) '
1814+
'from ignored modules]')
17901815
self._select_frame(newframe)
17911816
do_u = do_up
17921817

@@ -1795,6 +1820,8 @@ def do_down(self, arg):
17951820
17961821
Move the current frame count (default one) levels down in the
17971822
stack trace (to a newer frame).
1823+
1824+
Will skip frames from ignored modules.
17981825
"""
17991826
if self.curindex + 1 == len(self.stack):
18001827
self.error('Newest frame')
@@ -1807,7 +1834,30 @@ def do_down(self, arg):
18071834
if count < 0:
18081835
newframe = len(self.stack) - 1
18091836
else:
1810-
newframe = min(len(self.stack) - 1, self.curindex + count)
1837+
# Skip over ignored modules
1838+
counter = 0
1839+
module_skipped = 0
1840+
for i in range(self.curindex + 1, len(self.stack)):
1841+
frame = self.stack[i][0]
1842+
should_skip_module = (self.skip and
1843+
self.is_skipped_module(frame.f_globals.get('__name__', '')))
1844+
1845+
if should_skip_module:
1846+
module_skipped += 1
1847+
continue
1848+
counter += 1
1849+
if counter >= count:
1850+
break
1851+
else:
1852+
# No valid frames found
1853+
self.error('All frames below are from ignored modules. '
1854+
'Use "unignore_module" to allow stepping into them.')
1855+
return
1856+
1857+
newframe = i
1858+
if module_skipped:
1859+
self.message(f'[... skipped {module_skipped} frame(s) '
1860+
'from ignored modules]')
18111861
self._select_frame(newframe)
18121862
do_d = do_down
18131863

@@ -2327,6 +2377,69 @@ def do_interact(self, arg):
23272377
console.interact(banner="*pdb interact start*",
23282378
exitmsg="*exit from pdb interact command*")
23292379

2380+
def _show_ignored_modules(self):
2381+
"""Display currently ignored modules."""
2382+
if self.skip:
2383+
self.message(f'Currently ignored modules: {sorted(self.skip)}')
2384+
else:
2385+
self.message('No modules are currently ignored.')
2386+
2387+
def do_ignore_module(self, arg):
2388+
"""ignore_module [module_name]
2389+
2390+
Add a module to the list of modules to skip when stepping,
2391+
continuing, or navigating frames. When a module is ignored,
2392+
the debugger will automatically skip over frames from that
2393+
module during step, next, continue, up, and down commands.
2394+
2395+
Supports wildcard patterns using glob-style matching:
2396+
2397+
Usage:
2398+
ignore_module threading # Skip threading module frames
2399+
ignore_module asyncio.* # Skip all asyncio submodules
2400+
ignore_module *.tests # Skip all test modules
2401+
ignore_module # List currently ignored modules
2402+
"""
2403+
if self.skip is None:
2404+
self.skip = set()
2405+
2406+
module_name = arg.strip()
2407+
2408+
if not module_name:
2409+
self._show_ignored_modules()
2410+
return
2411+
2412+
self.skip.add(module_name)
2413+
self.message(f'Ignoring module: {module_name}')
2414+
2415+
def do_unignore_module(self, arg):
2416+
"""unignore_module [module_name]
2417+
2418+
Remove a module from the list of modules to skip when stepping
2419+
or navigating frames. This will allow the debugger to step into
2420+
frames from the specified module.
2421+
2422+
Usage:
2423+
unignore_module threading # Stop ignoring threading module frames
2424+
unignore_module asyncio.* # Remove asyncio.* pattern
2425+
unignore_module # List currently ignored modules
2426+
"""
2427+
if self.skip is None:
2428+
self.skip = set()
2429+
2430+
module_name = arg.strip()
2431+
2432+
if not module_name:
2433+
self._show_ignored_modules()
2434+
return
2435+
2436+
try:
2437+
self.skip.remove(module_name)
2438+
self.message(f'No longer ignoring module: {module_name}')
2439+
except KeyError:
2440+
self.error(f'Module {module_name} is not currently ignored')
2441+
self._show_ignored_modules()
2442+
23302443
def do_alias(self, arg):
23312444
"""alias [name [command]]
23322445

‎Lib/test/test_pdb.py‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5021,5 +5021,123 @@ def tearDown(test):
50215021
return tests
50225022

50235023

5024+
def test_ignore_module():
5025+
"""Test the ignore_module and unignore_module commands.
5026+
5027+
>>> def modA_func():
5028+
... x = 1
5029+
... return x + 1
5030+
5031+
>>> def modB_func():
5032+
... import pdb; pdb.Pdb(nosigint=True, readrc=False).set_trace()
5033+
... result = modA_func()
5034+
... return result
5035+
5036+
Test basic ignore_module functionality:
5037+
5038+
>>> with PdbTestInput([
5039+
... 'ignore_module', # List when empty
5040+
... 'ignore_module __main__', # Ignore __main__
5041+
... 'ignore_module', # List ignored modules
5042+
... 'ignore_module test.*', # Add wildcard pattern
5043+
... 'ignore_module', # List again
5044+
... 'unignore_module __main__', # Remove __main__
5045+
... 'ignore_module', # List after removal
5046+
... 'unignore_module nonexistent', # Try to remove non-existent
5047+
... 'unignore_module test.*', # Remove pattern
5048+
... 'ignore_module', # List when empty again
5049+
... 'continue',
5050+
... ]):
5051+
... modB_func()
5052+
> <doctest test.test_pdb.test_ignore_module[1]>(2)modB_func()
5053+
-> import pdb; pdb.Pdb(nosigint=True, readrc=False).set_trace()
5054+
(Pdb) ignore_module
5055+
No modules are currently ignored.
5056+
(Pdb) ignore_module __main__
5057+
Ignoring module: __main__
5058+
(Pdb) ignore_module
5059+
Currently ignored modules: ['__main__']
5060+
(Pdb) ignore_module test.*
5061+
Ignoring module: test.*
5062+
(Pdb) ignore_module
5063+
Currently ignored modules: ['__main__', 'test.*']
5064+
(Pdb) unignore_module __main__
5065+
No longer ignoring module: __main__
5066+
(Pdb) ignore_module
5067+
Currently ignored modules: ['test.*']
5068+
(Pdb) unignore_module nonexistent
5069+
*** Module nonexistent is not currently ignored
5070+
Currently ignored modules: ['test.*']
5071+
(Pdb) unignore_module test.*
5072+
No longer ignoring module: test.*
5073+
(Pdb) ignore_module
5074+
No modules are currently ignored.
5075+
(Pdb) continue
5076+
"""
5077+
5078+
5079+
def test_ignore_module_navigation():
5080+
"""Test that ignore_module works with up/down commands.
5081+
5082+
>>> def level3_func():
5083+
... import pdb; pdb.Pdb(nosigint=True, readrc=False).set_trace()
5084+
... x = 1
5085+
... return x
5086+
5087+
>>> def level2_func():
5088+
... return level3_func()
5089+
5090+
>>> def level1_func():
5091+
... return level2_func()
5092+
5093+
Test navigation with ignored modules:
5094+
5095+
>>> with PdbTestInput([
5096+
... 'up', # Go to level2_func (no ignore)
5097+
... 'where',
5098+
... 'down', # Back to level3_func
5099+
... 'ignore_module __main__', # Ignore level2_func's module
5100+
... 'up', # Should skip level2_func, go to level1_func
5101+
... 'where',
5102+
... 'down', # Should skip back down
5103+
... 'where',
5104+
... 'continue',
5105+
... ]):
5106+
... level1_func()
5107+
> <doctest test.test_pdb.test_ignore_module_navigation[0]>(2)level3_func()
5108+
-> import pdb; pdb.Pdb(nosigint=True, readrc=False).set_trace()
5109+
(Pdb) up
5110+
> <doctest test.test_pdb.test_ignore_module_navigation[1]>(2)level2_func()
5111+
-> return level3_func()
5112+
(Pdb) where
5113+
<doctest test.test_pdb.test_ignore_module_navigation[2]>(2)level1_func()
5114+
<doctest test.test_pdb.test_ignore_module_navigation[1]>(2)level2_func()
5115+
> <doctest test.test_pdb.test_ignore_module_navigation[1]>(2)level2_func()
5116+
(Pdb) down
5117+
> <doctest test.test_pdb.test_ignore_module_navigation[0]>(2)level3_func()
5118+
-> import pdb; pdb.Pdb(nosigint=True, readrc=False).set_trace()
5119+
(Pdb) ignore_module __main__
5120+
Ignoring module: __main__
5121+
(Pdb) up
5122+
[... skipped 1 frame(s) from ignored modules]
5123+
> <doctest test.test_pdb.test_ignore_module_navigation[2]>(2)level1_func()
5124+
-> return level2_func()
5125+
(Pdb) where
5126+
<doctest test.test_pdb.test_ignore_module_navigation[2]>(2)level1_func()
5127+
<doctest test.test_pdb.test_ignore_module_navigation[1]>(2)level2_func()
5128+
<doctest test.test_pdb.test_ignore_module_navigation[0]>(2)level3_func()
5129+
> <doctest test.test_pdb.test_ignore_module_navigation[2]>(2)level1_func()
5130+
(Pdb) down
5131+
[... skipped 1 frame(s) from ignored modules]
5132+
> <doctest test.test_pdb.test_ignore_module_navigation[0]>(2)level3_func()
5133+
-> import pdb; pdb.Pdb(nosigint=True, readrc=False).set_trace()
5134+
(Pdb) where
5135+
<doctest test.test_pdb.test_ignore_module_navigation[2]>(2)level1_func()
5136+
<doctest test.test_pdb.test_ignore_module_navigation[1]>(2)level2_func()
5137+
> <doctest test.test_pdb.test_ignore_module_navigation[0]>(2)level3_func()
5138+
(Pdb) continue
5139+
"""
5140+
5141+
50245142
if __name__ == '__main__':
50255143
unittest.main()

‎Misc/NEWS.d/next/Library/2025-10-07-20-44-37.gh-issue-139721.N4dpE8.rst‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
Add ``ignore_module`` and ``unignore_module`` commands to :mod:`pdb` to
2+
allow skipping frames from specified modules during debugging. When a module
3+
is ignored, the debugger will automatically skip over its frames during
4+
step, next, continue, up, and down commands. Supports wildcard patterns via
5+
:mod:`fnmatch` for ignoring submodules.

0 commit comments

Comments
 (0)