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. 203
