Guido van Rossum | f0a275d | 1998-09-12 14:42:23 +0000 | [diff] [blame^] | 1 | The Python Debugger Pdb |
| 2 | ======================= |
Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 3 | |
| 4 | To use the debugger in its simplest form: |
| 5 | |
Guido van Rossum | f0a275d | 1998-09-12 14:42:23 +0000 | [diff] [blame^] | 6 | >>> import pdb |
| 7 | >>> pdb.run('<a statement>') |
Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 8 | |
| 9 | The debugger's prompt is '(Pdb) '. This will stop in the first |
| 10 | function call in <a statement>. |
| 11 | |
Guido van Rossum | 3577113 | 1992-09-08 11:59:04 +0000 | [diff] [blame] | 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 | |
Guido van Rossum | f0a275d | 1998-09-12 14:42:23 +0000 | [diff] [blame^] | 16 | >>> <a statement> |
| 17 | <exception traceback> |
| 18 | >>> import pdb |
| 19 | >>> pdb.pm() |
Guido van Rossum | 3577113 | 1992-09-08 11:59:04 +0000 | [diff] [blame] | 20 | |
Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 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 | |
Guido van Rossum | f0a275d | 1998-09-12 14:42:23 +0000 | [diff] [blame^] | 27 | A blank line repeats the previous command literally, except for |
| 28 | 'list', where it lists the next 11 lines. |
Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 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 | |
Guido van Rossum | f0a275d | 1998-09-12 14:42:23 +0000 | [diff] [blame^] | 38 | The debugger supports aliases, which can save typing. And aliases |
| 39 | can have parameters (see the alias help entry) which allows one a |
| 40 | certain level of adaptability to the context under examination. |
| 41 | |
| 42 | Multiple commands may be entered on a single line, separated by |
| 43 | semi-colons. No intelligence is applied to separating the commands; |
| 44 | the input is split at the first ';', even if it is in the middle of |
| 45 | a 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 |
| 49 | the debugger prompt. This is particularly useful for aliases. |
| 50 | If both files exist, the one in the home directory is read first |
| 51 | and aliases defined there can be overriden by the local file. |
| 52 | |
| 53 | Aside from aliases, the debugger is not directly programmable; but |
| 54 | it is implemented as a class from which you can derive your own |
| 55 | debugger class, which you can make as fancy as you like. |
Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 56 | |
| 57 | |
| 58 | Debugger commands |
| 59 | ================= |
| 60 | |
| 61 | h(elp) |
Guido van Rossum | f0a275d | 1998-09-12 14:42:23 +0000 | [diff] [blame^] | 62 | Without argument, print the list of available commands. |
| 63 | With a command name as argument, print help about that command |
| 64 | (this is currently not implemented). |
Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 65 | |
| 66 | w(here) |
Guido van Rossum | f0a275d | 1998-09-12 14:42:23 +0000 | [diff] [blame^] | 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. |
Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 70 | |
| 71 | d(own) |
Guido van Rossum | f0a275d | 1998-09-12 14:42:23 +0000 | [diff] [blame^] | 72 | Move the current frame one level down in the stack trace |
| 73 | (to an older frame). |
Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 74 | |
| 75 | u(p) |
Guido van Rossum | f0a275d | 1998-09-12 14:42:23 +0000 | [diff] [blame^] | 76 | Move the current frame one level up in the stack trace |
| 77 | (to a newer frame). |
Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 78 | |
Guido van Rossum | f0a275d | 1998-09-12 14:42:23 +0000 | [diff] [blame^] | 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 name, |
| 82 | set a break at the first executable line of that function. |
| 83 | Without argument, list all breaks. Each breakpoint is assigned |
| 84 | a number which is by all the other breakpoint commands refer to it. |
Guido van Rossum | f60e8e8 | 1998-07-20 23:21:21 +0000 | [diff] [blame] | 85 | |
Guido van Rossum | f0a275d | 1998-09-12 14:42:23 +0000 | [diff] [blame^] | 86 | The condition argument, if present, is a string which must |
| 87 | evaluate to true in order for the breakpoint to be honored. |
Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 88 | |
Guido van Rossum | f0a275d | 1998-09-12 14:42:23 +0000 | [diff] [blame^] | 89 | tbreak [ ([filename:]lineno | function) [, "condition"] ] |
| 90 | Temporary breakpoint, which is removed automatically when it is |
| 91 | first hit. The arguments are the same as break. |
Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 92 | |
Guido van Rossum | f0a275d | 1998-09-12 14:42:23 +0000 | [diff] [blame^] | 93 | cl(ear) [bpnumber [bpnumber ...] ] |
| 94 | With a space separated list of breakpoint numbers, clear those |
| 95 | breakpoints. Without argument, clear all breaks (but first |
| 96 | ask confirmation). |
| 97 | |
| 98 | disable bpnumber [bpnumber ...] |
| 99 | Disables the breakpoints given as a space separated list of |
| 100 | breakpoint numbers. Disabling a breakpoint means it cannot cause |
| 101 | the program to stop execution, but unlike clearing a breakpoint, it |
| 102 | remains in the list of breakpoints and can be (re-)enabled. |
| 103 | |
| 104 | enable bpnumber [bpnumber ...] |
| 105 | Enables the breakpoints specified. |
| 106 | |
| 107 | ignore bpnumber count |
| 108 | Sets the ignore count for the given breakpoint number. If |
| 109 | count is omitted, the ignore count is set to 0. A breakpoint |
| 110 | becomes active when the ignore count is zero. When non-zero, |
| 111 | the count is decremented each time the breakpoint is reached |
| 112 | and the breakpoint is not disabled and any associated condition |
| 113 | evaluates to true. |
| 114 | |
| 115 | condition bpnumber str_condition |
| 116 | str_condition is a string specifying an expression which |
| 117 | must evaluate to true before the breakpoint is honored. |
| 118 | If str_condition is absent, any existing condition is removed; |
| 119 | i.e., the breakpoint is made unconditional. |
Guido van Rossum | f60e8e8 | 1998-07-20 23:21:21 +0000 | [diff] [blame] | 120 | |
Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 121 | s(tep) |
Guido van Rossum | f0a275d | 1998-09-12 14:42:23 +0000 | [diff] [blame^] | 122 | Execute the current line, stop at the first possible occasion |
| 123 | (either in a function that is called or in the current function). |
Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 124 | |
| 125 | n(ext) |
Guido van Rossum | f0a275d | 1998-09-12 14:42:23 +0000 | [diff] [blame^] | 126 | Continue execution until the next line in the current function |
| 127 | is reached or it returns. |
Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 128 | |
| 129 | r(eturn) |
Guido van Rossum | f0a275d | 1998-09-12 14:42:23 +0000 | [diff] [blame^] | 130 | Continue execution until the current function returns. |
Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 131 | |
| 132 | c(ont(inue)) |
Guido van Rossum | f0a275d | 1998-09-12 14:42:23 +0000 | [diff] [blame^] | 133 | Continue execution, only stop when a breakpoint is encountered. |
Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 134 | |
| 135 | l(ist) [first [,last]] |
Guido van Rossum | f0a275d | 1998-09-12 14:42:23 +0000 | [diff] [blame^] | 136 | List source code for the current file. |
| 137 | Without arguments, list 11 lines around the current line |
| 138 | or continue the previous listing. |
| 139 | With one argument, list 11 lines starting at that line. |
| 140 | With two arguments, list the given range; |
| 141 | if the second argument is less than the first, it is a count. |
Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 142 | |
| 143 | a(rgs) |
Guido van Rossum | f0a275d | 1998-09-12 14:42:23 +0000 | [diff] [blame^] | 144 | Print the argument list of the current function. |
Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 145 | |
| 146 | p expression |
Guido van Rossum | f0a275d | 1998-09-12 14:42:23 +0000 | [diff] [blame^] | 147 | Print the value of the expression. |
Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 148 | |
| 149 | (!) statement |
Guido van Rossum | f0a275d | 1998-09-12 14:42:23 +0000 | [diff] [blame^] | 150 | Execute the (one-line) statement in the context of the current |
| 151 | stack frame. The exclamation point can be omitted unless the |
| 152 | first word of the statement resembles a debugger command. |
| 153 | To assign to a global variable you must always prefix the |
| 154 | command with a 'global' command, e.g.: |
| 155 | (Pdb) global list_options; list_options = ['-l'] |
| 156 | (Pdb) |
| 157 | |
| 158 | |
| 159 | whatis arg |
| 160 | Prints the type of the argument. |
| 161 | |
| 162 | alias [name [command]] |
| 163 | Creates an alias called 'name' that executes 'command'. The command |
| 164 | must *not* be enclosed in quotes. Replaceable parameters can be |
| 165 | indicated by %1, %2, and so on, while %* is replaced by all the |
| 166 | parameters. If no command is given, the current alias for name |
| 167 | is shown. If no name is given, all aliases are listed. |
| 168 | |
| 169 | Aliases may be nested and can contain anything that can be |
| 170 | legally typed at the pdb prompt. Note! You *can* override |
| 171 | internal pdb commands with aliases! Those internal commands |
| 172 | are then hidden until the alias is removed. Aliasing is recursively |
| 173 | applied to the first word of the command line; all other words |
| 174 | in the line are left alone. |
| 175 | |
| 176 | As an example, here are two useful aliases (especially when placed |
| 177 | in the .pdbrc file): |
| 178 | |
| 179 | #Print instance variables (usage "pi classInst") |
| 180 | alias pi for k in %1.__dict__.keys(): print "%1." + k + "=" + %1.__dict__[k] |
| 181 | #Print instance variables in self |
| 182 | alias ps pi self |
| 183 | |
| 184 | unalias name |
| 185 | Deletes the specified alias. |
Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 186 | |
| 187 | q(uit) |
Guido van Rossum | f0a275d | 1998-09-12 14:42:23 +0000 | [diff] [blame^] | 188 | Quit from the debugger. |
| 189 | The program being executed is aborted. |
| 190 | |
| 191 | |
| 192 | How it works |
| 193 | ============ |
| 194 | |
| 195 | Some changes were made to the interpreter: |
| 196 | - sys.settrace(func) sets the global trace function |
| 197 | - there can also a local trace function (see later) |
| 198 | |
| 199 | Trace functions have three arguments: (frame, event, arg) |
| 200 | - frame is the current stack frame |
| 201 | - event is a string: 'call', 'line', 'return' or 'exception' |
| 202 | - arg is dependent on the event type |
| 203 | A trace function should return a new trace function or None. |
| 204 | Class methods are accepted (and most useful!) as trace methods. |
| 205 | |
| 206 | The events have the following meaning: |
| 207 | |
| 208 | 'call': A function is called (or some other code block entered). |
| 209 | The global trace function is called; |
| 210 | arg is the argument list to the function; |
| 211 | the return value specifies the local trace function. |
| 212 | |
| 213 | 'line': The interpreter is about to execute a new line of code |
| 214 | (sometimes multiple line events on one line exist). |
| 215 | The local trace function is called; arg in None; |
| 216 | the return value specifies the new local trace function. |
| 217 | |
| 218 | 'return': A function (or other code block) is about to return. |
| 219 | The local trace function is called; |
| 220 | arg is the value that will be returned. |
| 221 | The trace function's return value is ignored. |
| 222 | |
| 223 | 'exception': An exception has occurred. |
| 224 | The local trace function is called; |
| 225 | arg is a triple (exception, value, traceback); |
| 226 | the return value specifies the new local trace function |
| 227 | |
| 228 | Note that as an exception is propagated down the chain of callers, an |
| 229 | 'exception' event is generated at each level. |
| 230 | |
| 231 | Stack frame objects have the following read-only attributes: |
| 232 | f_code: the code object being executed |
| 233 | f_lineno: the current line number (-1 for 'call' events) |
| 234 | f_back: the stack frame of the caller, or None |
| 235 | f_locals: dictionary containing local name bindings |
| 236 | f_globals: dictionary containing global name bindings |
| 237 | |
| 238 | Code objects have the following read-only attributes: |
| 239 | co_code: the code string |
| 240 | co_names: the list of names used by the code |
| 241 | co_consts: the list of (literal) constants used by the code |
| 242 | co_filename: the filename from which the code was compiled |