| \chapter{The Python Debugger \label{debugger}} |
| |
| \declaremodule{standard}{pdb} |
| \modulesynopsis{The Python debugger for interactive interpreters.} |
| |
| |
| The module \module{pdb} defines an interactive source code |
| debugger\index{debugging} for Python programs. It supports setting |
| (conditional) breakpoints and single stepping at the source line |
| level, inspection of stack frames, source code listing, and evaluation |
| of arbitrary Python code in the context of any stack frame. It also |
| supports post-mortem debugging and can be called under program |
| control. |
| |
| The debugger is extensible --- it is actually defined as the class |
| \class{Pdb}\withsubitem{(class in pdb)}{\ttindex{Pdb}}. |
| This is currently undocumented but easily understood by reading the |
| source. The extension interface uses the modules |
| \module{bdb}\refstmodindex{bdb} (undocumented) and |
| \refmodule{cmd}\refstmodindex{cmd}. |
| |
| The debugger's prompt is \samp{(Pdb) }. |
| Typical usage to run a program under control of the debugger is: |
| |
| \begin{verbatim} |
| >>> import pdb |
| >>> import mymodule |
| >>> pdb.run('mymodule.test()') |
| > <string>(0)?() |
| (Pdb) continue |
| > <string>(1)?() |
| (Pdb) continue |
| NameError: 'spam' |
| > <string>(1)?() |
| (Pdb) |
| \end{verbatim} |
| |
| \file{pdb.py} can also be invoked as |
| a script to debug other scripts. For example: |
| |
| \begin{verbatim} |
| python -m pdb myscript.py |
| \end{verbatim} |
| |
| Typical usage to inspect a crashed program is: |
| |
| \begin{verbatim} |
| >>> import pdb |
| >>> import mymodule |
| >>> mymodule.test() |
| Traceback (most recent call last): |
| File "<stdin>", line 1, in ? |
| File "./mymodule.py", line 4, in test |
| test2() |
| File "./mymodule.py", line 3, in test2 |
| print spam |
| NameError: spam |
| >>> pdb.pm() |
| > ./mymodule.py(3)test2() |
| -> print spam |
| (Pdb) |
| \end{verbatim} |
| |
| The module defines the following functions; each enters the debugger |
| in a slightly different way: |
| |
| \begin{funcdesc}{run}{statement\optional{, globals\optional{, locals}}} |
| Execute the \var{statement} (given as a string) under debugger |
| control. The debugger prompt appears before any code is executed; you |
| can set breakpoints and type \samp{continue}, or you can step through |
| the statement using \samp{step} or \samp{next} (all these commands are |
| explained below). The optional \var{globals} and \var{locals} |
| arguments specify the environment in which the code is executed; by |
| default the dictionary of the module \refmodule[main]{__main__} is |
| used. (See the explanation of the \keyword{exec} statement or the |
| \function{eval()} built-in function.) |
| \end{funcdesc} |
| |
| \begin{funcdesc}{runeval}{expression\optional{, globals\optional{, locals}}} |
| Evaluate the \var{expression} (given as a string) under debugger |
| control. When \function{runeval()} returns, it returns the value of the |
| expression. Otherwise this function is similar to |
| \function{run()}. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{runcall}{function\optional{, argument, ...}} |
| Call the \var{function} (a function or method object, not a string) |
| with the given arguments. When \function{runcall()} returns, it returns |
| whatever the function call returned. The debugger prompt appears as |
| soon as the function is entered. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{set_trace}{} |
| Enter the debugger at the calling stack frame. This is useful to |
| hard-code a breakpoint at a given point in a program, even if the code |
| is not otherwise being debugged (e.g. when an assertion fails). |
| \end{funcdesc} |
| |
| \begin{funcdesc}{post_mortem}{traceback} |
| Enter post-mortem debugging of the given \var{traceback} object. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{pm}{} |
| Enter post-mortem debugging of the traceback found in |
| \code{sys.last_traceback}. |
| \end{funcdesc} |
| |
| |
| \section{Debugger Commands \label{debugger-commands}} |
| |
| The debugger recognizes the following commands. Most commands can be |
| abbreviated to one or two letters; e.g. \samp{h(elp)} means that |
| either \samp{h} or \samp{help} can be used to enter the help |
| command (but not \samp{he} or \samp{hel}, nor \samp{H} or |
| \samp{Help} or \samp{HELP}). Arguments to commands must be |
| separated by whitespace (spaces or tabs). Optional arguments are |
| enclosed in square brackets (\samp{[]}) in the command syntax; the |
| square brackets must not be typed. Alternatives in the command syntax |
| are separated by a vertical bar (\samp{|}). |
| |
| Entering a blank line repeats the last command entered. Exception: if |
| the last command was a \samp{list} command, the next 11 lines are |
| listed. |
| |
| Commands that the debugger doesn't recognize are assumed to be Python |
| statements and are executed in the context of the program being |
| debugged. Python statements can also be prefixed with an exclamation |
| point (\samp{!}). This is a powerful way to inspect the program |
| being debugged; it is even possible to change a variable or call a |
| function. When an |
| exception occurs in such a statement, the exception name is printed |
| but the debugger's state is not changed. |
| |
| Multiple commands may be entered on a single line, separated by |
| \samp{;;}. (A single \samp{;} is not used as it is |
| the separator for multiple commands in a line that is passed to |
| the Python parser.) |
| No intelligence is applied to separating the commands; |
| the input is split at the first \samp{;;} pair, even if it is in |
| the middle of a quoted string. |
| |
| The debugger supports aliases. Aliases can have parameters which |
| allows one a certain level of adaptability to the context under |
| examination. |
| |
| If a file \file{.pdbrc} |
| \indexii{.pdbrc}{file}\indexiii{debugger}{configuration}{file} |
| exists in the user's home directory or in the current directory, it is |
| read in and executed as if it had been typed at the debugger prompt. |
| This is particularly useful for aliases. If both files exist, the one |
| in the home directory is read first and aliases defined there can be |
| overridden by the local file. |
| |
| \begin{description} |
| |
| \item[h(elp) \optional{\var{command}}] |
| |
| Without argument, print the list of available commands. With a |
| \var{command} as argument, print help about that command. \samp{help |
| pdb} displays the full documentation file; if the environment variable |
| \envvar{PAGER} is defined, the file is piped through that command |
| instead. Since the \var{command} argument must be an identifier, |
| \samp{help exec} must be entered to get help on the \samp{!} command. |
| |
| \item[w(here)] |
| |
| Print a stack trace, with the most recent frame at the bottom. An |
| arrow indicates the current frame, which determines the context of |
| most commands. |
| |
| \item[d(own)] |
| |
| Move the current frame one level down in the stack trace |
| (to an newer frame). |
| |
| \item[u(p)] |
| |
| Move the current frame one level up in the stack trace |
| (to a older frame). |
| |
| \item[b(reak) \optional{\optional{\var{filename}:}\var{lineno}\code{\Large{|}}\var{function}\optional{, \var{condition}}}] |
| |
| With a \var{lineno} argument, set a break there in the current |
| file. With a \var{function} argument, set a break at the first |
| executable statement within that function. |
| The line number may be prefixed with a filename and a colon, |
| to specify a breakpoint in another file (probably one that |
| hasn't been loaded yet). The file is searched on \code{sys.path}. |
| Note that each breakpoint is assigned a number to which all the other |
| breakpoint commands refer. |
| |
| If a second argument is present, it is an expression which must |
| evaluate to true before the breakpoint is honored. |
| |
| Without argument, list all breaks, including for each breakpoint, |
| the number of times that breakpoint has been hit, the current |
| ignore count, and the associated condition if any. |
| |
| \item[tbreak \optional{\optional{\var{filename}:}\var{lineno}\code{\Large{|}}\var{function}\optional{, \var{condition}}}] |
| |
| Temporary breakpoint, which is removed automatically when it is |
| first hit. The arguments are the same as break. |
| |
| \item[cl(ear) \optional{\var{bpnumber} \optional{\var{bpnumber ...}}}] |
| |
| With a space separated list of breakpoint numbers, clear those |
| breakpoints. Without argument, clear all breaks (but first |
| ask confirmation). |
| |
| \item[disable \optional{\var{bpnumber} \optional{\var{bpnumber ...}}}] |
| |
| Disables the breakpoints given as a space separated list of |
| breakpoint numbers. Disabling a breakpoint means it cannot cause |
| the program to stop execution, but unlike clearing a breakpoint, it |
| remains in the list of breakpoints and can be (re-)enabled. |
| |
| \item[enable \optional{\var{bpnumber} \optional{\var{bpnumber ...}}}] |
| |
| Enables the breakpoints specified. |
| |
| \item[ignore \var{bpnumber} \optional{\var{count}}] |
| |
| Sets the ignore count for the given breakpoint number. If |
| count is omitted, the ignore count is set to 0. A breakpoint |
| becomes active when the ignore count is zero. When non-zero, |
| the count is decremented each time the breakpoint is reached |
| and the breakpoint is not disabled and any associated condition |
| evaluates to true. |
| |
| \item[condition \var{bpnumber} \optional{\var{condition}}] |
| |
| Condition is an expression which must evaluate to true before |
| the breakpoint is honored. If condition is absent, any existing |
| condition is removed; i.e., the breakpoint is made unconditional. |
| |
| \item[s(tep)] |
| |
| Execute the current line, stop at the first possible occasion |
| (either in a function that is called or on the next line in the |
| current function). |
| |
| \item[n(ext)] |
| |
| Continue execution until the next line in the current function |
| is reached or it returns. (The difference between \samp{next} and |
| \samp{step} is that \samp{step} stops inside a called function, while |
| \samp{next} executes called functions at (nearly) full speed, only |
| stopping at the next line in the current function.) |
| |
| \item[r(eturn)] |
| |
| Continue execution until the current function returns. |
| |
| \item[c(ont(inue))] |
| |
| Continue execution, only stop when a breakpoint is encountered. |
| |
| \item[j(ump) \var{lineno}] |
| |
| Set the next line that will be executed. Only available in the |
| bottom-most frame. This lets you jump back and execute code |
| again, or jump forward to skip code that you don't want to run. |
| |
| It should be noted that not all jumps are allowed --- for instance it |
| is not possible to jump into the middle of a \keyword{for} loop or out |
| of a \keyword{finally} clause. |
| |
| \item[l(ist) \optional{\var{first}\optional{, \var{last}}}] |
| |
| List source code for the current file. Without arguments, list 11 |
| lines around the current line or continue the previous listing. With |
| one argument, list 11 lines around at that line. With two arguments, |
| list the given range; if the second argument is less than the first, |
| it is interpreted as a count. |
| |
| \item[a(rgs)] |
| |
| Print the argument list of the current function. |
| |
| \item[p \var{expression}] |
| |
| Evaluate the \var{expression} in the current context and print its |
| value. \note{\samp{print} can also be used, but is not a debugger |
| command --- this executes the Python \keyword{print} statement.} |
| |
| \item[pp \var{expression}] |
| |
| Like the \samp{p} command, except the value of the expression is |
| pretty-printed using the \module{pprint} module. |
| |
| \item[alias \optional{\var{name} \optional{command}}] |
| |
| Creates an alias called \var{name} that executes \var{command}. The |
| command must \emph{not} be enclosed in quotes. Replaceable parameters |
| can be indicated by \samp{\%1}, \samp{\%2}, and so on, while \samp{\%*} is |
| replaced by all the parameters. If no command is given, the current |
| alias for \var{name} is shown. If no arguments are given, all |
| aliases are listed. |
| |
| Aliases may be nested and can contain anything that can be |
| legally typed at the pdb prompt. Note that internal pdb commands |
| \emph{can} be overridden by aliases. Such a command is |
| then hidden until the alias is removed. Aliasing is recursively |
| applied to the first word of the command line; all other words |
| in the line are left alone. |
| |
| As an example, here are two useful aliases (especially when placed |
| in the \file{.pdbrc} file): |
| |
| \begin{verbatim} |
| #Print instance variables (usage "pi classInst") |
| alias pi for k in %1.__dict__.keys(): print "%1.",k,"=",%1.__dict__[k] |
| #Print instance variables in self |
| alias ps pi self |
| \end{verbatim} |
| |
| \item[unalias \var{name}] |
| |
| Deletes the specified alias. |
| |
| \item[\optional{!}\var{statement}] |
| |
| Execute the (one-line) \var{statement} in the context of |
| the current stack frame. |
| The exclamation point can be omitted unless the first word |
| of the statement resembles a debugger command. |
| To set a global variable, you can prefix the assignment |
| command with a \samp{global} command on the same line, e.g.: |
| |
| \begin{verbatim} |
| (Pdb) global list_options; list_options = ['-l'] |
| (Pdb) |
| \end{verbatim} |
| |
| \item[q(uit)] |
| |
| Quit from the debugger. |
| The program being executed is aborted. |
| |
| \end{description} |
| |
| \section{How It Works \label{debugger-hooks}} |
| |
| Some changes were made to the interpreter: |
| |
| \begin{itemize} |
| \item \code{sys.settrace(\var{func})} sets the global trace function |
| \item there can also a local trace function (see later) |
| \end{itemize} |
| |
| Trace functions have three arguments: \var{frame}, \var{event}, and |
| \var{arg}. \var{frame} is the current stack frame. \var{event} is a |
| string: \code{'call'}, \code{'line'}, \code{'return'}, \code{'exception'}, |
| \code{'c_call'}, \code{'c_return'}, or \code{'c_exception'}. \var{arg} |
| depends on the event type. |
| |
| The global trace function is invoked (with \var{event} set to |
| \code{'call'}) whenever a new local scope is entered; it should return |
| a reference to the local trace function to be used that scope, or |
| \code{None} if the scope shouldn't be traced. |
| |
| The local trace function should return a reference to itself (or to |
| another function for further tracing in that scope), or \code{None} to |
| turn off tracing in that scope. |
| |
| Instance methods are accepted (and very useful!) as trace functions. |
| |
| The events have the following meaning: |
| |
| \begin{description} |
| |
| \item[\code{'call'}] |
| A function is called (or some other code block entered). The global |
| trace function is called; \var{arg} is \code{None}; |
| the return value specifies the local trace function. |
| |
| \item[\code{'line'}] |
| The interpreter is about to execute a new line of code (sometimes |
| multiple line events on one line exist). The local trace function is |
| called; \var{arg} is \code{None}; the return value specifies the new |
| local trace function. |
| |
| \item[\code{'return'}] |
| A function (or other code block) is about to return. The local trace |
| function is called; \var{arg} is the value that will be returned. The |
| trace function's return value is ignored. |
| |
| \item[\code{'exception'}] |
| An exception has occurred. The local trace function is called; |
| \var{arg} is a triple \code{(\var{exception}, \var{value}, |
| \var{traceback})}; the return value specifies the new local trace |
| function. |
| |
| \item[\code{'c_call'}] |
| A C function is about to be called. This may be an extension function |
| or a builtin. \var{arg} is the C function object. |
| |
| \item[\code{'c_return'}] |
| A C function has returned. \var{arg} is \code{None}. |
| |
| \item[\code{'c_exception'}] |
| A C function has thrown an exception. \var{arg} is \code{None}. |
| |
| \end{description} |
| |
| Note that as an exception is propagated down the chain of callers, an |
| \code{'exception'} event is generated at each level. |
| |
| For more information on code and frame objects, refer to the |
| \citetitle[../ref/ref.html]{Python Reference Manual}. |