<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!--Converted with LaTeX2HTML 98.2 beta6 (August 14th, 1998)
original version by:  Nikos Drakos, CBLU, University of Leeds
* revised and updated by:  Marcus Hennecke, Ross Moore, Herb Swan
* with significant contributions from:
  Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
<HTML>
<HEAD>
<TITLE>9. The Python Debugger</TITLE>
<META NAME="description" CONTENT="9. The Python Debugger">
<META NAME="keywords" CONTENT="lib">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<LINK REL="STYLESHEET" HREF="lib.css">
<LINK REL="next" HREF="profile.html">
<LINK REL="previous" HREF="unix.html">
<LINK REL="up" HREF="lib.html">
<LINK REL="next" HREF="debugger-commands.html">
</HEAD>
<BODY bgcolor="#ffffff">
<div class=navigation>
<table align=center width="100%" cellpadding=0 cellspacing=2>
<tr>
<td><A HREF="debugger-commands.html"><img width=32 height=32 align=bottom border=0 alt="next"
 src="../icons/next.gif"></A></td>
<td><A HREF="lib.html"><img width=32 height=32 align=bottom border=0 alt="up"
 src="../icons/up.gif"></A></td>
<td><A HREF="module-commands.html"><img width=32 height=32 align=bottom border=0 alt="previous"
 src="../icons/previous.gif"></A></td>
<td align=center bgcolor="#99CCFF" width="100%">
 <b class=title>Python Library Reference</b></td>
<td><A HREF="contents.html"><img width=32 height=32 align=bottom border=0 alt="contents"
 src="../icons/contents.gif"></A></td>
<td><a
 href="modindex.html"><img width=32 height=32 align=bottom border=0 alt="modules"
 src="../icons/modules.gif"></a></td>
<td><A HREF="genindex.html"><img width=32 height=32 align=bottom border=0 alt="index"
 src="../icons/index.gif"></A></td>
</tr></table><b class=navlabel>Next:</b> <span class=sectref><A HREF="debugger-commands.html">9.1 Debugger Commands</A></span>
<b class=navlabel>Up:</b> <span class=sectref><A HREF="lib.html">Python Library Reference</A></span>
<b class=navlabel>Previous:</b> <span class=sectref><A HREF="module-commands.html">8.14 commands  </A></span>
<br><hr></div>
<!--End of Navigation Panel-->

<H1><A NAME="SECTION0011000000000000000000">
9. The Python Debugger</A>
</H1>

<P>


<P>
The module <tt class=module>pdb</tt> defines an interactive source code
debugger<a name="l2h-1556"></a> 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.

<P>
The debugger is extensible -- it is actually defined as the class
<tt class=class>Pdb</tt><a name="l2h-1549"></a>.
This is currently undocumented but easily understood by reading the
source.  The extension interface uses the modules
<tt class=module>bdb</tt><a name="l2h-1557"></a> (undocumented) and
<tt class=module><a href="module-cmd.html">cmd</a></tt><a name="l2h-1558"></a>.

<P>
A primitive windowing version of the debugger also exists -- this is
module <tt class=module>wdb</tt><a name="l2h-1559"></a>, which requires
<tt class=module>stdwin</tt><a name="l2h-1560"></a>.

<P>
The debugger's prompt is "<tt class=samp>(Pdb) </tt>".
Typical usage to run a program under control of the debugger is:

<P>
<dl><dd><pre class=verbatim>
&gt;&gt;&gt; import pdb
&gt;&gt;&gt; import mymodule
&gt;&gt;&gt; pdb.run('mymodule.test()')
&gt; &lt;string&gt;(0)?()
(Pdb) continue
&gt; &lt;string&gt;(1)?()
(Pdb) continue
NameError: 'spam'
&gt; &lt;string&gt;(1)?()
(Pdb)
</pre></dl>

<P>
<tt class=file>pdb.py</tt> can also be invoked as
a script to debug other scripts.  For example:

<P>
<dl><dd><pre class=verbatim>
python /usr/local/lib/python1.5/pdb.py myscript.py
</pre></dl>

<P>
Typical usage to inspect a crashed program is:

<P>
<dl><dd><pre class=verbatim>
&gt;&gt;&gt; import pdb
&gt;&gt;&gt; import mymodule
&gt;&gt;&gt; mymodule.test()
Traceback (innermost last):
  File "&lt;stdin&gt;", line 1, in ?
  File "./mymodule.py", line 4, in test
    test2()
  File "./mymodule.py", line 3, in test2
    print spam
