Commit | Line | Data |
---|---|---|
920dae64 AT |
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 | r(eturn) | |
132 | Continue execution until the current function returns. | |
133 | ||
134 | c(ont(inue)) | |
135 | Continue execution, only stop when a breakpoint is encountered. | |
136 | ||
137 | l(ist) [first [,last]] | |
138 | List source code for the current file. | |
139 | Without arguments, list 11 lines around the current line | |
140 | or continue the previous listing. | |
141 | With one argument, list 11 lines starting at that line. | |
142 | With two arguments, list the given range; | |
143 | if the second argument is less than the first, it is a count. | |
144 | ||
145 | a(rgs) | |
146 | Print the argument list of the current function. | |
147 | ||
148 | p expression | |
149 | Print the value of the expression. | |
150 | ||
151 | (!) statement | |
152 | Execute the (one-line) statement in the context of the current | |
153 | stack frame. The exclamation point can be omitted unless the | |
154 | first word of the statement resembles a debugger command. To | |
155 | assign to a global variable you must always prefix the command | |
156 | with a 'global' command, e.g.: | |
157 | (Pdb) global list_options; list_options = ['-l'] | |
158 | (Pdb) | |
159 | ||
160 | ||
161 | whatis arg | |
162 | Prints the type of the argument. | |
163 | ||
164 | alias [name [command]] | |
165 | Creates an alias called 'name' that executes 'command'. The | |
166 | command must *not* be enclosed in quotes. Replaceable | |
167 | parameters can be indicated by %1, %2, and so on, while %* is | |
168 | replaced by all the parameters. If no command is given, the | |
169 | current alias for name is shown. If no name is given, all | |
170 | aliases are listed. | |
171 | ||
172 | Aliases may be nested and can contain anything that can be | |
173 | legally typed at the pdb prompt. Note! You *can* override | |
174 | internal pdb commands with aliases! Those internal commands | |
175 | are then hidden until the alias is removed. Aliasing is | |
176 | recursively applied to the first word of the command line; all | |
177 | other words in the line are left alone. | |
178 | ||
179 | As an example, here are two useful aliases (especially when | |
180 | placed in the .pdbrc file): | |
181 | ||
182 | #Print instance variables (usage "pi classInst") | |
183 | alias pi for k in %1.__dict__.keys(): print "%1.",k,"=",%1.__dict__[k] | |
184 | #Print instance variables in self | |
185 | alias ps pi self | |
186 | ||
187 | unalias name | |
188 | Deletes the specified alias. | |
189 | ||
190 | q(uit) | |
191 | Quit from the debugger. | |
192 | The program being executed is aborted. |