1The Python Debugger Pdb 2======================= 3 4To use the debugger in its simplest form: 5 6 >>> import pdb 7 >>> pdb.run('<a statement>') 8 9The debugger's prompt is '(Pdb) '. This will stop in the first 10function call in <a statement>. 11 12Alternatively, if a statement terminated with an unhandled exception, 13you can use pdb's post-mortem facility to inspect the contents of the 14traceback: 15 16 >>> <a statement> 17 <exception traceback> 18 >>> import pdb 19 >>> pdb.pm() 20 21The 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 supports aliases, which can save typing. And aliases can 39have parameters (see the alias help entry) which allows one a certain 40level of adaptability to the context under examination. 41 42Multiple commands may be entered on a single line, separated by the 43pair ';;'. No intelligence is applied to separating the commands; the 44input is split at the first ';;', even if it is in the middle of a 45quoted string. 46 47If a file ".pdbrc" exists in your home directory or in the current 48directory, it is read in and executed as if it had been typed at the 49debugger prompt. This is particularly useful for aliases. If both 50files exist, the one in the home directory is read first and aliases 51defined there can be overridden by the local file. 52 53Aside from aliases, the debugger is not directly programmable; but it 54is implemented as a class from which you can derive your own debugger 55class, which you can make as fancy as you like. 56 57 58Debugger commands 59================= 60 61h(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 66w(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 71d(own) 72 Move the current frame one level down in the stack trace 73 (to a newer frame). 74 75u(p) 76 Move the current frame one level up in the stack trace 77 (to an older frame). 78 79b(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 90tbreak [ ([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 94cl(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 99disable 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 106enable bpnumber [bpnumber ...] 107 Enables the breakpoints specified. 108 109ignore 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 117condition 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 123s(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 127n(ext) 128 Continue execution until the next line in the current function 129 is reached or it returns. 130 131unt(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 135r(eturn) 136 Continue execution until the current function returns. 137 138run [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 144c(ont(inue)) 145 Continue execution, only stop when a breakpoint is encountered. 146 147l(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 155a(rgs) 156 Print the argument list of the current function. 157 158p 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 171whatis arg 172 Prints the type of the argument. 173 174alias [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 197unalias name 198 Deletes the specified alias. 199 200q(uit) 201 Quit from the debugger. 202 The program being executed is aborted. 203