blob: 6ae54e7e77fa41f1e0bc4ba1b1066a11a77d2353 [file] [log] [blame]
Guido van Rossum3bead091992-01-27 17:00:37 +00001The Python Debugger
2===================
3
4To use the debugger in its simplest form:
5
Guido van Rossum136a1121998-07-20 23:22:51 +00006 >>> import pdb
7 >>> pdb.run('<a statement>')
Guido van Rossum3bead091992-01-27 17:00:37 +00008
9The debugger's prompt is '(Pdb) '. This will stop in the first
10function call in <a statement>.
11
Guido van Rossum35771131992-09-08 11:59:04 +000012Alternatively, if a statement terminated with an unhandled exception,
13you can use pdb's post-mortem facility to inspect the contents of the
14traceback:
15
Guido van Rossum136a1121998-07-20 23:22:51 +000016 >>> <a statement>
17 <exception traceback>
18 >>> import pdb
19 >>> pdb.pm()
Guido van Rossum35771131992-09-08 11:59:04 +000020
Guido van Rossum3bead091992-01-27 17:00:37 +000021The commands recognized by the debugger are listed in the next
22section. Most can be abbreviated as indicated; e.g., h(elp) means
23that 'help' can be typed as 'h' or 'help' (but not as 'he' or 'hel',
24nor as 'H' or 'Help' or 'HELP'). Optional arguments are enclosed in
25square brackets.
26
27A blank line repeats the previous command literally. (Except for
28'list', where it lists the next 11 lines.)
29
30Commands that the debugger doesn't recognize are assumed to be Python
31statements and are executed in the context of the program being
32debugged. Python statements can also be prefixed with an exclamation
33point ('!'). This is a powerful way to inspect the program being
34debugged; it is even possible to change variables. When an exception
35occurs in such a statement, the exception name is printed but the
36debugger's state is not changed.
37
38The debugger is not directly programmable; but it is implemented as a
39class from which you can derive your own debugger class, so you can
40make as fancy as you like.
41
42
43Debugger commands
44=================
45
46h(elp)
Guido van Rossumf60e8e81998-07-20 23:21:21 +000047 Without argument, print the list of available commands.
48 With a command name as argument, print help about that command
49 "help pdb" pipes the full documentation file to the $PAGER
50 "help exec" gives help on the ! command
Guido van Rossum3bead091992-01-27 17:00:37 +000051
52w(here)
Guido van Rossum136a1121998-07-20 23:22:51 +000053 Print a stack trace, with the most recent frame at the bottom.
54 An arrow indicates the "current frame", which determines the
55 context of most commands.
Guido van Rossum3bead091992-01-27 17:00:37 +000056
57d(own)
Guido van Rossum136a1121998-07-20 23:22:51 +000058 Move the current frame one level down in the stack trace
59 (to an older frame).
Guido van Rossum3bead091992-01-27 17:00:37 +000060
61u(p)
Guido van Rossum136a1121998-07-20 23:22:51 +000062 Move the current frame one level up in the stack trace
63 (to a newer frame).
Guido van Rossum3bead091992-01-27 17:00:37 +000064
Guido van Rossumf60e8e81998-07-20 23:21:21 +000065b(reak) ([file:]lineno | function) [, "condition"]
66 With a line number argument, set a break there in the current
67 file. With a function name, set a break at the entry of that
68 function. Without argument, list all breaks. If a second
69 argument is present, it is a string specifying an expression
70 which must evaluate to true before the breakpoint is honored.
71
72 The line number may be prefixed with a filename and a colon,
73 to specify a breakpoint in another file (probably one that
74 hasn't been loaded yet). The file is searched on sys.path.
Guido van Rossum3bead091992-01-27 17:00:37 +000075
76cl(ear) [lineno]
Guido van Rossum136a1121998-07-20 23:22:51 +000077 With a line number argument, clear that break in the current file.
78 Without argument, clear all breaks (but first ask confirmation).
Guido van Rossum3bead091992-01-27 17:00:37 +000079
Guido van Rossumf60e8e81998-07-20 23:21:21 +000080 The line number may be prefixed with a filename and a colon,
81 to specify a breakpoint in another file (probably one that
82 hasn't been loaded yet). The file is searched on sys.path.
83
Guido van Rossum3bead091992-01-27 17:00:37 +000084s(tep)
Guido van Rossum136a1121998-07-20 23:22:51 +000085 Execute the current line, stop at the first possible occasion
86 (either in a function that is called or in the current function).
Guido van Rossum3bead091992-01-27 17:00:37 +000087
88n(ext)
Guido van Rossum136a1121998-07-20 23:22:51 +000089 Continue execution until the next line in the current function
90 is reached or it returns.
Guido van Rossum3bead091992-01-27 17:00:37 +000091
92r(eturn)
Guido van Rossum136a1121998-07-20 23:22:51 +000093 Continue execution until the current function returns.
Guido van Rossum3bead091992-01-27 17:00:37 +000094
95c(ont(inue))
Guido van Rossum136a1121998-07-20 23:22:51 +000096 Continue execution, only stop when a breakpoint is encountered.
Guido van Rossum3bead091992-01-27 17:00:37 +000097
98l(ist) [first [,last]]
Guido van Rossum136a1121998-07-20 23:22:51 +000099 List source code for the current file.
100 Without arguments, list 11 lines around the current line
101 or continue the previous listing.
102 With one argument, list 11 lines starting at that line.
103 With two arguments, list the given range;
104 if the second argument is less than the first, it is a count.
Guido van Rossum3bead091992-01-27 17:00:37 +0000105
106a(rgs)
Guido van Rossum136a1121998-07-20 23:22:51 +0000107 Print the argument list of the current function.
Guido van Rossum3bead091992-01-27 17:00:37 +0000108
109p expression
Guido van Rossum136a1121998-07-20 23:22:51 +0000110 Print the value of the expression.
Guido van Rossum3bead091992-01-27 17:00:37 +0000111
112(!) statement
Guido van Rossum136a1121998-07-20 23:22:51 +0000113 Execute the (one-line) statement in the context of
114 the current stack frame.
115 The exclamation point can be omitted unless the first word
116 of the statement resembles a debugger command.
117 To assign to a global variable you must always prefix the
118 command with a 'global' command, e.g.:
119 (Pdb) global list_options; list_options = ['-l']
120 (Pdb)
Guido van Rossum3bead091992-01-27 17:00:37 +0000121
122q(uit)
Guido van Rossum136a1121998-07-20 23:22:51 +0000123 Quit from the debugger.
124 The program being executed is aborted.