NameError: spam
&gt;&gt;&gt; pdb.pm()
&gt; ./mymodule.py(3)test2()
-&gt; print spam
(Pdb)
</pre></dl>

<P>
The module defines the following functions; each enters the debugger
in a slightly different way:

<P>
<dl><dt><b><a name="l2h-1550"><tt class=function>run</tt></a></b> (<var>statement</var><big>[</big><var>, globals</var><big>[</big><var>, locals</var><big>]</big><big>]</big>)
<dd>
Execute the <var>statement</var> (given as a string) under debugger
control.  The debugger prompt appears before any code is executed; you
can set breakpoints and type "<tt class=samp>continue</tt>", or you can step through
the statement using "<tt class=samp>step</tt>" or "<tt class=samp>next</tt>" (all these commands are
explained below).  The optional <var>globals</var> and <var>locals</var>
arguments specify the environment in which the code is executed; by
default the dictionary of the module <tt class=module>__main__</tt> is used.  (See
the explanation of the <tt class=keyword>exec</tt> statement or the
<tt class=function>eval()</tt> built-in function.)
</dl>

<P>
<dl><dt><b><a name="l2h-1551"><tt class=function>runeval</tt></a></b> (<var>expression</var><big>[</big><var>, globals</var><big>[</big><var>, locals</var><big>]</big><big>]</big>)
<dd>
Evaluate the <var>expression</var> (given as a a string) under debugger
control.  When <tt class=function>runeval()</tt> returns, it returns the value of the
expression.  Otherwise this function is similar to
<tt class=function>run()</tt>.
</dl>

<P>
<dl><dt><b><a name="l2h-1552"><tt class=function>runcall</tt></a></b> (<var>function</var><big>[</big><var>, argument, ...</var><big>]</big>)
<dd>
Call the <var>function</var> (a function or method object, not a string)
with the given arguments.  When <tt class=function>runcall()</tt> returns, it returns
whatever the function call returned.  The debugger prompt appears as
soon as the function is entered.
</dl>

<P>
<dl><dt><b><a name="l2h-1553"><tt class=function>set_trace</tt></a></b> ()
<dd>
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).
</dl>

<P>
<dl><dt><b><a name="l2h-1554"><tt class=function>post_mortem</tt></a></b> (<var>traceback</var>)
<dd>
Enter post-mortem debugging of the given <var>traceback</var> object.
</dl>

<P>
<dl><dt><b><a name="l2h-1555"><tt class=function>pm</tt></a></b> ()
<dd>
Enter post-mortem debugging of the traceback found in
<tt>sys.last_traceback</tt>.
</dl>

<P>

<p><hr>
<!--Table of Child-Links-->


<UL>
<LI><A NAME="tex2html2649"
 HREF="debugger-commands.html">9.1 Debugger Commands </A>
<LI><A NAME="tex2html2650"
 HREF="node175.html">9.2 How It Works</A>
</UL>
<!--End of Table of Child-Links-->
<p>
<div class=navigation><hr><table align=center width="100%" cellpadding=0 cellspacing=2>
<tr>
<td><A HREF="debugger-commands.html"><img width=32 height=32 align=bottom border=0 alt="next"
 src="../icons/next.gif"></A></td>
<td><A HREF="lib.html"><img width=32 height=32 align=bottom border=0 alt="up"
 src="../icons/up.gif"></A></td>
<td><A HREF="module-commands.html"><img width=32 height=32 align=bottom border=0 alt="previous"
 src="../icons/previous.gif"></A></td>
<td align=center bgcolor="#99CCFF" width="100%">
 <b class=title>Python Library Reference</b></td>
<td><A HREF="contents.html"><img width=32 height=32 align=bottom border=0 alt="contents"
 src="../icons/contents.gif"></A></td>
<td><a
 href="modindex.html"><img width=32 height=32 align=bottom border=0 alt="modules"
 src="../icons/modules.gif"></a></td>
<td><A HREF="genindex.html"><img width=32 height=32 align=bottom border=0 alt="index"
 src="../icons/index.gif"></A></td>
</tr></table><b class=navlabel>Next:</b> <span class=sectref><A HREF="debugger-commands.html">9.1 Debugger Commands</A></span>
<b class=navlabel>Up:</b> <span class=sectref><A HREF="lib.html">Python Library Reference</A></span>
<b class=navlabel>Previous:</b> <span class=sectref><A HREF="module-commands.html">8.14 commands  </A></span>
</div>
<!--End of Navigation Panel-->
<ADDRESS>
<hr>Send comments on this document to <a href="mailto:python-docs@python.org">python-docs@python.org</a>.
</ADDRESS>
</BODY>
</HTML>
