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 | fc076d4 | 1998-09-17 15:01:38 +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 | fc076d4 | 1998-09-17 15:01:38 +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 | fc076d4 | 1998-09-17 15:01:38 +0000 | [diff] [blame] | 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. |
Guido van Rossum | f0a275d | 1998-09-12 14:42:23 +0000 | [diff] [blame] | 41 | |
Guido van Rossum | fc076d4 | 1998-09-17 15:01:38 +0000 | [diff] [blame] | 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. |
Guido van Rossum | f0a275d | 1998-09-12 14:42:23 +0000 | [diff] [blame] | 46 | |
| 47 | If a file ".pdbrc" exists in your home directory or in the current |
Guido van Rossum | fc076d4 | 1998-09-17 15:01:38 +0000 | [diff] [blame] | 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. |
Guido van Rossum | f0a275d | 1998-09-12 14:42:23 +0000 | [diff] [blame] | 52 | |
Guido van Rossum | fc076d4 | 1998-09-17 15:01:38 +0000 | [diff] [blame] | 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. |
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 | fc076d4 | 1998-09-17 15:01:38 +0000 | [diff] [blame] | 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). |
Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 65 | |
| 66 | w(here) |
Guido van Rossum | fc076d4 | 1998-09-17 15:01:38 +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 | fc076d4 | 1998-09-17 15:01:38 +0000 | [diff] [blame] | 72 | Move the current frame one level down in the stack trace |
Johannes Gijsbers | 34c4120 | 2004-08-14 15:19:28 +0000 | [diff] [blame] | 73 | (to a newer frame). |
Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 74 | |
| 75 | u(p) |
Guido van Rossum | fc076d4 | 1998-09-17 15:01:38 +0000 | [diff] [blame] | 76 | Move the current frame one level up in the stack trace |
Johannes Gijsbers | 34c4120 | 2004-08-14 15:19:28 +0000 | [diff] [blame] | 77 | (to an older frame). |
Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 78 | |
Guido van Rossum | fc076d4 | 1998-09-17 15:01:38 +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 |
| 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. |
Guido van Rossum | f60e8e8 | 1998-07-20 23:21:21 +0000 | [diff] [blame] | 86 | |
Guido van Rossum | fc076d4 | 1998-09-17 15:01:38 +0000 | [diff] [blame] | 87 | The condition argument, if present, is a string which must |
| 88 | evaluate to true in order for the breakpoint to be honored. |
Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 89 | |
Guido van Rossum | fc076d4 | 1998-09-17 15:01:38 +0000 | [diff] [blame] | 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. |
Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 93 | |
Guido van Rossum | f0a275d | 1998-09-12 14:42:23 +0000 | [diff] [blame] | 94 | cl(ear) [bpnumber [bpnumber ...] ] |
Guido van Rossum | fc076d4 | 1998-09-17 15:01:38 +0000 | [diff] [blame] | 95 | With a space separated list of breakpoint numbers, clear those |
| 96 | breakpoints. Without argument, clear all breaks (but first |
| 97 | ask confirmation). |
Guido van Rossum | f0a275d | 1998-09-12 14:42:23 +0000 | [diff] [blame] | 98 | |
| 99 | disable bpnumber [bpnumber ...] |
Guido van Rossum | fc076d4 | 1998-09-17 15:01:38 +0000 | [diff] [blame] | 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. |
Guido van Rossum | f0a275d | 1998-09-12 14:42:23 +0000 | [diff] [blame] | 105 | |
| 106 | enable bpnumber [bpnumber ...] |
Guido van Rossum | fc076d4 | 1998-09-17 15:01:38 +0000 | [diff] [blame] | 107 | Enables the breakpoints specified. |
Guido van Rossum | f0a275d | 1998-09-12 14:42:23 +0000 | [diff] [blame] | 108 | |
| 109 | ignore bpnumber count |
Guido van Rossum | fc076d4 | 1998-09-17 15:01:38 +0000 | [diff] [blame] | 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. |
Guido van Rossum | f0a275d | 1998-09-12 14:42:23 +0000 | [diff] [blame] | 116 | |
Guido van Rossum | fc076d4 | 1998-09-17 15:01:38 +0000 | [diff] [blame] | 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. |
Guido van Rossum | f60e8e8 | 1998-07-20 23:21:21 +0000 | [diff] [blame] | 122 | |
Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 123 | s(tep) |
Guido van Rossum | fc076d4 | 1998-09-17 15:01:38 +0000 | [diff] [blame] | 124 | Execute the current line, stop at the first possible occasion |
| 125 | (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] | 126 | |
| 127 | n(ext) |
Guido van Rossum | fc076d4 | 1998-09-17 15:01:38 +0000 | [diff] [blame] | 128 | Continue execution until the next line in the current function |
| 129 | is reached or it returns. |
Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 130 | |
| 131 | r(eturn) |
Guido van Rossum | fc076d4 | 1998-09-17 15:01:38 +0000 | [diff] [blame] | 132 | Continue execution until the current function returns. |
Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 133 | |
Guido van Rossum | d8faa36 | 2007-04-27 19:54:29 +0000 | [diff] [blame^] | 134 | run [args...] |
| 135 | Restart the debugged python program. If a string is supplied it is |
| 136 | splitted with "shlex", and the result is used as the new sys.argv. |
| 137 | History, breakpoints, actions and debugger options are preserved. |
| 138 | "restart" is an alias for "run". |
| 139 | |
Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 140 | c(ont(inue)) |
Guido van Rossum | fc076d4 | 1998-09-17 15:01:38 +0000 | [diff] [blame] | 141 | Continue execution, only stop when a breakpoint is encountered. |
Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 142 | |
| 143 | l(ist) [first [,last]] |
Guido van Rossum | fc076d4 | 1998-09-17 15:01:38 +0000 | [diff] [blame] | 144 | List source code for the current file. |
| 145 | Without arguments, list 11 lines around the current line |
| 146 | or continue the previous listing. |
| 147 | With one argument, list 11 lines starting at that line. |
| 148 | With two arguments, list the given range; |
| 149 | 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] | 150 | |
| 151 | a(rgs) |
Guido van Rossum | fc076d4 | 1998-09-17 15:01:38 +0000 | [diff] [blame] | 152 | Print the argument list of the current function. |
Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 153 | |
| 154 | p expression |
Guido van Rossum | fc076d4 | 1998-09-17 15:01:38 +0000 | [diff] [blame] | 155 | Print the value of the expression. |
Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 156 | |
| 157 | (!) statement |
Guido van Rossum | fc076d4 | 1998-09-17 15:01:38 +0000 | [diff] [blame] | 158 | Execute the (one-line) statement in the context of the current |
| 159 | stack frame. The exclamation point can be omitted unless the |
| 160 | first word of the statement resembles a debugger command. To |
| 161 | assign to a global variable you must always prefix the command |
| 162 | with a 'global' command, e.g.: |
| 163 | (Pdb) global list_options; list_options = ['-l'] |
| 164 | (Pdb) |
Guido van Rossum | f0a275d | 1998-09-12 14:42:23 +0000 | [diff] [blame] | 165 | |
| 166 | |
| 167 | whatis arg |
Guido van Rossum | fc076d4 | 1998-09-17 15:01:38 +0000 | [diff] [blame] | 168 | Prints the type of the argument. |
Guido van Rossum | f0a275d | 1998-09-12 14:42:23 +0000 | [diff] [blame] | 169 | |
| 170 | alias [name [command]] |
Guido van Rossum | fc076d4 | 1998-09-17 15:01:38 +0000 | [diff] [blame] | 171 | Creates an alias called 'name' that executes 'command'. The |
| 172 | command must *not* be enclosed in quotes. Replaceable |
| 173 | parameters can be indicated by %1, %2, and so on, while %* is |
| 174 | replaced by all the parameters. If no command is given, the |
| 175 | current alias for name is shown. If no name is given, all |
| 176 | aliases are listed. |
Guido van Rossum | f0a275d | 1998-09-12 14:42:23 +0000 | [diff] [blame] | 177 | |
Guido van Rossum | fc076d4 | 1998-09-17 15:01:38 +0000 | [diff] [blame] | 178 | Aliases may be nested and can contain anything that can be |
| 179 | legally typed at the pdb prompt. Note! You *can* override |
| 180 | internal pdb commands with aliases! Those internal commands |
| 181 | are then hidden until the alias is removed. Aliasing is |
| 182 | recursively applied to the first word of the command line; all |
| 183 | other words in the line are left alone. |
Guido van Rossum | f0a275d | 1998-09-12 14:42:23 +0000 | [diff] [blame] | 184 | |
Guido van Rossum | fc076d4 | 1998-09-17 15:01:38 +0000 | [diff] [blame] | 185 | As an example, here are two useful aliases (especially when |
| 186 | placed in the .pdbrc file): |
Guido van Rossum | f0a275d | 1998-09-12 14:42:23 +0000 | [diff] [blame] | 187 | |
Guido van Rossum | fc076d4 | 1998-09-17 15:01:38 +0000 | [diff] [blame] | 188 | #Print instance variables (usage "pi classInst") |
| 189 | alias pi for k in %1.__dict__.keys(): print "%1.",k,"=",%1.__dict__[k] |
| 190 | #Print instance variables in self |
| 191 | alias ps pi self |
| 192 | |
Guido van Rossum | f0a275d | 1998-09-12 14:42:23 +0000 | [diff] [blame] | 193 | unalias name |
Guido van Rossum | fc076d4 | 1998-09-17 15:01:38 +0000 | [diff] [blame] | 194 | Deletes the specified alias. |
Guido van Rossum | 3bead09 | 1992-01-27 17:00:37 +0000 | [diff] [blame] | 195 | |
| 196 | q(uit) |
Guido van Rossum | fc076d4 | 1998-09-17 15:01:38 +0000 | [diff] [blame] | 197 | Quit from the debugger. |
| 198 | The program being executed is aborted. |