|
1 The Python Debugger Pdb |
|
2 ======================= |
|
3 |
|
4 To use the debugger in its simplest form: |
|
5 |
|
6 >>> import pdb |
|
7 >>> pdb.run('<a statement>') |
|
8 |
|
9 The debugger's prompt is '(Pdb) '. This will stop in the first |
|
10 function call in <a statement>. |
|
11 |
|
12 Alternatively, if a statement terminated with an unhandled exception, |
|
13 you can use pdb's post-mortem facility to inspect the contents of the |
|
14 traceback: |
|
15 |
|
16 >>> <a statement> |
|
17 <exception traceback> |
|
18 >>> import pdb |
|
19 >>> pdb.pm() |
|
20 |
|
21 The commands recognized by the debugger are listed in the next |
|
22 section. Most can be abbreviated as indicated; e.g., h(elp) means |
|
23 that 'help' can be typed as 'h' or 'help' (but not as 'he' or 'hel', |
|
24 nor as 'H' or 'Help' or 'HELP'). Optional arguments are enclosed in |
|
25 square brackets. |
|
26 |
|
27 A blank line repeats the previous command literally, except for |
|
28 'list', where it lists the next 11 lines. |
|
29 |
|
30 Commands that the debugger doesn't recognize are assumed to be Python |
|
31 statements and are executed in the context of the program being |
|
32 debugged. Python statements can also be prefixed with an exclamation |
|
33 point ('!'). This is a powerful way to inspect the program being |
|
34 debugged; it is even possible to change variables. When an exception |
|
35 occurs in such a statement, the exception name is printed but the |
|
36 debugger's state is not changed. |
|
37 |
|
38 The debugger supports aliases, which can save typing. And aliases can |
|
39 have parameters (see the alias help entry) which allows one a certain |
|
40 level of adaptability to the context under examination. |
|
41 |
|
42 Multiple commands may be entered on a single line, separated by the |
|
43 pair ';;'. No intelligence is applied to separating the commands; the |
|
44 input is split at the first ';;', even if it is in the middle of a |
|
45 quoted string. |
|
46 |
|
47 If a file ".pdbrc" exists in your home directory or in the current |
|
48 directory, it is read in and executed as if it had been typed at the |
|
49 debugger prompt. This is particularly useful for aliases. If both |
|
50 files exist, the one in the home directory is read first and aliases |
|
51 defined there can be overriden by the local file. |
|
52 |
|
53 Aside from aliases, the debugger is not directly programmable; but it |
|
54 is implemented as a class from which you can derive your own debugger |
|
55 class, which you can make as fancy as you like. |
|
56 |
|
57 |
|
58 Debugger commands |
|
59 ================= |
|
60 |
|
61 h(elp) |
|
62 Without argument, print the list of available commands. With |
|
63 a command name as argument, print help about that command |
|
64 (this is currently not implemented). |
|
65 |
|
66 w(here) |
|
67 Print a stack trace, with the most recent frame at the bottom. |
|
68 An arrow indicates the "current frame", which determines the |
|
69 context of most commands. |
|
70 |
|
71 d(own) |
|
72 Move the current frame one level down in the stack trace |
|
73 (to a newer frame). |
|
74 |
|
75 u(p) |
|
76 Move the current frame one level up in the stack trace |
|
77 (to an older frame). |
|
78 |
|
79 b(reak) [ ([filename:]lineno | function) [, condition] ] |
|
80 With a filename:line number argument, set a break there. If |
|
81 filename is omitted, use the current file. With a function |
|
82 name, set a break at the first executable line of that |
|
83 function. Without argument, list all breaks. Each breakpoint |
|
84 is assigned a number to which all the other breakpoint |
|
85 commands refer. |
|
86 |
|
87 The condition argument, if present, is a string which must |
|
88 evaluate to true in order for the breakpoint to be honored. |
|
89 |
|
90 tbreak [ ([filename:]lineno | function) [, condition] ] |
|
91 Temporary breakpoint, which is removed automatically when it |
|
92 is first hit. The arguments are the same as break. |
|
93 |
|
94 cl(ear) [bpnumber [bpnumber ...] ] |
|
95 With a space separated list of breakpoint numbers, clear those |
|
96 breakpoints. Without argument, clear all breaks (but first |
|
97 ask confirmation). |
|
98 |
|
99 disable bpnumber [bpnumber ...] |
|
100 Disables the breakpoints given as a space separated list of |
|
101 breakpoint numbers. Disabling a breakpoint means it cannot |
|
102 cause the program to stop execution, but unlike clearing a |
|
103 breakpoint, it remains in the list of breakpoints and can be |
|
104 (re-)enabled. |
|
105 |
|
106 enable bpnumber [bpnumber ...] |
|
107 Enables the breakpoints specified. |
|
108 |
|
109 ignore bpnumber count |
|
110 Sets the ignore count for the given breakpoint number. If |
|
111 count is omitted, the ignore count is set to 0. A breakpoint |
|
112 becomes active when the ignore count is zero. When non-zero, |
|
113 the count is decremented each time the breakpoint is reached |
|
114 and the breakpoint is not disabled and any associated |
|
115 condition evaluates to true. |
|
116 |
|
117 condition bpnumber condition |
|
118 condition is an expression which must evaluate to true before |
|
119 the breakpoint is honored. If condition is absent, any |
|
120 existing condition is removed; i.e., the breakpoint is made |
|
121 unconditional. |
|
122 |
|
123 s(tep) |
|
124 Execute the current line, stop at the first possible occasion |
|
125 (either in a function that is called or in the current function). |
|
126 |
|
127 n(ext) |
|
128 Continue execution until the next line in the current function |
|
129 is reached or it returns. |
|
130 |
|
131 unt(il) |
|
132 Continue execution until the line with a number greater than the |
|
133 current one is reached or until the current frame returns. |
|
134 |
|
135 r(eturn) |
|
136 Continue execution until the current function returns. |
|
137 |
|
138 run [args...] |
|
139 Restart the debugged python program. If a string is supplied it is |
|
140 splitted with "shlex", and the result is used as the new sys.argv. |
|
141 History, breakpoints, actions and debugger options are preserved. |
|
142 "restart" is an alias for "run". |
|
143 |
|
144 c(ont(inue)) |
|
145 Continue execution, only stop when a breakpoint is encountered. |
|
146 |
|
147 l(ist) [first [,last]] |
|
148 List source code for the current file. |
|
149 Without arguments, list 11 lines around the current line |
|
150 or continue the previous listing. |
|
151 With one argument, list 11 lines starting at that line. |
|
152 With two arguments, list the given range; |
|
153 if the second argument is less than the first, it is a count. |
|
154 |
|
155 a(rgs) |
|
156 Print the argument list of the current function. |
|
157 |
|
158 p expression |
|
159 Print the value of the expression. |
|
160 |
|
161 (!) statement |
|
162 Execute the (one-line) statement in the context of the current |
|
163 stack frame. The exclamation point can be omitted unless the |
|
164 first word of the statement resembles a debugger command. To |
|
165 assign to a global variable you must always prefix the command |
|
166 with a 'global' command, e.g.: |
|
167 (Pdb) global list_options; list_options = ['-l'] |
|
168 (Pdb) |
|
169 |
|
170 |
|
171 whatis arg |
|
172 Prints the type of the argument. |
|
173 |
|
174 alias [name [command]] |
|
175 Creates an alias called 'name' that executes 'command'. The |
|
176 command must *not* be enclosed in quotes. Replaceable |
|
177 parameters can be indicated by %1, %2, and so on, while %* is |
|
178 replaced by all the parameters. If no command is given, the |
|
179 current alias for name is shown. If no name is given, all |
|
180 aliases are listed. |
|
181 |
|
182 Aliases may be nested and can contain anything that can be |
|
183 legally typed at the pdb prompt. Note! You *can* override |
|
184 internal pdb commands with aliases! Those internal commands |
|
185 are then hidden until the alias is removed. Aliasing is |
|
186 recursively applied to the first word of the command line; all |
|
187 other words in the line are left alone. |
|
188 |
|
189 As an example, here are two useful aliases (especially when |
|
190 placed in the .pdbrc file): |
|
191 |
|
192 #Print instance variables (usage "pi classInst") |
|
193 alias pi for k in %1.__dict__.keys(): print "%1.",k,"=",%1.__dict__[k] |
|
194 #Print instance variables in self |
|
195 alias ps pi self |
|
196 |
|
197 unalias name |
|
198 Deletes the specified alias. |
|
199 |
|
200 q(uit) |
|
201 Quit from the debugger. |
|
202 The program being executed is aborted. |