Doc/lib/libpdb.tex

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