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