411 lines
15 KiB
TeX
411 lines
15 KiB
TeX
\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}.
|