Fred Drake | 1a2302b | 2001-07-18 17:40:19 +0000 | [diff] [blame] | 1 | \chapter{The Python Debugger \label{debugger}} |
Fred Drake | c8993aa | 1999-04-22 16:50:40 +0000 | [diff] [blame] | 2 | |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 3 | \declaremodule{standard}{pdb} |
Fred Drake | c8993aa | 1999-04-22 16:50:40 +0000 | [diff] [blame] | 4 | \modulesynopsis{The Python debugger for interactive interpreters.} |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 5 | |
Guido van Rossum | f4aac48 | 1995-03-02 12:37:55 +0000 | [diff] [blame] | 6 | |
Fred Drake | c8993aa | 1999-04-22 16:50:40 +0000 | [diff] [blame] | 7 | The module \module{pdb} defines an interactive source code |
| 8 | debugger\index{debugging} for Python programs. It supports setting |
| 9 | (conditional) breakpoints and single stepping at the source line |
| 10 | level, inspection of stack frames, source code listing, and evaluation |
| 11 | of arbitrary Python code in the context of any stack frame. It also |
| 12 | supports post-mortem debugging and can be called under program |
| 13 | control. |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 14 | |
Fred Drake | c8993aa | 1999-04-22 16:50:40 +0000 | [diff] [blame] | 15 | The debugger is extensible --- it is actually defined as the class |
| 16 | \class{Pdb}\withsubitem{(class in pdb)}{\ttindex{Pdb}}. |
Fred Drake | 82d493f | 1998-04-07 19:14:17 +0000 | [diff] [blame] | 17 | This is currently undocumented but easily understood by reading the |
Fred Drake | c8993aa | 1999-04-22 16:50:40 +0000 | [diff] [blame] | 18 | source. The extension interface uses the modules |
| 19 | \module{bdb}\refstmodindex{bdb} (undocumented) and |
| 20 | \refmodule{cmd}\refstmodindex{cmd}. |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 21 | |
Fred Drake | 82d493f | 1998-04-07 19:14:17 +0000 | [diff] [blame] | 22 | The debugger's prompt is \samp{(Pdb) }. |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 23 | Typical usage to run a program under control of the debugger is: |
| 24 | |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 25 | \begin{verbatim} |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 26 | >>> import pdb |
| 27 | >>> import mymodule |
| 28 | >>> pdb.run('mymodule.test()') |
Guido van Rossum | 25f6fcc | 1995-04-04 12:28:53 +0000 | [diff] [blame] | 29 | > <string>(0)?() |
| 30 | (Pdb) continue |
| 31 | > <string>(1)?() |
| 32 | (Pdb) continue |
| 33 | NameError: 'spam' |
| 34 | > <string>(1)?() |
| 35 | (Pdb) |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 36 | \end{verbatim} |
Fred Drake | 82d493f | 1998-04-07 19:14:17 +0000 | [diff] [blame] | 37 | |
| 38 | \file{pdb.py} can also be invoked as |
Guido van Rossum | 809408e | 1997-06-02 17:28:16 +0000 | [diff] [blame] | 39 | a script to debug other scripts. For example: |
Fred Drake | 82d493f | 1998-04-07 19:14:17 +0000 | [diff] [blame] | 40 | |
| 41 | \begin{verbatim} |
Raymond Hettinger | 700d9b9 | 2004-11-07 06:18:37 +0000 | [diff] [blame] | 42 | python -m pdb myscript.py |
Fred Drake | 82d493f | 1998-04-07 19:14:17 +0000 | [diff] [blame] | 43 | \end{verbatim} |
Guido van Rossum | 809408e | 1997-06-02 17:28:16 +0000 | [diff] [blame] | 44 | |
Raymond Hettinger | a2325f6 | 2004-11-18 08:39:33 +0000 | [diff] [blame] | 45 | When invoked as a script, pdb will automatically enter post-mortem debugging |
| 46 | if the program being debugged exits abnormally. After post-mortem debugging |
| 47 | (or after normal exit of the program), pdb will restart the program. |
| 48 | Automatic restarting preserves pdb's state (such as breakpoints) and in most |
| 49 | cases is more useful than quitting the debugger upon program's exit. |
| 50 | \versionadded[Restarting post-mortem behavior added]{2.4} |
| 51 | |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 52 | Typical usage to inspect a crashed program is: |
| 53 | |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 54 | \begin{verbatim} |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 55 | >>> import pdb |
| 56 | >>> import mymodule |
| 57 | >>> mymodule.test() |
Fred Drake | 162c6a6 | 2001-02-14 03:20:18 +0000 | [diff] [blame] | 58 | Traceback (most recent call last): |
Guido van Rossum | 25f6fcc | 1995-04-04 12:28:53 +0000 | [diff] [blame] | 59 | File "<stdin>", line 1, in ? |
| 60 | File "./mymodule.py", line 4, in test |
| 61 | test2() |
| 62 | File "./mymodule.py", line 3, in test2 |
| 63 | print spam |
| 64 | NameError: spam |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 65 | >>> pdb.pm() |
Guido van Rossum | 25f6fcc | 1995-04-04 12:28:53 +0000 | [diff] [blame] | 66 | > ./mymodule.py(3)test2() |
| 67 | -> print spam |
| 68 | (Pdb) |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 69 | \end{verbatim} |
Fred Drake | 82d493f | 1998-04-07 19:14:17 +0000 | [diff] [blame] | 70 | |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 71 | The module defines the following functions; each enters the debugger |
| 72 | in a slightly different way: |
| 73 | |
Fred Drake | cce1090 | 1998-03-17 06:33:25 +0000 | [diff] [blame] | 74 | \begin{funcdesc}{run}{statement\optional{, globals\optional{, locals}}} |
Guido van Rossum | f4aac48 | 1995-03-02 12:37:55 +0000 | [diff] [blame] | 75 | Execute the \var{statement} (given as a string) under debugger |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 76 | control. The debugger prompt appears before any code is executed; you |
Fred Drake | c8993aa | 1999-04-22 16:50:40 +0000 | [diff] [blame] | 77 | can set breakpoints and type \samp{continue}, or you can step through |
| 78 | the statement using \samp{step} or \samp{next} (all these commands are |
Guido van Rossum | f4aac48 | 1995-03-02 12:37:55 +0000 | [diff] [blame] | 79 | explained below). The optional \var{globals} and \var{locals} |
| 80 | arguments specify the environment in which the code is executed; by |
Fred Drake | 7a666b8 | 2000-09-14 20:32:17 +0000 | [diff] [blame] | 81 | default the dictionary of the module \refmodule[main]{__main__} is |
| 82 | used. (See the explanation of the \keyword{exec} statement or the |
Fred Drake | c8993aa | 1999-04-22 16:50:40 +0000 | [diff] [blame] | 83 | \function{eval()} built-in function.) |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 84 | \end{funcdesc} |
| 85 | |
Fred Drake | cce1090 | 1998-03-17 06:33:25 +0000 | [diff] [blame] | 86 | \begin{funcdesc}{runeval}{expression\optional{, globals\optional{, locals}}} |
Raymond Hettinger | 999b57c | 2003-08-25 04:28:05 +0000 | [diff] [blame] | 87 | Evaluate the \var{expression} (given as a string) under debugger |
Fred Drake | c8993aa | 1999-04-22 16:50:40 +0000 | [diff] [blame] | 88 | control. When \function{runeval()} returns, it returns the value of the |
Guido van Rossum | f4aac48 | 1995-03-02 12:37:55 +0000 | [diff] [blame] | 89 | expression. Otherwise this function is similar to |
Fred Drake | c8993aa | 1999-04-22 16:50:40 +0000 | [diff] [blame] | 90 | \function{run()}. |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 91 | \end{funcdesc} |
| 92 | |
Fred Drake | cce1090 | 1998-03-17 06:33:25 +0000 | [diff] [blame] | 93 | \begin{funcdesc}{runcall}{function\optional{, argument, ...}} |
Guido van Rossum | f4aac48 | 1995-03-02 12:37:55 +0000 | [diff] [blame] | 94 | Call the \var{function} (a function or method object, not a string) |
Fred Drake | c8993aa | 1999-04-22 16:50:40 +0000 | [diff] [blame] | 95 | with the given arguments. When \function{runcall()} returns, it returns |
Guido van Rossum | f4aac48 | 1995-03-02 12:37:55 +0000 | [diff] [blame] | 96 | whatever the function call returned. The debugger prompt appears as |
| 97 | soon as the function is entered. |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 98 | \end{funcdesc} |
| 99 | |
| 100 | \begin{funcdesc}{set_trace}{} |
| 101 | Enter the debugger at the calling stack frame. This is useful to |
Guido van Rossum | f4aac48 | 1995-03-02 12:37:55 +0000 | [diff] [blame] | 102 | hard-code a breakpoint at a given point in a program, even if the code |
| 103 | is not otherwise being debugged (e.g. when an assertion fails). |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 104 | \end{funcdesc} |
| 105 | |
| 106 | \begin{funcdesc}{post_mortem}{traceback} |
| 107 | Enter post-mortem debugging of the given \var{traceback} object. |
| 108 | \end{funcdesc} |
| 109 | |
| 110 | \begin{funcdesc}{pm}{} |
Guido van Rossum | f4aac48 | 1995-03-02 12:37:55 +0000 | [diff] [blame] | 111 | Enter post-mortem debugging of the traceback found in |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 112 | \code{sys.last_traceback}. |
| 113 | \end{funcdesc} |
| 114 | |
Fred Drake | c8993aa | 1999-04-22 16:50:40 +0000 | [diff] [blame] | 115 | |
| 116 | \section{Debugger Commands \label{debugger-commands}} |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 117 | |
| 118 | The debugger recognizes the following commands. Most commands can be |
Fred Drake | c8993aa | 1999-04-22 16:50:40 +0000 | [diff] [blame] | 119 | abbreviated to one or two letters; e.g. \samp{h(elp)} means that |
| 120 | either \samp{h} or \samp{help} can be used to enter the help |
| 121 | command (but not \samp{he} or \samp{hel}, nor \samp{H} or |
| 122 | \samp{Help} or \samp{HELP}). Arguments to commands must be |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 123 | separated by whitespace (spaces or tabs). Optional arguments are |
Fred Drake | c8993aa | 1999-04-22 16:50:40 +0000 | [diff] [blame] | 124 | enclosed in square brackets (\samp{[]}) in the command syntax; the |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 125 | square brackets must not be typed. Alternatives in the command syntax |
Fred Drake | c8993aa | 1999-04-22 16:50:40 +0000 | [diff] [blame] | 126 | are separated by a vertical bar (\samp{|}). |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 127 | |
| 128 | Entering a blank line repeats the last command entered. Exception: if |
Fred Drake | c8993aa | 1999-04-22 16:50:40 +0000 | [diff] [blame] | 129 | the last command was a \samp{list} command, the next 11 lines are |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 130 | listed. |
| 131 | |
| 132 | Commands that the debugger doesn't recognize are assumed to be Python |
| 133 | statements and are executed in the context of the program being |
| 134 | debugged. Python statements can also be prefixed with an exclamation |
Fred Drake | c8993aa | 1999-04-22 16:50:40 +0000 | [diff] [blame] | 135 | point (\samp{!}). This is a powerful way to inspect the program |
Guido van Rossum | 25f6fcc | 1995-04-04 12:28:53 +0000 | [diff] [blame] | 136 | being debugged; it is even possible to change a variable or call a |
| 137 | function. When an |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 138 | exception occurs in such a statement, the exception name is printed |
| 139 | but the debugger's state is not changed. |
| 140 | |
Guido van Rossum | 6442116 | 1998-09-17 15:11:51 +0000 | [diff] [blame] | 141 | Multiple commands may be entered on a single line, separated by |
Fred Drake | c8993aa | 1999-04-22 16:50:40 +0000 | [diff] [blame] | 142 | \samp{;;}. (A single \samp{;} is not used as it is |
Guido van Rossum | 6442116 | 1998-09-17 15:11:51 +0000 | [diff] [blame] | 143 | the separator for multiple commands in a line that is passed to |
| 144 | the Python parser.) |
| 145 | No intelligence is applied to separating the commands; |
Fred Drake | c8993aa | 1999-04-22 16:50:40 +0000 | [diff] [blame] | 146 | the input is split at the first \samp{;;} pair, even if it is in |
Guido van Rossum | 6442116 | 1998-09-17 15:11:51 +0000 | [diff] [blame] | 147 | the middle of a quoted string. |
| 148 | |
| 149 | The debugger supports aliases. Aliases can have parameters which |
| 150 | allows one a certain level of adaptability to the context under |
| 151 | examination. |
| 152 | |
Fred Drake | c8993aa | 1999-04-22 16:50:40 +0000 | [diff] [blame] | 153 | If a file \file{.pdbrc} |
| 154 | \indexii{.pdbrc}{file}\indexiii{debugger}{configuration}{file} |
| 155 | exists in the user's home directory or in the current directory, it is |
| 156 | read in and executed as if it had been typed at the debugger prompt. |
| 157 | This is particularly useful for aliases. If both files exist, the one |
| 158 | in the home directory is read first and aliases defined there can be |
Thomas Wouters | f831663 | 2000-07-16 19:01:10 +0000 | [diff] [blame] | 159 | overridden by the local file. |
Guido van Rossum | 6442116 | 1998-09-17 15:11:51 +0000 | [diff] [blame] | 160 | |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 161 | \begin{description} |
| 162 | |
Fred Drake | 74947ac | 1998-01-12 15:38:30 +0000 | [diff] [blame] | 163 | \item[h(elp) \optional{\var{command}}] |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 164 | |
Fred Drake | 74947ac | 1998-01-12 15:38:30 +0000 | [diff] [blame] | 165 | Without argument, print the list of available commands. With a |
| 166 | \var{command} as argument, print help about that command. \samp{help |
| 167 | pdb} displays the full documentation file; if the environment variable |
Fred Drake | c8993aa | 1999-04-22 16:50:40 +0000 | [diff] [blame] | 168 | \envvar{PAGER} is defined, the file is piped through that command |
Fred Drake | 74947ac | 1998-01-12 15:38:30 +0000 | [diff] [blame] | 169 | instead. Since the \var{command} argument must be an identifier, |
| 170 | \samp{help exec} must be entered to get help on the \samp{!} command. |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 171 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 172 | \item[w(here)] |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 173 | |
Fred Drake | 74947ac | 1998-01-12 15:38:30 +0000 | [diff] [blame] | 174 | Print a stack trace, with the most recent frame at the bottom. An |
| 175 | arrow indicates the current frame, which determines the context of |
| 176 | most commands. |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 177 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 178 | \item[d(own)] |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 179 | |
| 180 | Move the current frame one level down in the stack trace |
Fred Drake | 898915d | 2000-04-05 15:01:36 +0000 | [diff] [blame] | 181 | (to an newer frame). |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 182 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 183 | \item[u(p)] |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 184 | |
| 185 | Move the current frame one level up in the stack trace |
Fred Drake | 898915d | 2000-04-05 15:01:36 +0000 | [diff] [blame] | 186 | (to a older frame). |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 187 | |
Fred Drake | 31ec33e | 1999-04-13 21:36:44 +0000 | [diff] [blame] | 188 | \item[b(reak) \optional{\optional{\var{filename}:}\var{lineno}\code{\Large{|}}\var{function}\optional{, \var{condition}}}] |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 189 | |
| 190 | With a \var{lineno} argument, set a break there in the current |
Guido van Rossum | 6442116 | 1998-09-17 15:11:51 +0000 | [diff] [blame] | 191 | file. With a \var{function} argument, set a break at the first |
| 192 | executable statement within that function. |
Guido van Rossum | 897b9f0 | 1998-07-20 23:29:10 +0000 | [diff] [blame] | 193 | The line number may be prefixed with a filename and a colon, |
| 194 | to specify a breakpoint in another file (probably one that |
| 195 | hasn't been loaded yet). The file is searched on \code{sys.path}. |
Guido van Rossum | 6442116 | 1998-09-17 15:11:51 +0000 | [diff] [blame] | 196 | Note that each breakpoint is assigned a number to which all the other |
| 197 | breakpoint commands refer. |
Guido van Rossum | 897b9f0 | 1998-07-20 23:29:10 +0000 | [diff] [blame] | 198 | |
Guido van Rossum | 6442116 | 1998-09-17 15:11:51 +0000 | [diff] [blame] | 199 | If a second argument is present, it is an expression which must |
| 200 | evaluate to true before the breakpoint is honored. |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 201 | |
Guido van Rossum | 6442116 | 1998-09-17 15:11:51 +0000 | [diff] [blame] | 202 | Without argument, list all breaks, including for each breakpoint, |
| 203 | the number of times that breakpoint has been hit, the current |
| 204 | ignore count, and the associated condition if any. |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 205 | |
Fred Drake | 31ec33e | 1999-04-13 21:36:44 +0000 | [diff] [blame] | 206 | \item[tbreak \optional{\optional{\var{filename}:}\var{lineno}\code{\Large{|}}\var{function}\optional{, \var{condition}}}] |
Guido van Rossum | 6442116 | 1998-09-17 15:11:51 +0000 | [diff] [blame] | 207 | |
| 208 | Temporary breakpoint, which is removed automatically when it is |
| 209 | first hit. The arguments are the same as break. |
| 210 | |
| 211 | \item[cl(ear) \optional{\var{bpnumber} \optional{\var{bpnumber ...}}}] |
| 212 | |
| 213 | With a space separated list of breakpoint numbers, clear those |
| 214 | breakpoints. Without argument, clear all breaks (but first |
| 215 | ask confirmation). |
| 216 | |
| 217 | \item[disable \optional{\var{bpnumber} \optional{\var{bpnumber ...}}}] |
| 218 | |
| 219 | Disables the breakpoints given as a space separated list of |
| 220 | breakpoint numbers. Disabling a breakpoint means it cannot cause |
| 221 | the program to stop execution, but unlike clearing a breakpoint, it |
| 222 | remains in the list of breakpoints and can be (re-)enabled. |
| 223 | |
| 224 | \item[enable \optional{\var{bpnumber} \optional{\var{bpnumber ...}}}] |
| 225 | |
| 226 | Enables the breakpoints specified. |
| 227 | |
| 228 | \item[ignore \var{bpnumber} \optional{\var{count}}] |
| 229 | |
| 230 | Sets the ignore count for the given breakpoint number. If |
| 231 | count is omitted, the ignore count is set to 0. A breakpoint |
| 232 | becomes active when the ignore count is zero. When non-zero, |
| 233 | the count is decremented each time the breakpoint is reached |
| 234 | and the breakpoint is not disabled and any associated condition |
| 235 | evaluates to true. |
| 236 | |
| 237 | \item[condition \var{bpnumber} \optional{\var{condition}}] |
| 238 | |
| 239 | Condition is an expression which must evaluate to true before |
| 240 | the breakpoint is honored. If condition is absent, any existing |
| 241 | condition is removed; i.e., the breakpoint is made unconditional. |
Guido van Rossum | 897b9f0 | 1998-07-20 23:29:10 +0000 | [diff] [blame] | 242 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 243 | \item[s(tep)] |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 244 | |
| 245 | Execute the current line, stop at the first possible occasion |
| 246 | (either in a function that is called or on the next line in the |
| 247 | current function). |
| 248 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 249 | \item[n(ext)] |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 250 | |
| 251 | Continue execution until the next line in the current function |
Fred Drake | c8993aa | 1999-04-22 16:50:40 +0000 | [diff] [blame] | 252 | is reached or it returns. (The difference between \samp{next} and |
| 253 | \samp{step} is that \samp{step} stops inside a called function, while |
| 254 | \samp{next} executes called functions at (nearly) full speed, only |
Guido van Rossum | f4aac48 | 1995-03-02 12:37:55 +0000 | [diff] [blame] | 255 | stopping at the next line in the current function.) |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 256 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 257 | \item[r(eturn)] |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 258 | |
| 259 | Continue execution until the current function returns. |
| 260 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 261 | \item[c(ont(inue))] |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 262 | |
| 263 | Continue execution, only stop when a breakpoint is encountered. |
| 264 | |
Michael W. Hudson | cfd3884 | 2002-12-17 16:15:34 +0000 | [diff] [blame] | 265 | \item[j(ump) \var{lineno}] |
| 266 | |
| 267 | Set the next line that will be executed. Only available in the |
| 268 | bottom-most frame. This lets you jump back and execute code |
| 269 | again, or jump forward to skip code that you don't want to run. |
| 270 | |
Fred Drake | e0f02f0 | 2002-12-18 02:07:14 +0000 | [diff] [blame] | 271 | It should be noted that not all jumps are allowed --- for instance it |
| 272 | is not possible to jump into the middle of a \keyword{for} loop or out |
| 273 | of a \keyword{finally} clause. |
Michael W. Hudson | cfd3884 | 2002-12-17 16:15:34 +0000 | [diff] [blame] | 274 | |
Fred Drake | 853276e | 2003-07-16 17:58:38 +0000 | [diff] [blame] | 275 | \item[l(ist) \optional{\var{first}\optional{, \var{last}}}] |
Guido van Rossum | 43b655c | 1998-09-17 17:07:15 +0000 | [diff] [blame] | 276 | |
Guido van Rossum | f4aac48 | 1995-03-02 12:37:55 +0000 | [diff] [blame] | 277 | List source code for the current file. Without arguments, list 11 |
| 278 | lines around the current line or continue the previous listing. With |
| 279 | one argument, list 11 lines around at that line. With two arguments, |
| 280 | list the given range; if the second argument is less than the first, |
| 281 | it is interpreted as a count. |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 282 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 283 | \item[a(rgs)] |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 284 | |
| 285 | Print the argument list of the current function. |
| 286 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 287 | \item[p \var{expression}] |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 288 | |
| 289 | Evaluate the \var{expression} in the current context and print its |
Fred Drake | e0f02f0 | 2002-12-18 02:07:14 +0000 | [diff] [blame] | 290 | value. \note{\samp{print} can also be used, but is not a debugger |
| 291 | command --- this executes the Python \keyword{print} statement.} |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 292 | |
Barry Warsaw | 75f36b7 | 2002-11-05 22:41:16 +0000 | [diff] [blame] | 293 | \item[pp \var{expression}] |
| 294 | |
Neal Norwitz | a5c6459 | 2004-10-17 19:55:47 +0000 | [diff] [blame] | 295 | Like the \samp{p} command, except the value of the expression is |
Barry Warsaw | 75f36b7 | 2002-11-05 22:41:16 +0000 | [diff] [blame] | 296 | pretty-printed using the \module{pprint} module. |
| 297 | |
Guido van Rossum | 6442116 | 1998-09-17 15:11:51 +0000 | [diff] [blame] | 298 | \item[alias \optional{\var{name} \optional{command}}] |
| 299 | |
| 300 | Creates an alias called \var{name} that executes \var{command}. The |
| 301 | command must \emph{not} be enclosed in quotes. Replaceable parameters |
| 302 | can be indicated by \samp{\%1}, \samp{\%2}, and so on, while \samp{\%*} is |
| 303 | replaced by all the parameters. If no command is given, the current |
| 304 | alias for \var{name} is shown. If no arguments are given, all |
| 305 | aliases are listed. |
| 306 | |
| 307 | Aliases may be nested and can contain anything that can be |
| 308 | legally typed at the pdb prompt. Note that internal pdb commands |
| 309 | \emph{can} be overridden by aliases. Such a command is |
| 310 | then hidden until the alias is removed. Aliasing is recursively |
| 311 | applied to the first word of the command line; all other words |
| 312 | in the line are left alone. |
| 313 | |
| 314 | As an example, here are two useful aliases (especially when placed |
| 315 | in the \file{.pdbrc} file): |
| 316 | |
| 317 | \begin{verbatim} |
| 318 | #Print instance variables (usage "pi classInst") |
| 319 | alias pi for k in %1.__dict__.keys(): print "%1.",k,"=",%1.__dict__[k] |
| 320 | #Print instance variables in self |
| 321 | alias ps pi self |
| 322 | \end{verbatim} |
Michael W. Hudson | cfd3884 | 2002-12-17 16:15:34 +0000 | [diff] [blame] | 323 | |
Guido van Rossum | 6442116 | 1998-09-17 15:11:51 +0000 | [diff] [blame] | 324 | \item[unalias \var{name}] |
| 325 | |
| 326 | Deletes the specified alias. |
| 327 | |
Fred Drake | 74947ac | 1998-01-12 15:38:30 +0000 | [diff] [blame] | 328 | \item[\optional{!}\var{statement}] |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 329 | |
| 330 | Execute the (one-line) \var{statement} in the context of |
| 331 | the current stack frame. |
| 332 | The exclamation point can be omitted unless the first word |
| 333 | of the statement resembles a debugger command. |
| 334 | To set a global variable, you can prefix the assignment |
Fred Drake | c8993aa | 1999-04-22 16:50:40 +0000 | [diff] [blame] | 335 | command with a \samp{global} command on the same line, e.g.: |
Fred Drake | 82d493f | 1998-04-07 19:14:17 +0000 | [diff] [blame] | 336 | |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 337 | \begin{verbatim} |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 338 | (Pdb) global list_options; list_options = ['-l'] |
| 339 | (Pdb) |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 340 | \end{verbatim} |
Fred Drake | 82d493f | 1998-04-07 19:14:17 +0000 | [diff] [blame] | 341 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 342 | \item[q(uit)] |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 343 | |
| 344 | Quit from the debugger. |
| 345 | The program being executed is aborted. |
| 346 | |
| 347 | \end{description} |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 348 | |
Fred Drake | 1a2302b | 2001-07-18 17:40:19 +0000 | [diff] [blame] | 349 | \section{How It Works \label{debugger-hooks}} |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 350 | |
| 351 | Some changes were made to the interpreter: |
| 352 | |
| 353 | \begin{itemize} |
Fred Drake | 74947ac | 1998-01-12 15:38:30 +0000 | [diff] [blame] | 354 | \item \code{sys.settrace(\var{func})} sets the global trace function |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 355 | \item there can also a local trace function (see later) |
| 356 | \end{itemize} |
| 357 | |
Fred Drake | 82d493f | 1998-04-07 19:14:17 +0000 | [diff] [blame] | 358 | Trace functions have three arguments: \var{frame}, \var{event}, and |
| 359 | \var{arg}. \var{frame} is the current stack frame. \var{event} is a |
Nicholas Bastin | c69ebe8 | 2004-03-24 21:57:10 +0000 | [diff] [blame] | 360 | string: \code{'call'}, \code{'line'}, \code{'return'}, \code{'exception'}, |
| 361 | \code{'c_call'}, \code{'c_return'}, or \code{'c_exception'}. \var{arg} |
| 362 | depends on the event type. |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 363 | |
Guido van Rossum | 9d37a4d | 1997-10-27 19:57:20 +0000 | [diff] [blame] | 364 | The global trace function is invoked (with \var{event} set to |
| 365 | \code{'call'}) whenever a new local scope is entered; it should return |
| 366 | a reference to the local trace function to be used that scope, or |
| 367 | \code{None} if the scope shouldn't be traced. |
| 368 | |
| 369 | The local trace function should return a reference to itself (or to |
| 370 | another function for further tracing in that scope), or \code{None} to |
| 371 | turn off tracing in that scope. |
| 372 | |
| 373 | Instance methods are accepted (and very useful!) as trace functions. |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 374 | |
| 375 | The events have the following meaning: |
| 376 | |
| 377 | \begin{description} |
| 378 | |
| 379 | \item[\code{'call'}] |
| 380 | A function is called (or some other code block entered). The global |
Fred Drake | b9a9628 | 2001-09-13 16:56:43 +0000 | [diff] [blame] | 381 | trace function is called; \var{arg} is \code{None}; |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 382 | the return value specifies the local trace function. |
| 383 | |
| 384 | \item[\code{'line'}] |
| 385 | The interpreter is about to execute a new line of code (sometimes |
| 386 | multiple line events on one line exist). The local trace function is |
Fred Drake | b9a9628 | 2001-09-13 16:56:43 +0000 | [diff] [blame] | 387 | called; \var{arg} is \code{None}; the return value specifies the new |
| 388 | local trace function. |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 389 | |
| 390 | \item[\code{'return'}] |
| 391 | A function (or other code block) is about to return. The local trace |
Fred Drake | b9a9628 | 2001-09-13 16:56:43 +0000 | [diff] [blame] | 392 | function is called; \var{arg} is the value that will be returned. The |
| 393 | trace function's return value is ignored. |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 394 | |
| 395 | \item[\code{'exception'}] |
Fred Drake | b9a9628 | 2001-09-13 16:56:43 +0000 | [diff] [blame] | 396 | An exception has occurred. The local trace function is called; |
| 397 | \var{arg} is a triple \code{(\var{exception}, \var{value}, |
| 398 | \var{traceback})}; the return value specifies the new local trace |
| 399 | function. |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 400 | |
Nicholas Bastin | c69ebe8 | 2004-03-24 21:57:10 +0000 | [diff] [blame] | 401 | \item[\code{'c_call'}] |
| 402 | A C function is about to be called. This may be an extension function |
Nicholas Bastin | 068979c | 2004-07-04 04:47:40 +0000 | [diff] [blame] | 403 | or a builtin. \var{arg} is the C function object. |
Nicholas Bastin | c69ebe8 | 2004-03-24 21:57:10 +0000 | [diff] [blame] | 404 | |
| 405 | \item[\code{'c_return'}] |
| 406 | A C function has returned. \var{arg} is \code{None}. |
| 407 | |
| 408 | \item[\code{'c_exception'}] |
| 409 | A C function has thrown an exception. \var{arg} is \code{None}. |
| 410 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 411 | \end{description} |
| 412 | |
| 413 | Note that as an exception is propagated down the chain of callers, an |
| 414 | \code{'exception'} event is generated at each level. |
| 415 | |
Fred Drake | bc8ad5b | 1998-03-11 06:29:59 +0000 | [diff] [blame] | 416 | For more information on code and frame objects, refer to the |
Fred Drake | 356d0ce | 1999-11-09 20:10:01 +0000 | [diff] [blame] | 417 | \citetitle[../ref/ref.html]{Python Reference Manual}. |