Guido van Rossum | f4aac48 | 1995-03-02 12:37:55 +0000 | [diff] [blame] | 1 | \chapter{The Python Debugger} |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 2 | \stmodindex{pdb} |
| 3 | \index{debugging} |
| 4 | |
Guido van Rossum | f4aac48 | 1995-03-02 12:37:55 +0000 | [diff] [blame] | 5 | \renewcommand{\indexsubitem}{(in module pdb)} |
| 6 | |
| 7 | The module \code{pdb} defines an interactive source code debugger for |
Guido van Rossum | 255d790 | 1997-07-11 13:51:17 +0000 | [diff] [blame] | 8 | Python programs. It supports setting |
| 9 | (conditional) breakpoints and single stepping |
Guido van Rossum | f4aac48 | 1995-03-02 12:37:55 +0000 | [diff] [blame] | 10 | at the source line level, inspection of stack frames, source code |
| 11 | listing, and evaluation of arbitrary Python code in the context of any |
| 12 | stack frame. It also supports post-mortem debugging and can be called |
| 13 | under program control. |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 14 | |
| 15 | The debugger is extensible --- it is actually defined as a class |
Guido van Rossum | 25f6fcc | 1995-04-04 12:28:53 +0000 | [diff] [blame] | 16 | \code{Pdb}. This is currently undocumented but easily understood by |
| 17 | reading the source. The extension interface uses the (also |
| 18 | undocumented) modules \code{bdb} and \code{cmd}. |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 19 | \ttindex{Pdb} |
| 20 | \ttindex{bdb} |
| 21 | \ttindex{cmd} |
| 22 | |
| 23 | A primitive windowing version of the debugger also exists --- this is |
Guido van Rossum | f4aac48 | 1995-03-02 12:37:55 +0000 | [diff] [blame] | 24 | module \code{wdb}, which requires STDWIN (see the chapter on STDWIN |
| 25 | specific modules). |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 26 | \index{stdwin} |
| 27 | \ttindex{wdb} |
| 28 | |
Guido van Rossum | 25f6fcc | 1995-04-04 12:28:53 +0000 | [diff] [blame] | 29 | The debugger's prompt is ``\code{(Pdb) }''. |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 30 | Typical usage to run a program under control of the debugger is: |
| 31 | |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 32 | \bcode\begin{verbatim} |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 33 | >>> import pdb |
| 34 | >>> import mymodule |
| 35 | >>> pdb.run('mymodule.test()') |
Guido van Rossum | 25f6fcc | 1995-04-04 12:28:53 +0000 | [diff] [blame] | 36 | > <string>(0)?() |
| 37 | (Pdb) continue |
| 38 | > <string>(1)?() |
| 39 | (Pdb) continue |
| 40 | NameError: 'spam' |
| 41 | > <string>(1)?() |
| 42 | (Pdb) |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 43 | \end{verbatim}\ecode |
| 44 | % |
Guido van Rossum | 809408e | 1997-06-02 17:28:16 +0000 | [diff] [blame] | 45 | \code{pdb.py} can also be invoked as |
| 46 | a script to debug other scripts. For example: |
| 47 | \code{python /usr/local/lib/python1.4/pdb.py myscript.py} |
| 48 | |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 49 | Typical usage to inspect a crashed program is: |
| 50 | |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 51 | \bcode\begin{verbatim} |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 52 | >>> import pdb |
| 53 | >>> import mymodule |
| 54 | >>> mymodule.test() |
Guido van Rossum | 25f6fcc | 1995-04-04 12:28:53 +0000 | [diff] [blame] | 55 | Traceback (innermost last): |
| 56 | File "<stdin>", line 1, in ? |
| 57 | File "./mymodule.py", line 4, in test |
| 58 | test2() |
| 59 | File "./mymodule.py", line 3, in test2 |
| 60 | print spam |
| 61 | NameError: spam |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 62 | >>> pdb.pm() |
Guido van Rossum | 25f6fcc | 1995-04-04 12:28:53 +0000 | [diff] [blame] | 63 | > ./mymodule.py(3)test2() |
| 64 | -> print spam |
| 65 | (Pdb) |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 66 | \end{verbatim}\ecode |
| 67 | % |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 68 | The module defines the following functions; each enters the debugger |
| 69 | in a slightly different way: |
| 70 | |
| 71 | \begin{funcdesc}{run}{statement\optional{\, globals\optional{\, locals}}} |
Guido van Rossum | f4aac48 | 1995-03-02 12:37:55 +0000 | [diff] [blame] | 72 | Execute the \var{statement} (given as a string) under debugger |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 73 | control. The debugger prompt appears before any code is executed; you |
Guido van Rossum | f4aac48 | 1995-03-02 12:37:55 +0000 | [diff] [blame] | 74 | can set breakpoints and type \code{continue}, or you can step through |
| 75 | the statement using \code{step} or \code{next} (all these commands are |
| 76 | explained below). The optional \var{globals} and \var{locals} |
| 77 | arguments specify the environment in which the code is executed; by |
| 78 | default the dictionary of the module \code{__main__} is used. (See |
| 79 | the explanation of the \code{exec} statement or the \code{eval()} |
| 80 | built-in function.) |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 81 | \end{funcdesc} |
| 82 | |
| 83 | \begin{funcdesc}{runeval}{expression\optional{\, globals\optional{\, locals}}} |
Guido van Rossum | f4aac48 | 1995-03-02 12:37:55 +0000 | [diff] [blame] | 84 | Evaluate the \var{expression} (given as a a string) under debugger |
| 85 | control. When \code{runeval()} returns, it returns the value of the |
| 86 | expression. Otherwise this function is similar to |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 87 | \code{run()}. |
| 88 | \end{funcdesc} |
| 89 | |
| 90 | \begin{funcdesc}{runcall}{function\optional{\, argument\, ...}} |
Guido van Rossum | f4aac48 | 1995-03-02 12:37:55 +0000 | [diff] [blame] | 91 | Call the \var{function} (a function or method object, not a string) |
| 92 | with the given arguments. When \code{runcall()} returns, it returns |
| 93 | whatever the function call returned. The debugger prompt appears as |
| 94 | soon as the function is entered. |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 95 | \end{funcdesc} |
| 96 | |
| 97 | \begin{funcdesc}{set_trace}{} |
| 98 | 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] | 99 | hard-code a breakpoint at a given point in a program, even if the code |
| 100 | is not otherwise being debugged (e.g. when an assertion fails). |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 101 | \end{funcdesc} |
| 102 | |
| 103 | \begin{funcdesc}{post_mortem}{traceback} |
| 104 | Enter post-mortem debugging of the given \var{traceback} object. |
| 105 | \end{funcdesc} |
| 106 | |
| 107 | \begin{funcdesc}{pm}{} |
Guido van Rossum | f4aac48 | 1995-03-02 12:37:55 +0000 | [diff] [blame] | 108 | Enter post-mortem debugging of the traceback found in |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 109 | \code{sys.last_traceback}. |
| 110 | \end{funcdesc} |
| 111 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 112 | \section{Debugger Commands} |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 113 | |
| 114 | The debugger recognizes the following commands. Most commands can be |
| 115 | abbreviated to one or two letters; e.g. ``\code{h(elp)}'' means that |
| 116 | either ``\code{h}'' or ``\code{help}'' can be used to enter the help |
| 117 | command (but not ``\code{he}'' or ``\code{hel}'', nor ``\code{H}'' or |
| 118 | ``\code{Help} or ``\code{HELP}''). Arguments to commands must be |
| 119 | separated by whitespace (spaces or tabs). Optional arguments are |
Guido van Rossum | 6c4f003 | 1995-03-07 10:14:09 +0000 | [diff] [blame] | 120 | enclosed in square brackets (``\code{[]}'') in the command syntax; the |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 121 | square brackets must not be typed. Alternatives in the command syntax |
| 122 | are separated by a vertical bar (``\code{|}''). |
| 123 | |
| 124 | Entering a blank line repeats the last command entered. Exception: if |
| 125 | the last command was a ``\code{list}'' command, the next 11 lines are |
| 126 | listed. |
| 127 | |
| 128 | Commands that the debugger doesn't recognize are assumed to be Python |
| 129 | statements and are executed in the context of the program being |
| 130 | debugged. Python statements can also be prefixed with an exclamation |
| 131 | point (``\code{!}''). This is a powerful way to inspect the program |
Guido van Rossum | 25f6fcc | 1995-04-04 12:28:53 +0000 | [diff] [blame] | 132 | being debugged; it is even possible to change a variable or call a |
| 133 | function. When an |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 134 | exception occurs in such a statement, the exception name is printed |
| 135 | but the debugger's state is not changed. |
| 136 | |
| 137 | \begin{description} |
| 138 | |
Fred Drake | 74947ac | 1998-01-12 15:38:30 +0000 | [diff] [blame] | 139 | \item[h(elp) \optional{\var{command}}] |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 140 | |
Fred Drake | 74947ac | 1998-01-12 15:38:30 +0000 | [diff] [blame] | 141 | Without argument, print the list of available commands. With a |
| 142 | \var{command} as argument, print help about that command. \samp{help |
| 143 | pdb} displays the full documentation file; if the environment variable |
| 144 | \code{PAGER} is defined, the file is piped through that command |
| 145 | instead. Since the \var{command} argument must be an identifier, |
| 146 | \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] | 147 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 148 | \item[w(here)] |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 149 | |
Fred Drake | 74947ac | 1998-01-12 15:38:30 +0000 | [diff] [blame] | 150 | Print a stack trace, with the most recent frame at the bottom. An |
| 151 | arrow indicates the current frame, which determines the context of |
| 152 | most commands. |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 153 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 154 | \item[d(own)] |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 155 | |
| 156 | Move the current frame one level down in the stack trace |
| 157 | (to an older frame). |
| 158 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 159 | \item[u(p)] |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 160 | |
| 161 | Move the current frame one level up in the stack trace |
| 162 | (to a newer frame). |
| 163 | |
Fred Drake | 74947ac | 1998-01-12 15:38:30 +0000 | [diff] [blame] | 164 | \item[b(reak) \optional{\var{lineno}{\Large\code{|}}\var{function}% |
| 165 | \optional{, \code{'}\var{condition}\code{'}}}] |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 166 | |
| 167 | With a \var{lineno} argument, set a break there in the current |
| 168 | file. With a \var{function} argument, set a break at the entry of |
| 169 | that function. Without argument, list all breaks. |
Guido van Rossum | 31cbc84 | 1997-07-11 13:57:28 +0000 | [diff] [blame] | 170 | If a second argument is present, it is a string (included in string |
| 171 | quotes!) specifying an expression which must evaluate to true before |
| 172 | the breakpoint is honored. |
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 | \item[cl(ear) \optional{\var{lineno}}] |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 175 | |
| 176 | With a \var{lineno} argument, clear that break in the current file. |
| 177 | Without argument, clear all breaks (but first ask confirmation). |
| 178 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 179 | \item[s(tep)] |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 180 | |
| 181 | Execute the current line, stop at the first possible occasion |
| 182 | (either in a function that is called or on the next line in the |
| 183 | current function). |
| 184 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 185 | \item[n(ext)] |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 186 | |
| 187 | Continue execution until the next line in the current function |
| 188 | is reached or it returns. (The difference between \code{next} and |
| 189 | \code{step} is that \code{step} stops inside a called function, while |
Guido van Rossum | f4aac48 | 1995-03-02 12:37:55 +0000 | [diff] [blame] | 190 | \code{next} executes called functions at (nearly) full speed, only |
| 191 | stopping at the next line in the current function.) |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 192 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 193 | \item[r(eturn)] |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 194 | |
| 195 | Continue execution until the current function returns. |
| 196 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 197 | \item[c(ont(inue))] |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 198 | |
| 199 | Continue execution, only stop when a breakpoint is encountered. |
| 200 | |
Fred Drake | 74947ac | 1998-01-12 15:38:30 +0000 | [diff] [blame] | 201 | \item[l(ist) \optional{\var{first\optional{, last}}}] |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 202 | |
Guido van Rossum | f4aac48 | 1995-03-02 12:37:55 +0000 | [diff] [blame] | 203 | List source code for the current file. Without arguments, list 11 |
| 204 | lines around the current line or continue the previous listing. With |
| 205 | one argument, list 11 lines around at that line. With two arguments, |
| 206 | list the given range; if the second argument is less than the first, |
| 207 | it is interpreted as a count. |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 208 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 209 | \item[a(rgs)] |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 210 | |
| 211 | Print the argument list of the current function. |
| 212 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 213 | \item[p \var{expression}] |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 214 | |
| 215 | Evaluate the \var{expression} in the current context and print its |
Guido van Rossum | f4aac48 | 1995-03-02 12:37:55 +0000 | [diff] [blame] | 216 | value. (Note: \code{print} can also be used, but is not a debugger |
| 217 | command --- this executes the Python \code{print} statement.) |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 218 | |
Fred Drake | 74947ac | 1998-01-12 15:38:30 +0000 | [diff] [blame] | 219 | \item[\optional{!}\var{statement}] |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 220 | |
| 221 | Execute the (one-line) \var{statement} in the context of |
| 222 | the current stack frame. |
| 223 | The exclamation point can be omitted unless the first word |
| 224 | of the statement resembles a debugger command. |
| 225 | To set a global variable, you can prefix the assignment |
| 226 | command with a ``\code{global}'' command on the same line, e.g.: |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 227 | \bcode\begin{verbatim} |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 228 | (Pdb) global list_options; list_options = ['-l'] |
| 229 | (Pdb) |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 230 | \end{verbatim}\ecode |
| 231 | % |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 232 | \item[q(uit)] |
Guido van Rossum | dc46c7f | 1995-03-01 15:38:16 +0000 | [diff] [blame] | 233 | |
| 234 | Quit from the debugger. |
| 235 | The program being executed is aborted. |
| 236 | |
| 237 | \end{description} |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 238 | |
| 239 | \section{How It Works} |
| 240 | |
| 241 | Some changes were made to the interpreter: |
| 242 | |
| 243 | \begin{itemize} |
Fred Drake | 74947ac | 1998-01-12 15:38:30 +0000 | [diff] [blame] | 244 | \item \code{sys.settrace(\var{func})} sets the global trace function |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 245 | \item there can also a local trace function (see later) |
| 246 | \end{itemize} |
| 247 | |
| 248 | Trace functions have three arguments: (\var{frame}, \var{event}, \var{arg}) |
| 249 | |
| 250 | \begin{description} |
| 251 | |
| 252 | \item[\var{frame}] is the current stack frame |
| 253 | |
| 254 | \item[\var{event}] is a string: \code{'call'}, \code{'line'}, \code{'return'} |
| 255 | or \code{'exception'} |
| 256 | |
| 257 | \item[\var{arg}] is dependent on the event type |
| 258 | |
| 259 | \end{description} |
| 260 | |
Guido van Rossum | 9d37a4d | 1997-10-27 19:57:20 +0000 | [diff] [blame] | 261 | The global trace function is invoked (with \var{event} set to |
| 262 | \code{'call'}) whenever a new local scope is entered; it should return |
| 263 | a reference to the local trace function to be used that scope, or |
| 264 | \code{None} if the scope shouldn't be traced. |
| 265 | |
| 266 | The local trace function should return a reference to itself (or to |
| 267 | another function for further tracing in that scope), or \code{None} to |
| 268 | turn off tracing in that scope. |
| 269 | |
| 270 | Instance methods are accepted (and very useful!) as trace functions. |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 271 | |
| 272 | The events have the following meaning: |
| 273 | |
| 274 | \begin{description} |
| 275 | |
| 276 | \item[\code{'call'}] |
| 277 | A function is called (or some other code block entered). The global |
| 278 | trace function is called; arg is the argument list to the function; |
| 279 | the return value specifies the local trace function. |
| 280 | |
| 281 | \item[\code{'line'}] |
| 282 | The interpreter is about to execute a new line of code (sometimes |
| 283 | multiple line events on one line exist). The local trace function is |
| 284 | called; arg in None; the return value specifies the new local trace |
| 285 | function. |
| 286 | |
| 287 | \item[\code{'return'}] |
| 288 | A function (or other code block) is about to return. The local trace |
| 289 | function is called; arg is the value that will be returned. The trace |
| 290 | function's return value is ignored. |
| 291 | |
| 292 | \item[\code{'exception'}] |
| 293 | An exception has occurred. The local trace function is called; arg is |
| 294 | a triple (exception, value, traceback); the return value specifies the |
| 295 | new local trace function |
| 296 | |
| 297 | \end{description} |
| 298 | |
| 299 | Note that as an exception is propagated down the chain of callers, an |
| 300 | \code{'exception'} event is generated at each level. |
| 301 | |
| 302 | Stack frame objects have the following read-only attributes: |
| 303 | |
| 304 | \begin{description} |
| 305 | \item[f_code] the code object being executed |
| 306 | \item[f_lineno] the current line number (\code{-1} for \code{'call'} events) |
| 307 | \item[f_back] the stack frame of the caller, or None |
| 308 | \item[f_locals] dictionary containing local name bindings |
| 309 | \item[f_globals] dictionary containing global name bindings |
| 310 | \end{description} |
| 311 | |
| 312 | Code objects have the following read-only attributes: |
| 313 | |
| 314 | \begin{description} |
| 315 | \item[co_code] the code string |
| 316 | \item[co_names] the list of names used by the code |
| 317 | \item[co_consts] the list of (literal) constants used by the code |
| 318 | \item[co_filename] the filename from which the code was compiled |
| 319 | \end{description} |