1
#! /usr/bin/env python3
4
The Python Debugger Pdb
5
=======================
7
To use the debugger in its simplest form:
10
>>> pdb.run('<a statement>')
12
The debugger's prompt is '(Pdb) '. This will stop in the first
13
function call in <a statement>.
15
Alternatively, if a statement terminated with an unhandled exception,
16
you can use pdb's post-mortem facility to inspect the contents of the
24
The commands recognized by the debugger are listed in the next
25
section. Most can be abbreviated as indicated; e.g., h(elp) means
26
that 'help' can be typed as 'h' or 'help' (but not as 'he' or 'hel',
27
nor as 'H' or 'Help' or 'HELP'). Optional arguments are enclosed in
28
square brackets. Alternatives in the command syntax are separated
29
by a vertical bar (|).
31
A blank line repeats the previous command literally, except for
32
'list', where it lists the next 11 lines.
34
Commands that the debugger doesn't recognize are assumed to be Python
35
statements and are executed in the context of the program being
36
debugged. Python statements can also be prefixed with an exclamation
37
point ('!'). This is a powerful way to inspect the program being
38
debugged; it is even possible to change variables or call functions.
39
When an exception occurs in such a statement, the exception name is
40
printed but the debugger's state is not changed.
42
The debugger supports aliases, which can save typing. And aliases can
43
have parameters (see the alias help entry) which allows one a certain
44
level of adaptability to the context under examination.
46
Multiple commands may be entered on a single line, separated by the
47
pair ';;'. No intelligence is applied to separating the commands; the
48
input is split at the first ';;', even if it is in the middle of a
51
If a file ".pdbrc" exists in your home directory or in the current
52
directory, it is read in and executed as if it had been typed at the
53
debugger prompt. This is particularly useful for aliases. If both
54
files exist, the one in the home directory is read first and aliases
55
defined there can be overriden by the local file.
57
Aside from aliases, the debugger is not directly programmable; but it
58
is implemented as a class from which you can derive your own debugger
59
class, which you can make as fancy as you like.
66
# NOTE: the actual command documentation is collected from docstrings of the
67
# commands and is appended to __doc__ after the class has been defined.
84
class Restart(Exception):
85
"""Causes a debugger to be restarted for the debugged python program."""
88
__all__ = ["run", "pm", "Pdb", "runeval", "runctx", "runcall", "set_trace",
89
"post_mortem", "help"]
91
def find_function(funcname, filename):
92
cre = re.compile(r'def\s+%s\s*[(]' % re.escape(funcname))
97
# consumer of this info expects the first line to be 1
99
for lineno, line in enumerate(fp, start=1):
101
return funcname, filename, lineno
104
def getsourcelines(obj):
105
lines, lineno = inspect.findsource(obj)
106
if inspect.isframe(obj) and obj.f_globals is obj.f_locals:
107
# must be a module frame: do not try to cut a block out of it
109
elif inspect.ismodule(obj):
111
return inspect.getblock(lines[lineno:]), lineno+1
113
def lasti2lineno(code, lasti):
114
linestarts = list(dis.findlinestarts(code))
116
for i, lineno in linestarts:
123
"""String that doesn't quote its repr."""
128
# Interaction prompt line will separate file and call info from code
129
# text using value of line_prefix string. A newline and arrow may
130
# be to your liking. You can set it once pdb is imported using the
131
# command "pdb.line_prefix = '\n% '".
132
# line_prefix = ': ' # Use this to get the old situation back
133
line_prefix = '\n-> ' # Probably a better default
135
class Pdb(bdb.Bdb, cmd.Cmd):
137
def __init__(self, completekey='tab', stdin=None, stdout=None, skip=None,
139
bdb.Bdb.__init__(self, skip=skip)
140
cmd.Cmd.__init__(self, completekey, stdin, stdout)
142
self.use_rawinput = 0
143
self.prompt = '(Pdb) '
147
self._wait_for_mainpyfile = False
149
# Try to load readline if it exists
152
# remove some common file name delimiters
153
readline.set_completer_delims(' \t\n`@#$%^&*()=+[{]}\\|;:\'",<>?')
156
self.allow_kbdint = False
157
self.nosigint = nosigint
159
# Read $HOME/.pdbrc and ./.pdbrc
161
if 'HOME' in os.environ:
162
envHome = os.environ['HOME']
164
with open(os.path.join(envHome, ".pdbrc")) as rcFile:
165
self.rcLines.extend(rcFile)
169
with open(".pdbrc") as rcFile:
170
self.rcLines.extend(rcFile)
174
self.commands = {} # associates a command list to breakpoint numbers
175
self.commands_doprompt = {} # for each bp num, tells if the prompt
176
# must be disp. after execing the cmd list
177
self.commands_silent = {} # for each bp num, tells if the stack trace
178
# must be disp. after execing the cmd list
179
self.commands_defining = False # True while in the process of defining
181
self.commands_bnum = None # The breakpoint number for which we are
184
def sigint_handler(self, signum, frame):
185
if self.allow_kbdint:
186
raise KeyboardInterrupt
187
self.message("\nProgram interrupted. (Use 'cont' to resume).")
189
self.set_trace(frame)
190
# restore previous signal handler
191
signal.signal(signal.SIGINT, self._previous_sigint_handler)
202
self.tb_lineno.clear()
204
def setup(self, f, tb):
206
self.stack, self.curindex = self.get_stack(f, tb)
208
# when setting up post-mortem debugging with a traceback, save all
209
# the original line numbers to be displayed along the current line
210
# numbers (which can be different, e.g. due to finally clauses)
211
lineno = lasti2lineno(tb.tb_frame.f_code, tb.tb_lasti)
212
self.tb_lineno[tb.tb_frame] = lineno
214
self.curframe = self.stack[self.curindex][0]
215
# The f_locals dictionary is updated from the actual frame
216
# locals whenever the .f_locals accessor is called, so we
217
# cache it here to ensure that modifications are not overwritten.
218
self.curframe_locals = self.curframe.f_locals
219
return self.execRcLines()
221
# Can be executed earlier than 'setup' if desired
222
def execRcLines(self):
225
# local copy because of recursion
226
rcLines = self.rcLines
228
# execute every line only once
231
line = rcLines.pop().strip()
232
if line and line[0] != '#':
233
if self.onecmd(line):
234
# if onecmd returns True, the command wants to exit
235
# from the interaction, save leftover rc lines
236
# to execute before next interaction
237
self.rcLines += reversed(rcLines)
240
# Override Bdb methods
242
def user_call(self, frame, argument_list):
243
"""This method is called when there is the remote possibility
244
that we ever need to stop in this function."""
245
if self._wait_for_mainpyfile:
247
if self.stop_here(frame):
248
self.message('--Call--')
249
self.interaction(frame, None)
251
def user_line(self, frame):
252
"""This function is called when we stop or break at this line."""
253
if self._wait_for_mainpyfile:
254
if (self.mainpyfile != self.canonic(frame.f_code.co_filename)
255
or frame.f_lineno <= 0):
257
self._wait_for_mainpyfile = False
258
if self.bp_commands(frame):
259
self.interaction(frame, None)
261
def bp_commands(self, frame):
262
"""Call every command that was set for the current active breakpoint
265
Returns True if the normal interaction function must be called,
267
# self.currentbp is set in bdb in Bdb.break_here if a breakpoint was hit
268
if getattr(self, "currentbp", False) and \
269
self.currentbp in self.commands:
270
currentbp = self.currentbp
272
lastcmd_back = self.lastcmd
273
self.setup(frame, None)
274
for line in self.commands[currentbp]:
276
self.lastcmd = lastcmd_back
277
if not self.commands_silent[currentbp]:
278
self.print_stack_entry(self.stack[self.curindex])
279
if self.commands_doprompt[currentbp]:
285
def user_return(self, frame, return_value):
286
"""This function is called when a return trap is set here."""
287
if self._wait_for_mainpyfile:
289
frame.f_locals['__return__'] = return_value
290
self.message('--Return--')
291
self.interaction(frame, None)
293
def user_exception(self, frame, exc_info):
294
"""This function is called if an exception occurs,
295
but only if we are to stop at or just below this level."""
296
if self._wait_for_mainpyfile:
298
exc_type, exc_value, exc_traceback = exc_info
299
frame.f_locals['__exception__'] = exc_type, exc_value
301
# An 'Internal StopIteration' exception is an exception debug event
302
# issued by the interpreter when handling a subgenerator run with
303
# 'yield from' or a generator controled by a for loop. No exception has
304
# actually occured in this case. The debugger uses this debug event to
305
# stop when the debuggee is returning from such generators.
306
prefix = 'Internal ' if (not exc_traceback
307
and exc_type is StopIteration) else ''
308
self.message('%s%s' % (prefix,
309
traceback.format_exception_only(exc_type, exc_value)[-1].strip()))
310
self.interaction(frame, exc_traceback)
312
# General interaction function
316
# keyboard interrupts allow for an easy way to cancel
317
# the current command, so allow them during interactive input
318
self.allow_kbdint = True
320
self.allow_kbdint = False
322
except KeyboardInterrupt:
323
self.message('--KeyboardInterrupt--')
325
# Called before loop, handles display expressions
327
displaying = self.displaying.get(self.curframe)
329
for expr, oldvalue in displaying.items():
330
newvalue = self._getval_except(expr)
331
# check for identity first; this prevents custom __eq__ to
332
# be called at every loop, and also prevents instances whose
333
# fields are changed to be displayed
334
if newvalue is not oldvalue and newvalue != oldvalue:
335
displaying[expr] = newvalue
336
self.message('display %s: %r [old: %r]' %
337
(expr, newvalue, oldvalue))
339
def interaction(self, frame, traceback):
340
if self.setup(frame, traceback):
341
# no interaction desired at this time (happens if .pdbrc contains
342
# a command like "continue")
345
self.print_stack_entry(self.stack[self.curindex])
349
def displayhook(self, obj):
350
"""Custom displayhook for the exec in default(), which prevents
351
assignment of the _ variable in the builtins.
353
# reproduce the behavior of the standard displayhook, not printing None
355
self.message(repr(obj))
357
def default(self, line):
358
if line[:1] == '!': line = line[1:]
359
locals = self.curframe_locals
360
globals = self.curframe.f_globals
362
code = compile(line + '\n', '<stdin>', 'single')
363
save_stdout = sys.stdout
364
save_stdin = sys.stdin
365
save_displayhook = sys.displayhook
367
sys.stdin = self.stdin
368
sys.stdout = self.stdout
369
sys.displayhook = self.displayhook
370
exec(code, globals, locals)
372
sys.stdout = save_stdout
373
sys.stdin = save_stdin
374
sys.displayhook = save_displayhook
376
exc_info = sys.exc_info()[:2]
377
self.error(traceback.format_exception_only(*exc_info)[-1].strip())
379
def precmd(self, line):
380
"""Handle alias expansion and ';;' separator."""
384
while args[0] in self.aliases:
385
line = self.aliases[args[0]]
387
for tmpArg in args[1:]:
388
line = line.replace("%" + str(ii),
391
line = line.replace("%*", ' '.join(args[1:]))
393
# split into ';;' separated commands
394
# unless it's an alias command
395
if args[0] != 'alias':
396
marker = line.find(';;')
398
# queue up everything after marker
399
next = line[marker+2:].lstrip()
400
self.cmdqueue.append(next)
401
line = line[:marker].rstrip()
404
def onecmd(self, line):
405
"""Interpret the argument as though it had been typed in response
408
Checks whether this line is typed at the normal prompt or in
409
a breakpoint command list definition.
411
if not self.commands_defining:
412
return cmd.Cmd.onecmd(self, line)
414
return self.handle_command_def(line)
416
def handle_command_def(self, line):
417
"""Handles one command line during command list definition."""
418
cmd, arg, line = self.parseline(line)
422
self.commands_silent[self.commands_bnum] = True
423
return # continue to handle other cmd def in the cmd list
426
return 1 # end of cmd list
427
cmdlist = self.commands[self.commands_bnum]
429
cmdlist.append(cmd+' '+arg)
432
# Determine if we must stop
434
func = getattr(self, 'do_' + cmd)
435
except AttributeError:
437
# one of the resuming commands
438
if func.__name__ in self.commands_resuming:
439
self.commands_doprompt[self.commands_bnum] = False
444
# interface abstraction functions
446
def message(self, msg):
447
print(msg, file=self.stdout)
449
def error(self, msg):
450
print('***', msg, file=self.stdout)
452
# Generic completion functions. Individual complete_foo methods can be
453
# assigned below to one of these functions.
455
def _complete_location(self, text, line, begidx, endidx):
456
# Complete a file/module/function location for break/tbreak/clear.
457
if line.strip().endswith((':', ',')):
458
# Here comes a line number or a condition which we can't complete.
460
# First, try to find matching functions (i.e. expressions).
462
ret = self._complete_expression(text, line, begidx, endidx)
465
# Then, try to complete file names as well.
466
globs = glob.glob(text + '*')
468
if os.path.isdir(fn):
470
elif os.path.isfile(fn) and fn.lower().endswith(('.py', '.pyw')):
474
def _complete_bpnumber(self, text, line, begidx, endidx):
475
# Complete a breakpoint number. (This would be more helpful if we could
476
# display additional info along with the completions, such as file/line
477
# of the breakpoint.)
478
return [str(i) for i, bp in enumerate(bdb.Breakpoint.bpbynumber)
479
if bp is not None and str(i).startswith(text)]
481
def _complete_expression(self, text, line, begidx, endidx):
482
# Complete an arbitrary expression.
483
if not self.curframe:
485
# Collect globals and locals. It is usually not really sensible to also
486
# complete builtins, and they clutter the namespace quite heavily, so we
488
ns = self.curframe.f_globals.copy()
489
ns.update(self.curframe_locals)
491
# Walk an attribute chain up to the last part, similar to what
492
# rlcompleter does. This will bail if any of the parts are not
493
# simple attribute access, which is what we want.
494
dotted = text.split('.')
497
for part in dotted[1:-1]:
498
obj = getattr(obj, part)
499
except (KeyError, AttributeError):
501
prefix = '.'.join(dotted[:-1]) + '.'
502
return [prefix + n for n in dir(obj) if n.startswith(dotted[-1])]
504
# Complete a simple name.
505
return [n for n in ns.keys() if n.startswith(text)]
507
# Command definitions, called by cmdloop()
508
# The argument is the remaining string on the command line
509
# Return true to exit from the command loop
511
def do_commands(self, arg):
512
"""commands [bpnumber]
517
Specify a list of commands for breakpoint number bpnumber.
518
The commands themselves are entered on the following lines.
519
Type a line containing just 'end' to terminate the commands.
520
The commands are executed when the breakpoint is hit.
522
To remove all commands from a breakpoint, type commands and
523
follow it immediately with end; that is, give no commands.
525
With no bpnumber argument, commands refers to the last
528
You can use breakpoint commands to start your program up
529
again. Simply use the continue command, or step, or any other
530
command that resumes execution.
532
Specifying any command resuming execution (currently continue,
533
step, next, return, jump, quit and their abbreviations)
534
terminates the command list (as if that command was
535
immediately followed by end). This is because any time you
536
resume execution (even with a simple next or step), you may
537
encounter another breakpoint -- which could have its own
538
command list, leading to ambiguities about which list to
541
If you use the 'silent' command in the command list, the usual
542
message about stopping at a breakpoint is not printed. This
543
may be desirable for breakpoints that are to print a specific
544
message and then continue. If none of the other commands
545
print anything, you will see no sign that the breakpoint was
549
bnum = len(bdb.Breakpoint.bpbynumber) - 1
554
self.error("Usage: commands [bnum]\n ...\n end")
556
self.commands_bnum = bnum
557
# Save old definitions for the case of a keyboard interrupt.
558
if bnum in self.commands:
559
old_command_defs = (self.commands[bnum],
560
self.commands_doprompt[bnum],
561
self.commands_silent[bnum])
563
old_command_defs = None
564
self.commands[bnum] = []
565
self.commands_doprompt[bnum] = True
566
self.commands_silent[bnum] = False
568
prompt_back = self.prompt
569
self.prompt = '(com) '
570
self.commands_defining = True
573
except KeyboardInterrupt:
574
# Restore old definitions.
576
self.commands[bnum] = old_command_defs[0]
577
self.commands_doprompt[bnum] = old_command_defs[1]
578
self.commands_silent[bnum] = old_command_defs[2]
580
del self.commands[bnum]
581
del self.commands_doprompt[bnum]
582
del self.commands_silent[bnum]
583
self.error('command definition aborted, old commands restored')
585
self.commands_defining = False
586
self.prompt = prompt_back
588
complete_commands = _complete_bpnumber
590
def do_break(self, arg, temporary = 0):
591
"""b(reak) [ ([filename:]lineno | function) [, condition] ]
592
Without argument, list all breaks.
594
With a line number argument, set a break at this line in the
595
current file. With a function name, set a break at the first
596
executable line of that function. If a second argument is
597
present, it is a string specifying an expression which must
598
evaluate to true before the breakpoint is honored.
600
The line number may be prefixed with a filename and a colon,
601
to specify a breakpoint in another file (probably one that
602
hasn't been loaded yet). The file is searched for on
603
sys.path; the .py suffix may be omitted.
606
if self.breaks: # There's at least one
607
self.message("Num Type Disp Enb Where")
608
for bp in bdb.Breakpoint.bpbynumber:
610
self.message(bp.bpformat())
612
# parse arguments; comma has lowest precedence
613
# and cannot occur in filename
617
comma = arg.find(',')
619
# parse stuff after comma: "condition"
620
cond = arg[comma+1:].lstrip()
621
arg = arg[:comma].rstrip()
622
# parse stuff before comma: [filename:]lineno | function
623
colon = arg.rfind(':')
626
filename = arg[:colon].rstrip()
627
f = self.lookupmodule(filename)
629
self.error('%r not found from sys.path' % filename)
633
arg = arg[colon+1:].lstrip()
637
self.error('Bad lineno: %s' % arg)
640
# no colon; can be lineno or function
646
self.curframe.f_globals,
647
self.curframe_locals)
651
if hasattr(func, '__func__'):
654
#use co_name to identify the bkpt (function names
655
#could be aliased, but co_name is invariant)
656
funcname = code.co_name
657
lineno = code.co_firstlineno
658
filename = code.co_filename
661
(ok, filename, ln) = self.lineinfo(arg)
663
self.error('The specified object %r is not a function '
664
'or was not found along sys.path.' % arg)
666
funcname = ok # ok contains a function name
669
filename = self.defaultFile()
670
# Check for reasonable breakpoint
671
line = self.checkline(filename, lineno)
673
# now set the break point
674
err = self.set_break(filename, line, temporary, cond, funcname)
676
self.error(err, file=self.stdout)
678
bp = self.get_breaks(filename, line)[-1]
679
self.message("Breakpoint %d at %s:%d" %
680
(bp.number, bp.file, bp.line))
682
# To be overridden in derived debuggers
683
def defaultFile(self):
684
"""Produce a reasonable default."""
685
filename = self.curframe.f_code.co_filename
686
if filename == '<string>' and self.mainpyfile:
687
filename = self.mainpyfile
692
complete_break = _complete_location
693
complete_b = _complete_location
695
def do_tbreak(self, arg):
696
"""tbreak [ ([filename:]lineno | function) [, condition] ]
697
Same arguments as break, but sets a temporary breakpoint: it
698
is automatically deleted when first hit.
700
self.do_break(arg, 1)
702
complete_tbreak = _complete_location
704
def lineinfo(self, identifier):
705
failed = (None, None, None)
706
# Input is identifier, may be in single quotes
707
idstring = identifier.split("'")
708
if len(idstring) == 1:
709
# not in single quotes
710
id = idstring[0].strip()
711
elif len(idstring) == 3:
713
id = idstring[1].strip()
716
if id == '': return failed
717
parts = id.split('.')
718
# Protection for derived debuggers
719
if parts[0] == 'self':
723
# Best first guess at file to look at
724
fname = self.defaultFile()
728
# More than one part.
729
# First is module, second is method/class
730
f = self.lookupmodule(parts[0])
734
answer = find_function(item, fname)
735
return answer or failed
737
def checkline(self, filename, lineno):
738
"""Check whether specified line seems to be executable.
740
Return `lineno` if it is, 0 if not (e.g. a docstring, comment, blank
741
line or EOF). Warning: testing is not comprehensive.
743
# this method should be callable before starting debugging, so default
744
# to "no globals" if there is no current frame
745
globs = self.curframe.f_globals if hasattr(self, 'curframe') else None
746
line = linecache.getline(filename, lineno, globs)
748
self.message('End of file')
751
# Don't allow setting breakpoint at a blank line
752
if (not line or (line[0] == '#') or
753
(line[:3] == '"""') or line[:3] == "'''"):
754
self.error('Blank or comment')
758
def do_enable(self, arg):
759
"""enable bpnumber [bpnumber ...]
760
Enables the breakpoints given as a space separated list of
766
bp = self.get_bpbynumber(i)
767
except ValueError as err:
771
self.message('Enabled %s' % bp)
773
complete_enable = _complete_bpnumber
775
def do_disable(self, arg):
776
"""disable bpnumber [bpnumber ...]
777
Disables the breakpoints given as a space separated list of
778
breakpoint numbers. Disabling a breakpoint means it cannot
779
cause the program to stop execution, but unlike clearing a
780
breakpoint, it remains in the list of breakpoints and can be
786
bp = self.get_bpbynumber(i)
787
except ValueError as err:
791
self.message('Disabled %s' % bp)
793
complete_disable = _complete_bpnumber
795
def do_condition(self, arg):
796
"""condition bpnumber [condition]
797
Set a new condition for the breakpoint, an expression which
798
must evaluate to true before the breakpoint is honored. If
799
condition is absent, any existing condition is removed; i.e.,
800
the breakpoint is made unconditional.
802
args = arg.split(' ', 1)
808
bp = self.get_bpbynumber(args[0].strip())
810
self.error('Breakpoint number expected')
811
except ValueError as err:
816
self.message('Breakpoint %d is now unconditional.' % bp.number)
818
self.message('New condition set for breakpoint %d.' % bp.number)
820
complete_condition = _complete_bpnumber
822
def do_ignore(self, arg):
823
"""ignore bpnumber [count]
824
Set the ignore count for the given breakpoint number. If
825
count is omitted, the ignore count is set to 0. A breakpoint
826
becomes active when the ignore count is zero. When non-zero,
827
the count is decremented each time the breakpoint is reached
828
and the breakpoint is not disabled and any associated
829
condition evaluates to true.
833
count = int(args[1].strip())
837
bp = self.get_bpbynumber(args[0].strip())
839
self.error('Breakpoint number expected')
840
except ValueError as err:
846
countstr = '%d crossings' % count
848
countstr = '1 crossing'
849
self.message('Will ignore next %s of breakpoint %d.' %
850
(countstr, bp.number))
852
self.message('Will stop next time breakpoint %d is reached.'
855
complete_ignore = _complete_bpnumber
857
def do_clear(self, arg):
858
"""cl(ear) filename:lineno\ncl(ear) [bpnumber [bpnumber...]]
859
With a space separated list of breakpoint numbers, clear
860
those breakpoints. Without argument, clear all breaks (but
861
first ask confirmation). With a filename:lineno argument,
862
clear all breaks at that line in that file.
866
reply = input('Clear all breaks? ')
869
reply = reply.strip().lower()
870
if reply in ('y', 'yes'):
871
bplist = [bp for bp in bdb.Breakpoint.bpbynumber if bp]
872
self.clear_all_breaks()
874
self.message('Deleted %s' % bp)
877
# Make sure it works for "clear C:\foo\bar.py:12"
884
err = "Invalid line number (%s)" % arg
886
bplist = self.get_breaks(filename, lineno)
887
err = self.clear_break(filename, lineno)
892
self.message('Deleted %s' % bp)
894
numberlist = arg.split()
897
bp = self.get_bpbynumber(i)
898
except ValueError as err:
901
self.clear_bpbynumber(i)
902
self.message('Deleted %s' % bp)
903
do_cl = do_clear # 'c' is already an abbreviation for 'continue'
905
complete_clear = _complete_location
906
complete_cl = _complete_location
908
def do_where(self, arg):
910
Print a stack trace, with the most recent frame at the bottom.
911
An arrow indicates the "current frame", which determines the
912
context of most commands. 'bt' is an alias for this command.
914
self.print_stack_trace()
918
def _select_frame(self, number):
919
assert 0 <= number < len(self.stack)
920
self.curindex = number
921
self.curframe = self.stack[self.curindex][0]
922
self.curframe_locals = self.curframe.f_locals
923
self.print_stack_entry(self.stack[self.curindex])
926
def do_up(self, arg):
928
Move the current frame count (default one) levels up in the
929
stack trace (to an older frame).
931
if self.curindex == 0:
932
self.error('Oldest frame')
935
count = int(arg or 1)
937
self.error('Invalid frame count (%s)' % arg)
942
newframe = max(0, self.curindex - count)
943
self._select_frame(newframe)
946
def do_down(self, arg):
948
Move the current frame count (default one) levels down in the
949
stack trace (to a newer frame).
951
if self.curindex + 1 == len(self.stack):
952
self.error('Newest frame')
955
count = int(arg or 1)
957
self.error('Invalid frame count (%s)' % arg)
960
newframe = len(self.stack) - 1
962
newframe = min(len(self.stack) - 1, self.curindex + count)
963
self._select_frame(newframe)
966
def do_until(self, arg):
968
Without argument, continue execution until the line with a
969
number greater than the current one is reached. With a line
970
number, continue execution until a line with a number greater
971
or equal to that is reached. In both cases, also stop when
972
the current frame returns.
978
self.error('Error in argument: %r' % arg)
980
if lineno <= self.curframe.f_lineno:
981
self.error('"until" line number is smaller than current '
986
self.set_until(self.curframe, lineno)
990
def do_step(self, arg):
992
Execute the current line, stop at the first possible occasion
993
(either in a function that is called or in the current
1000
def do_next(self, arg):
1002
Continue execution until the next line in the current function
1003
is reached or it returns.
1005
self.set_next(self.curframe)
1009
def do_run(self, arg):
1011
Restart the debugged python program. If a string is supplied
1012
it is split with "shlex", and the result is used as the new
1013
sys.argv. History, breakpoints, actions and debugger options
1014
are preserved. "restart" is an alias for "run".
1018
argv0 = sys.argv[0:1]
1019
sys.argv = shlex.split(arg)
1020
sys.argv[:0] = argv0
1021
# this is caught in the main debugger loop
1026
def do_return(self, arg):
1028
Continue execution until the current function returns.
1030
self.set_return(self.curframe)
1034
def do_continue(self, arg):
1036
Continue execution, only stop when a breakpoint is encountered.
1038
if not self.nosigint:
1040
self._previous_sigint_handler = \
1041
signal.signal(signal.SIGINT, self.sigint_handler)
1043
# ValueError happens when do_continue() is invoked from
1044
# a non-main thread in which case we just continue without
1045
# SIGINT set. Would printing a message here (once) make
1050
do_c = do_cont = do_continue
1052
def do_jump(self, arg):
1054
Set the next line that will be executed. Only available in
1055
the bottom-most frame. This lets you jump back and execute
1056
code again, or jump forward to skip code that you don't want
1059
It should be noted that not all jumps are allowed -- for
1060
instance it is not possible to jump into the middle of a
1061
for loop or out of a finally clause.
1063
if self.curindex + 1 != len(self.stack):
1064
self.error('You can only jump within the bottom frame')
1069
self.error("The 'jump' command requires a line number")
1072
# Do the jump, fix up our copy of the stack, and display the
1074
self.curframe.f_lineno = arg
1075
self.stack[self.curindex] = self.stack[self.curindex][0], arg
1076
self.print_stack_entry(self.stack[self.curindex])
1077
except ValueError as e:
1078
self.error('Jump failed: %s' % e)
1081
def do_debug(self, arg):
1083
Enter a recursive debugger that steps through the code
1084
argument (which is an arbitrary expression or statement to be
1085
executed in the current environment).
1088
globals = self.curframe.f_globals
1089
locals = self.curframe_locals
1090
p = Pdb(self.completekey, self.stdin, self.stdout)
1091
p.prompt = "(%s) " % self.prompt.strip()
1092
self.message("ENTERING RECURSIVE DEBUGGER")
1093
sys.call_tracing(p.run, (arg, globals, locals))
1094
self.message("LEAVING RECURSIVE DEBUGGER")
1095
sys.settrace(self.trace_dispatch)
1096
self.lastcmd = p.lastcmd
1098
complete_debug = _complete_expression
1100
def do_quit(self, arg):
1102
Quit from the debugger. The program being executed is aborted.
1104
self._user_requested_quit = True
1111
def do_EOF(self, arg):
1113
Handles the receipt of EOF as a command.
1116
self._user_requested_quit = True
1120
def do_args(self, arg):
1122
Print the argument list of the current function.
1124
co = self.curframe.f_code
1125
dict = self.curframe_locals
1127
if co.co_flags & 4: n = n+1
1128
if co.co_flags & 8: n = n+1
1130
name = co.co_varnames[i]
1132
self.message('%s = %r' % (name, dict[name]))
1134
self.message('%s = *** undefined ***' % (name,))
1137
def do_retval(self, arg):
1139
Print the return value for the last return of a function.
1141
if '__return__' in self.curframe_locals:
1142
self.message(repr(self.curframe_locals['__return__']))
1144
self.error('Not yet returned!')
1147
def _getval(self, arg):
1149
return eval(arg, self.curframe.f_globals, self.curframe_locals)
1151
exc_info = sys.exc_info()[:2]
1152
self.error(traceback.format_exception_only(*exc_info)[-1].strip())
1155
def _getval_except(self, arg, frame=None):
1158
return eval(arg, self.curframe.f_globals, self.curframe_locals)
1160
return eval(arg, frame.f_globals, frame.f_locals)
1162
exc_info = sys.exc_info()[:2]
1163
err = traceback.format_exception_only(*exc_info)[-1].strip()
1164
return _rstr('** raised %s **' % err)
1166
def do_p(self, arg):
1168
Print the value of the expression.
1171
self.message(repr(self._getval(arg)))
1175
def do_pp(self, arg):
1177
Pretty-print the value of the expression.
1180
self.message(pprint.pformat(self._getval(arg)))
1184
complete_print = _complete_expression
1185
complete_p = _complete_expression
1186
complete_pp = _complete_expression
1188
def do_list(self, arg):
1189
"""l(ist) [first [,last] | .]
1191
List source code for the current file. Without arguments,
1192
list 11 lines around the current line or continue the previous
1193
listing. With . as argument, list 11 lines around the current
1194
line. With one argument, list 11 lines starting at that line.
1195
With two arguments, list the given range; if the second
1196
argument is less than the first, it is a count.
1198
The current line in the current frame is indicated by "->".
1199
If an exception is being debugged, the line where the
1200
exception was originally raised or propagated is indicated by
1201
">>", if it differs from the current line.
1203
self.lastcmd = 'list'
1205
if arg and arg != '.':
1208
first, last = arg.split(',')
1209
first = int(first.strip())
1210
last = int(last.strip())
1212
# assume it's a count
1215
first = int(arg.strip())
1216
first = max(1, first - 5)
1218
self.error('Error in argument: %r' % arg)
1220
elif self.lineno is None or arg == '.':
1221
first = max(1, self.curframe.f_lineno - 5)
1223
first = self.lineno + 1
1226
filename = self.curframe.f_code.co_filename
1227
breaklist = self.get_file_breaks(filename)
1229
lines = linecache.getlines(filename, self.curframe.f_globals)
1230
self._print_lines(lines[first-1:last], first, breaklist,
1232
self.lineno = min(last, len(lines))
1233
if len(lines) < last:
1234
self.message('[EOF]')
1235
except KeyboardInterrupt:
1239
def do_longlist(self, arg):
1241
List the whole source code for the current function or frame.
1243
filename = self.curframe.f_code.co_filename
1244
breaklist = self.get_file_breaks(filename)
1246
lines, lineno = getsourcelines(self.curframe)
1247
except OSError as err:
1250
self._print_lines(lines, lineno, breaklist, self.curframe)
1253
def do_source(self, arg):
1254
"""source expression
1255
Try to get source code for the given object and display it.
1258
obj = self._getval(arg)
1262
lines, lineno = getsourcelines(obj)
1263
except (OSError, TypeError) as err:
1266
self._print_lines(lines, lineno)
1268
complete_source = _complete_expression
1270
def _print_lines(self, lines, start, breaks=(), frame=None):
1271
"""Print a range of lines."""
1273
current_lineno = frame.f_lineno
1274
exc_lineno = self.tb_lineno.get(frame, -1)
1276
current_lineno = exc_lineno = -1
1277
for lineno, line in enumerate(lines, start):
1278
s = str(lineno).rjust(3)
1281
if lineno in breaks:
1285
if lineno == current_lineno:
1287
elif lineno == exc_lineno:
1289
self.message(s + '\t' + line.rstrip())
1291
def do_whatis(self, arg):
1293
Print the type of the argument.
1296
value = self._getval(arg)
1298
# _getval() already printed the error
1303
code = value.__code__
1307
self.message('Function %s' % code.co_name)
1309
# Is it an instance method?
1311
code = value.__func__.__code__
1315
self.message('Method %s' % code.co_name)
1318
if value.__class__ is type:
1319
self.message('Class %s.%s' % (value.__module__, value.__name__))
1321
# None of the above...
1322
self.message(type(value))
1324
complete_whatis = _complete_expression
1326
def do_display(self, arg):
1327
"""display [expression]
1329
Display the value of the expression if it changed, each time execution
1330
stops in the current frame.
1332
Without expression, list all display expressions for the current frame.
1335
self.message('Currently displaying:')
1336
for item in self.displaying.get(self.curframe, {}).items():
1337
self.message('%s: %r' % item)
1339
val = self._getval_except(arg)
1340
self.displaying.setdefault(self.curframe, {})[arg] = val
1341
self.message('display %s: %r' % (arg, val))
1343
complete_display = _complete_expression
1345
def do_undisplay(self, arg):
1346
"""undisplay [expression]
1348
Do not display the expression any more in the current frame.
1350
Without expression, clear all display expressions for the current frame.
1354
del self.displaying.get(self.curframe, {})[arg]
1356
self.error('not displaying %s' % arg)
1358
self.displaying.pop(self.curframe, None)
1360
def complete_undisplay(self, text, line, begidx, endidx):
1361
return [e for e in self.displaying.get(self.curframe, {})
1362
if e.startswith(text)]
1364
def do_interact(self, arg):
1367
Start an interactive interpreter whose global namespace
1368
contains all the (global and local) names found in the current scope.
1370
ns = self.curframe.f_globals.copy()
1371
ns.update(self.curframe_locals)
1372
code.interact("*interactive*", local=ns)
1374
def do_alias(self, arg):
1375
"""alias [name [command [parameter parameter ...] ]]
1376
Create an alias called 'name' that executes 'command'. The
1377
command must *not* be enclosed in quotes. Replaceable
1378
parameters can be indicated by %1, %2, and so on, while %* is
1379
replaced by all the parameters. If no command is given, the
1380
current alias for name is shown. If no name is given, all
1383
Aliases may be nested and can contain anything that can be
1384
legally typed at the pdb prompt. Note! You *can* override
1385
internal pdb commands with aliases! Those internal commands
1386
are then hidden until the alias is removed. Aliasing is
1387
recursively applied to the first word of the command line; all
1388
other words in the line are left alone.
1390
As an example, here are two useful aliases (especially when
1391
placed in the .pdbrc file):
1393
# Print instance variables (usage "pi classInst")
1394
alias pi for k in %1.__dict__.keys(): print("%1.",k,"=",%1.__dict__[k])
1395
# Print instance variables in self
1400
keys = sorted(self.aliases.keys())
1402
self.message("%s = %s" % (alias, self.aliases[alias]))
1404
if args[0] in self.aliases and len(args) == 1:
1405
self.message("%s = %s" % (args[0], self.aliases[args[0]]))
1407
self.aliases[args[0]] = ' '.join(args[1:])
1409
def do_unalias(self, arg):
1411
Delete the specified alias.
1414
if len(args) == 0: return
1415
if args[0] in self.aliases:
1416
del self.aliases[args[0]]
1418
def complete_unalias(self, text, line, begidx, endidx):
1419
return [a for a in self.aliases if a.startswith(text)]
1421
# List of all the commands making the program resume execution.
1422
commands_resuming = ['do_continue', 'do_step', 'do_next', 'do_return',
1423
'do_quit', 'do_jump']
1425
# Print a traceback starting at the top stack frame.
1426
# The most recently entered frame is printed last;
1427
# this is different from dbx and gdb, but consistent with
1428
# the Python interpreter's stack trace.
1429
# It is also consistent with the up/down commands (which are
1430
# compatible with dbx and gdb: up moves towards 'main()'
1431
# and down moves towards the most recent stack frame).
1433
def print_stack_trace(self):
1435
for frame_lineno in self.stack:
1436
self.print_stack_entry(frame_lineno)
1437
except KeyboardInterrupt:
1440
def print_stack_entry(self, frame_lineno, prompt_prefix=line_prefix):
1441
frame, lineno = frame_lineno
1442
if frame is self.curframe:
1446
self.message(prefix +
1447
self.format_stack_entry(frame_lineno, prompt_prefix))
1451
def do_help(self, arg):
1453
Without argument, print the list of available commands.
1454
With a command name as argument, print help about that command.
1455
"help pdb" shows the full pdb documentation.
1456
"help exec" gives help on the ! command.
1459
return cmd.Cmd.do_help(self, arg)
1462
topic = getattr(self, 'help_' + arg)
1464
except AttributeError:
1465
command = getattr(self, 'do_' + arg)
1466
except AttributeError:
1467
self.error('No help for %r' % arg)
1469
if sys.flags.optimize >= 2:
1470
self.error('No help for %r; please do not run Python with -OO '
1471
'if you need command help' % arg)
1473
self.message(command.__doc__.rstrip())
1477
def help_exec(self):
1479
Execute the (one-line) statement in the context of the current
1480
stack frame. The exclamation point can be omitted unless the
1481
first word of the statement resembles a debugger command. To
1482
assign to a global variable you must always prefix the command
1483
with a 'global' command, e.g.:
1484
(Pdb) global list_options; list_options = ['-l']
1487
self.message((self.help_exec.__doc__ or '').strip())
1492
# other helper functions
1494
def lookupmodule(self, filename):
1495
"""Helper function for break/clear parsing -- may be overridden.
1497
lookupmodule() translates (possibly incomplete) file or module name
1498
into an absolute file name.
1500
if os.path.isabs(filename) and os.path.exists(filename):
1502
f = os.path.join(sys.path[0], filename)
1503
if os.path.exists(f) and self.canonic(f) == self.mainpyfile:
1505
root, ext = os.path.splitext(filename)
1507
filename = filename + '.py'
1508
if os.path.isabs(filename):
1510
for dirname in sys.path:
1511
while os.path.islink(dirname):
1512
dirname = os.readlink(dirname)
1513
fullname = os.path.join(dirname, filename)
1514
if os.path.exists(fullname):
1518
def _runscript(self, filename):
1519
# The script has to run in __main__ namespace (or imports from
1520
# __main__ will break).
1522
# So we clear up the __main__ and set several special variables
1523
# (this gets rid of pdb's globals and cleans old variables on restarts).
1525
__main__.__dict__.clear()
1526
__main__.__dict__.update({"__name__" : "__main__",
1527
"__file__" : filename,
1528
"__builtins__": __builtins__,
1531
# When bdb sets tracing, a number of call and line events happens
1532
# BEFORE debugger even reaches user's code (and the exact sequence of
1533
# events depends on python version). So we take special measures to
1534
# avoid stopping before we reach the main script (see user_line and
1535
# user_call for details).
1536
self._wait_for_mainpyfile = True
1537
self.mainpyfile = self.canonic(filename)
1538
self._user_requested_quit = False
1539
with open(filename, "rb") as fp:
1540
statement = "exec(compile(%r, %r, 'exec'))" % \
1541
(fp.read(), self.mainpyfile)
1544
# Collect all command help into docstring, if not run with -OO
1546
if __doc__ is not None:
1547
# unfortunately we can't guess this order from the class definition
1549
'help', 'where', 'down', 'up', 'break', 'tbreak', 'clear', 'disable',
1550
'enable', 'ignore', 'condition', 'commands', 'step', 'next', 'until',
1551
'jump', 'return', 'retval', 'run', 'continue', 'list', 'longlist',
1552
'args', 'p', 'pp', 'whatis', 'source', 'display', 'undisplay',
1553
'interact', 'alias', 'unalias', 'debug', 'quit',
1556
for _command in _help_order:
1557
__doc__ += getattr(Pdb, 'do_' + _command).__doc__.strip() + '\n\n'
1558
__doc__ += Pdb.help_exec.__doc__
1560
del _help_order, _command
1563
# Simplified interface
1565
def run(statement, globals=None, locals=None):
1566
Pdb().run(statement, globals, locals)
1568
def runeval(expression, globals=None, locals=None):
1569
return Pdb().runeval(expression, globals, locals)
1571
def runctx(statement, globals, locals):
1573
run(statement, globals, locals)
1575
def runcall(*args, **kwds):
1576
return Pdb().runcall(*args, **kwds)
1579
Pdb().set_trace(sys._getframe().f_back)
1581
# Post-Mortem interface
1583
def post_mortem(t=None):
1584
# handling the default
1586
# sys.exc_info() returns (type, value, traceback) if an exception is
1587
# being handled, otherwise it returns None
1588
t = sys.exc_info()[2]
1590
raise ValueError("A valid traceback must be passed if no "
1591
"exception is being handled")
1595
p.interaction(None, t)
1598
post_mortem(sys.last_traceback)
1601
# Main program for testing
1603
TESTCMD = 'import x; x.main()'
1611
pydoc.pager(__doc__)
1614
usage: pdb.py [-c command] ... pyfile [arg] ...
1616
Debug the Python program given by pyfile.
1618
Initial commands are read from .pdbrc files in your home directory
1619
and in the current directory, if they exist. Commands supplied with
1620
-c are executed after commands from .pdbrc files.
1622
To let the script run until an exception occurs, use "-c continue".
1623
To let the script run up to a given line X in the debugged file, use
1629
opts, args = getopt.getopt(sys.argv[1:], 'hc:', ['--help', '--command='])
1636
for opt, optarg in opts:
1637
if opt in ['-h', '--help']:
1640
elif opt in ['-c', '--command']:
1641
commands.append(optarg)
1643
mainpyfile = args[0] # Get script filename
1644
if not os.path.exists(mainpyfile):
1645
print('Error:', mainpyfile, 'does not exist')
1648
sys.argv[:] = args # Hide "pdb.py" and pdb options from argument list
1650
# Replace pdb's dir with script's dir in front of module search path.
1651
sys.path[0] = os.path.dirname(mainpyfile)
1653
# Note on saving/restoring sys.argv: it's a good idea when sys.argv was
1654
# modified by the script being debugged. It's a bad idea when it was
1655
# changed by the user from the command line. There is a "restart" command
1656
# which allows explicit specification of command line arguments.
1658
pdb.rcLines.extend(commands)
1661
pdb._runscript(mainpyfile)
1662
if pdb._user_requested_quit:
1664
print("The program finished and will be restarted")
1666
print("Restarting", mainpyfile, "with arguments:")
1667
print("\t" + " ".join(args))
1669
# In most cases SystemExit does not warrant a post-mortem session.
1670
print("The program exited via sys.exit(). Exit status:", end=' ')
1671
print(sys.exc_info()[1])
1673
traceback.print_exc()
1674
print("Uncaught exception. Entering post mortem debugging")
1675
print("Running 'cont' or 'step' will restart the program")
1676
t = sys.exc_info()[2]
1677
pdb.interaction(None, t)
1678
print("Post mortem debugger finished. The " + mainpyfile +
1679
" will be restarted")
1682
# When invoked as main program, invoke the debugger on a script
1683
if __name__ == '__main__':
added
removed
Lib/pdb.py
