Doc/libpdb.tex

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