Doc/lib/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}.  The extension interface uses the (also undocumented)
  16 modules \code{bdb} and \code{cmd}; it is currently undocumented but
  17 easily understood by reading the source.
  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 Typical usage to run a program under control of the debugger is:
  29
  30 \begin{verbatim}
  31 >>> import pdb
  32 >>> import mymodule
  33 >>> pdb.run('mymodule.test()')
  34 (Pdb)
  35 \end{verbatim}
  36
  37 Typical usage to inspect a crashed program is:
  38
  39 \begin{verbatim}
  40 >>> import pdb
  41 >>> import mymodule
  42 >>> mymodule.test()
  43 (crashes with a stack trace)
  44 >>> pdb.pm()
  45 (Pdb)
  46 \end{verbatim}
  47
  48 The debugger's prompt is ``\code{(Pdb) }''.
  49
  50 The module defines the following functions; each enters the debugger
  51 in a slightly different way:
  52
  53 \begin{funcdesc}{run}{statement\optional{\, globals\optional{\, locals}}}
  54 Execute the \var{statement} (given as a string) under debugger
  55 control.  The debugger prompt appears before any code is executed; you
  56 can set breakpoints and type \code{continue}, or you can step through
  57 the statement using \code{step} or \code{next} (all these commands are
  58 explained below).  The optional \var{globals} and \var{locals}
  59 arguments specify the environment in which the code is executed; by
  60 default the dictionary of the module \code{__main__} is used.  (See
  61 the explanation of the \code{exec} statement or the \code{eval()}
  62 built-in function.)
  63 \end{funcdesc}
  64
  65 \begin{funcdesc}{runeval}{expression\optional{\, globals\optional{\, locals}}}
  66 Evaluate the \var{expression} (given as a a string) under debugger
  67 control.  When \code{runeval()} returns, it returns the value of the
  68 expression.  Otherwise this function is similar to
  69 \code{run()}.
  70 \end{funcdesc}
  71
  72 \begin{funcdesc}{runcall}{function\optional{\, argument\, ...}}
  73 Call the \var{function} (a function or method object, not a string)
  74 with the given arguments.  When \code{runcall()} returns, it returns
  75 whatever the function call returned.  The debugger prompt appears as
  76 soon as the function is entered.
  77 \end{funcdesc}
  78
  79 \begin{funcdesc}{set_trace}{}
  80 Enter the debugger at the calling stack frame.  This is useful to
  81 hard-code a breakpoint at a given point in a program, even if the code
  82 is not otherwise being debugged (e.g. when an assertion fails).
  83 \end{funcdesc}
  84
  85 \begin{funcdesc}{post_mortem}{traceback}
  86 Enter post-mortem debugging of the given \var{traceback} object.
  87 \end{funcdesc}
  88
  89 \begin{funcdesc}{pm}{}
  90 Enter post-mortem debugging of the traceback found in
  91 \code{sys.last_traceback}.
  92 \end{funcdesc}
  93
  94 \subsection{Debugger Commands}
  95
  96 The debugger recognizes the following commands.  Most commands can be
  97 abbreviated to one or two letters; e.g. ``\code{h(elp)}'' means that
  98 either ``\code{h}'' or ``\code{help}'' can be used to enter the help
  99 command (but not ``\code{he}'' or ``\code{hel}'', nor ``\code{H}'' or
 100 ``\code{Help} or ``\code{HELP}'').  Arguments to commands must be
 101 separated by whitespace (spaces or tabs).  Optional arguments are
 102 enclosed in square brackets (``\code{[]}'') in the command syntax; the
 103 square brackets must not be typed.  Alternatives in the command syntax
 104 are separated by a vertical bar (``\code{|}'').
 105
 106 Entering a blank line repeats the last command entered.  Exception: if
 107 the last command was a ``\code{list}'' command, the next 11 lines are
 108 listed.
 109
 110 Commands that the debugger doesn't recognize are assumed to be Python
 111 statements and are executed in the context of the program being
 112 debugged.  Python statements can also be prefixed with an exclamation
 113 point (``\code{!}'').  This is a powerful way to inspect the program
 114 being debugged; it is even possible to change variables.  When an
 115 exception occurs in such a statement, the exception name is printed
 116 but the debugger's state is not changed.
 117
 118 \begin{description}
 119
 120 \item[{h(elp) [\var{command}]}]
 121
 122 Without argument, print the list of available commands.
 123 With a \var{command} as argument, print help about that command.
 124 ``\code{help pdb}'' displays the full documentation file; if the
 125 environment variable \code{PAGER} is defined, the file is piped
 126 through that command instead.  Since the \var{command} argument must be
 127 an identifier, ``\code{help exec}'' must be entered to get help on the
 128 ``\code{!}'' command.
 129
 130 \item[{w(here)}]
 131
 132 Print a stack trace, with the most recent frame at the bottom.
 133 An arrow indicates the current frame, which determines the
 134 context of most commands.
 135
 136 \item[{d(own)}]
 137
 138 Move the current frame one level down in the stack trace
 139 (to an older frame).
 140
 141 \item[{u(p)}]
 142
 143 Move the current frame one level up in the stack trace
 144 (to a newer frame).
 145
 146 \item[{b(reak) [\var{lineno}\code{|}\var{function}]}]
 147
 148 With a \var{lineno} argument, set a break there in the current
 149 file.  With a \var{function} argument, set a break at the entry of
 150 that function.  Without argument, list all breaks.
 151
 152 \item[{cl(ear) [\var{lineno}]}]
 153
 154 With a \var{lineno} argument, clear that break in the current file.
 155 Without argument, clear all breaks (but first ask confirmation).
 156
 157 \item[{s(tep)}]
 158
 159 Execute the current line, stop at the first possible occasion
 160 (either in a function that is called or on the next line in the
 161 current function).
 162
 163 \item[{n(ext)}]
 164
 165 Continue execution until the next line in the current function
 166 is reached or it returns.  (The difference between \code{next} and
 167 \code{step} is that \code{step} stops inside a called function, while
 168 \code{next} executes called functions at (nearly) full speed, only
 169 stopping at the next line in the current function.)
 170
 171 \item[{r(eturn)}]
 172
 173 Continue execution until the current function returns.
 174
 175 \item[{c(ont(inue))}]
 176
 177 Continue execution, only stop when a breakpoint is encountered.
 178
 179 \item[{l(ist) [\var{first} [, \var{last}]]}]
 180
 181 List source code for the current file.  Without arguments, list 11
 182 lines around the current line or continue the previous listing.  With
 183 one argument, list 11 lines around at that line.  With two arguments,
 184 list the given range; if the second argument is less than the first,
 185 it is interpreted as a count.
 186
 187 \item[{a(rgs)}]
 188
 189 Print the argument list of the current function.
 190
 191 \item[{p \var{expression}}]
 192
 193 Evaluate the \var{expression} in the current context and print its
 194 value.  (Note: \code{print} can also be used, but is not a debugger
 195 command --- this executes the Python \code{print} statement.)
 196
 197 \item[{[!] \var{statement}}]
 198
 199 Execute the (one-line) \var{statement} in the context of
 200 the current stack frame.
 201 The exclamation point can be omitted unless the first word
 202 of the statement resembles a debugger command.
 203 To set a global variable, you can prefix the assignment
 204 command with a ``\code{global}'' command on the same line, e.g.:
 205 \begin{verbatim}
 206 (Pdb) global list_options; list_options = ['-l']
 207 (Pdb)
 208 \end{verbatim}
 209
 210 \item[{q(uit)}]
 211
 212 Quit from the debugger.
 213 The program being executed is aborted.
 214
 215 \end{description}