[OpenSPARC-T2-SAM] / sam-t2 / devtools / amd64 / html / python / lib / module-pdb.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="lib.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index' />
<link rel="first" href="lib.html" title='Python Library Reference' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="profile.html" />
<link rel="prev" href="unix.html" />
<link rel="parent" href="lib.html" />
<link rel="next" href="debugger-commands.html" />
<meta name='aesop' content='information' />
<title>9. The Python Debugger </title>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="8.17 commands  "
  href="module-commands.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="Python Library Reference"
  href="lib.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="9.1 Debugger Commands"
  href="debugger-commands.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="module-commands.html">8.17 commands  </A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="lib.html">Python Library Reference</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="debugger-commands.html">9.1 Debugger Commands</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

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

<P>
<A NAME="module-pdb"></A>

<P>
The module <tt class="module">pdb</tt> defines an interactive source code
debugger<a id='l2h-3099' xml:id='l2h-3099'></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 id='l2h-3092' xml:id='l2h-3092'></a>.
This is currently undocumented but easily understood by reading the
source.  The extension interface uses the modules
<tt class="module">bdb</tt><a id='l2h-3100' xml:id='l2h-3100'></a> (undocumented) and
<tt class="module"><a href="module-cmd.html">cmd</a></tt><a id='l2h-3101' xml:id='l2h-3101'></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>
<div class="verbatim"><pre>
&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></div>

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

<P>
<div class="verbatim"><pre>
python -m pdb myscript.py
</pre></div>

<P>
When invoked as a script, pdb will automatically enter post-mortem debugging
if the program being debugged exits abnormally. After post-mortem debugging
(or after normal exit of the program), pdb will restart the program.
Automatic restarting preserves pdb's state (such as breakpoints) and in most
cases is more useful than quitting the debugger upon program's exit.

<span class="versionnote">New in version 2.4:
Restarting post-mortem behavior added.</span>

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

<P>
<div class="verbatim"><pre>
&gt;&gt;&gt; import pdb
&gt;&gt;&gt; import mymodule
&gt;&gt;&gt; mymodule.test()
Traceback (most recent call 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></div>

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

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3093' xml:id='l2h-3093' class="function">run</tt></b>(</nobr></td>
  <td><var>statement</var><big>[</big><var>, globals</var><big>[</big><var>, locals</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
<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"><a href="module-main.html">__main__</a></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><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3094' xml:id='l2h-3094' class="function">runeval</tt></b>(</nobr></td>
  <td><var>expression</var><big>[</big><var>, globals</var><big>[</big><var>, locals</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Evaluate the <var>expression</var> (given as 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><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3095' xml:id='l2h-3095' class="function">runcall</tt></b>(</nobr></td>
  <td><var>function</var><big>[</big><var>, argument, ...</var><big>]</big><var></var>)</td></tr></table></dt>
<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><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3096' xml:id='l2h-3096' class="function">set_trace</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<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><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3097' xml:id='l2h-3097' class="function">post_mortem</tt></b>(</nobr></td>
  <td><var>traceback</var>)</td></tr></table></dt>
<dd>
Enter post-mortem debugging of the given <var>traceback</var> object.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3098' xml:id='l2h-3098' class="function">pm</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Enter post-mortem debugging of the traceback found in
<code>sys.last_traceback</code>.
</dl>

<P>

<p><br /></p><hr class='online-navigation' />
<div class='online-navigation'>
<!--Table of Child-Links-->
<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a>

<UL CLASS="ChildLinks">
<LI><A href="debugger-commands.html">9.1 Debugger Commands</a>
<LI><A href="debugger-hooks.html">9.2 How It Works</a>
</ul>
<!--End of Table of Child-Links-->
</div>

<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="8.17 commands  "
  href="module-commands.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="Python Library Reference"
  href="lib.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="9.1 Debugger Commands"
  href="debugger-commands.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="module-commands.html">8.17 commands  </A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="lib.html">Python Library Reference</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="debugger-commands.html">9.1 Debugger Commands</A>
</div>
</div>
<hr />
<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>
Commit	Line	Data
920dae64 AT	1	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	2	<html>
	3	<head>
	4	<link rel="STYLESHEET" href="lib.css" type='text/css' />
	5	<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
	6	<link rel='start' href='../index.html' title='Python Documentation Index' />
	7	<link rel="first" href="lib.html" title='Python Library Reference' />
	8	<link rel='contents' href='contents.html' title="Contents" />
	9	<link rel='index' href='genindex.html' title='Index' />
	10	<link rel='last' href='about.html' title='About this document...' />
	11	<link rel='help' href='about.html' title='About this document...' />
	12	<link rel="next" href="profile.html" />
	13	<link rel="prev" href="unix.html" />
	14	<link rel="parent" href="lib.html" />
	15	<link rel="next" href="debugger-commands.html" />
	16	<meta name='aesop' content='information' />
	17	<title>9. The Python Debugger </title>
	18	</head>
	19	<body>
	20	<DIV CLASS="navigation">
	21	<div id='top-navigation-panel' xml:id='top-navigation-panel'>
	22	<table align="center" width="100%" cellpadding="0" cellspacing="2">
	23	<tr>
	24	<td class='online-navigation'><a rel="prev" title="8.17 commands "
	25	href="module-commands.html"><img src='../icons/previous.png'
	26	border='0' height='32' alt='Previous Page' width='32' /></A></td>
	27	<td class='online-navigation'><a rel="parent" title="Python Library Reference"
	28	href="lib.html"><img src='../icons/up.png'
	29	border='0' height='32' alt='Up One Level' width='32' /></A></td>
	30	<td class='online-navigation'><a rel="next" title="9.1 Debugger Commands"
	31	href="debugger-commands.html"><img src='../icons/next.png'
	32	border='0' height='32' alt='Next Page' width='32' /></A></td>
	33	<td align="center" width="100%">Python Library Reference</td>
	34	<td class='online-navigation'><a rel="contents" title="Table of Contents"
	35	href="contents.html"><img src='../icons/contents.png'
	36	border='0' height='32' alt='Contents' width='32' /></A></td>
	37	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
	38	border='0' height='32' alt='Module Index' width='32' /></a></td>
	39	<td class='online-navigation'><a rel="index" title="Index"
	40	href="genindex.html"><img src='../icons/index.png'
	41	border='0' height='32' alt='Index' width='32' /></A></td>
	42	</tr></table>
	43	<div class='online-navigation'>
	44	<b class="navlabel">Previous:</b>
	45	<a class="sectref" rel="prev" href="module-commands.html">8.17 commands </A>
	46	<b class="navlabel">Up:</b>
	47	<a class="sectref" rel="parent" href="lib.html">Python Library Reference</A>
	48	<b class="navlabel">Next:</b>
	49	<a class="sectref" rel="next" href="debugger-commands.html">9.1 Debugger Commands</A>
	50	</div>
	51	<hr /></div>
	52	</DIV>
	53	<!--End of Navigation Panel-->
	54
	55	<H1><A NAME="SECTION0011000000000000000000"></A><A NAME="debugger"></A>
	56	<BR>
	57	9. The Python Debugger
	58	</H1>
	59
	60	<P>
	61	<A NAME="module-pdb"></A>
	62
	63	<P>
	64	The module <tt class="module">pdb</tt> defines an interactive source code
65	debugger<a id='l2h-3099' xml:id='l2h-3099'></a> for Python programs. It supports setting
66	(conditional) breakpoints and single stepping at the source line
67	level, inspection of stack frames, source code listing, and evaluation
68	of arbitrary Python code in the context of any stack frame. It also
69	supports post-mortem debugging and can be called under program
70	control.
71
72	<P>
73	The debugger is extensible -- it is actually defined as the class
74	<tt class="class">Pdb</tt><a id='l2h-3092' xml:id='l2h-3092'></a>.
75	This is currently undocumented but easily understood by reading the
76	source. The extension interface uses the modules
77	<tt class="module">bdb</tt><a id='l2h-3100' xml:id='l2h-3100'></a> (undocumented) and
78	<tt class="module"><a href="module-cmd.html">cmd</a></tt><a id='l2h-3101' xml:id='l2h-3101'></a>.
79
80	<P>
81	The debugger's prompt is "<tt class="samp">(Pdb) </tt>".
82	Typical usage to run a program under control of the debugger is:
83
84	<P>
85	<div class="verbatim"><pre>
86	>>> import pdb
87	>>> import mymodule
88	>>> pdb.run('mymodule.test()')
89	> <string>(0)?()
90	(Pdb) continue
91	> <string>(1)?()
92	(Pdb) continue
93	NameError: 'spam'
94	> <string>(1)?()
95	(Pdb)
96	</pre></div>
97
98	<P>
99	<span class="file">pdb.py</span> can also be invoked as
100	a script to debug other scripts. For example:
101
102	<P>
103	<div class="verbatim"><pre>
104	python -m pdb myscript.py
105	</pre></div>
106
107	<P>
108	When invoked as a script, pdb will automatically enter post-mortem debugging
109	if the program being debugged exits abnormally. After post-mortem debugging
110	(or after normal exit of the program), pdb will restart the program.
111	Automatic restarting preserves pdb's state (such as breakpoints) and in most
112	cases is more useful than quitting the debugger upon program's exit.
113
114	<span class="versionnote">New in version 2.4:
115	Restarting post-mortem behavior added.</span>
116
117	<P>
118	Typical usage to inspect a crashed program is:
119
120	<P>
121	<div class="verbatim"><pre>
122	>>> import pdb
123	>>> import mymodule
124	>>> mymodule.test()
125	Traceback (most recent call last):
126	File "<stdin>", line 1, in ?
127	File "./mymodule.py", line 4, in test
128	test2()
129	File "./mymodule.py", line 3, in test2
130	print spam
131	NameError: spam
132	>>> pdb.pm()
133	> ./mymodule.py(3)test2()
134	-> print spam
135	(Pdb)
136	</pre></div>
137
138	<P>
139	The module defines the following functions; each enters the debugger
140	in a slightly different way:
141
142	<P>
143	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
144	<td><nobr><b><tt id='l2h-3093' xml:id='l2h-3093' class="function">run</tt></b>(</nobr></td>
145	<td><var>statement</var><big>[</big><var>, globals</var><big>[</big><var>, locals</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
146	<dd>
147	Execute the <var>statement</var> (given as a string) under debugger
148	control. The debugger prompt appears before any code is executed; you
149	can set breakpoints and type "<tt class="samp">continue</tt>", or you can step through
150	the statement using "<tt class="samp">step</tt>" or "<tt class="samp">next</tt>" (all these commands are
151	explained below). The optional <var>globals</var> and <var>locals</var>
152	arguments specify the environment in which the code is executed; by
153	default the dictionary of the module <tt class="module"><a href="module-main.html">__main__</a></tt> is
154	used. (See the explanation of the <tt class="keyword">exec</tt> statement or the
155	<tt class="function">eval()</tt> built-in function.)
156	</dl>
157
158	<P>
159	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
160	<td><nobr><b><tt id='l2h-3094' xml:id='l2h-3094' class="function">runeval</tt></b>(</nobr></td>
161	<td><var>expression</var><big>[</big><var>, globals</var><big>[</big><var>, locals</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
162	<dd>
163	Evaluate the <var>expression</var> (given as a string) under debugger
164	control. When <tt class="function">runeval()</tt> returns, it returns the value of the
165	expression. Otherwise this function is similar to
166	<tt class="function">run()</tt>.
167	</dl>
168
169	<P>
170	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
171	<td><nobr><b><tt id='l2h-3095' xml:id='l2h-3095' class="function">runcall</tt></b>(</nobr></td>
172	<td><var>function</var><big>[</big><var>, argument, ...</var><big>]</big><var></var>)</td></tr></table></dt>
173	<dd>
174	Call the <var>function</var> (a function or method object, not a string)
175	with the given arguments. When <tt class="function">runcall()</tt> returns, it returns
176	whatever the function call returned. The debugger prompt appears as
177	soon as the function is entered.
178	</dl>
179
180	<P>
181	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
182	<td><nobr><b><tt id='l2h-3096' xml:id='l2h-3096' class="function">set_trace</tt></b>(</nobr></td>
183	<td><var></var>)</td></tr></table></dt>
184	<dd>
185	Enter the debugger at the calling stack frame. This is useful to
186	hard-code a breakpoint at a given point in a program, even if the code
187	is not otherwise being debugged (e.g. when an assertion fails).
188	</dl>
189
190	<P>
191	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
192	<td><nobr><b><tt id='l2h-3097' xml:id='l2h-3097' class="function">post_mortem</tt></b>(</nobr></td>
193	<td><var>traceback</var>)</td></tr></table></dt>
194	<dd>
195	Enter post-mortem debugging of the given <var>traceback</var> object.
196	</dl>
197
198	<P>
199	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
200	<td><nobr><b><tt id='l2h-3098' xml:id='l2h-3098' class="function">pm</tt></b>(</nobr></td>
201	<td><var></var>)</td></tr></table></dt>
202	<dd>
203	Enter post-mortem debugging of the traceback found in
204	<code>sys.last_traceback</code>.
205	</dl>
206
207	<P>
208
209	<p><br /></p><hr class='online-navigation' />
210	<div class='online-navigation'>
211	<!--Table of Child-Links-->
212	<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a>
213
214	<UL CLASS="ChildLinks">
215	<LI><A href="debugger-commands.html">9.1 Debugger Commands</a>
216	<LI><A href="debugger-hooks.html">9.2 How It Works</a>
217	</ul>
218	<!--End of Table of Child-Links-->
219	</div>
220
221	<DIV CLASS="navigation">
222	<div class='online-navigation'>
223	<p></p><hr />
224	<table align="center" width="100%" cellpadding="0" cellspacing="2">
225	<tr>
226	<td class='online-navigation'><a rel="prev" title="8.17 commands "
227	href="module-commands.html"><img src='../icons/previous.png'
228	border='0' height='32' alt='Previous Page' width='32' /></A></td>
229	<td class='online-navigation'><a rel="parent" title="Python Library Reference"
230	href="lib.html"><img src='../icons/up.png'
231	border='0' height='32' alt='Up One Level' width='32' /></A></td>
232	<td class='online-navigation'><a rel="next" title="9.1 Debugger Commands"
233	href="debugger-commands.html"><img src='../icons/next.png'
234	border='0' height='32' alt='Next Page' width='32' /></A></td>
235	<td align="center" width="100%">Python Library Reference</td>
236	<td class='online-navigation'><a rel="contents" title="Table of Contents"
237	href="contents.html"><img src='../icons/contents.png'
238	border='0' height='32' alt='Contents' width='32' /></A></td>
239	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
240	border='0' height='32' alt='Module Index' width='32' /></a></td>
241	<td class='online-navigation'><a rel="index" title="Index"
242	href="genindex.html"><img src='../icons/index.png'
243	border='0' height='32' alt='Index' width='32' /></A></td>
244	</tr></table>
245	<div class='online-navigation'>
246	<b class="navlabel">Previous:</b>
247	<a class="sectref" rel="prev" href="module-commands.html">8.17 commands </A>
248	<b class="navlabel">Up:</b>
249	<a class="sectref" rel="parent" href="lib.html">Python Library Reference</A>
250	<b class="navlabel">Next:</b>
251	<a class="sectref" rel="next" href="debugger-commands.html">9.1 Debugger Commands</A>
252	</div>
253	</div>
254	<hr />
255	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
256	</DIV>
257	<!--End of Navigation Panel-->
258	<ADDRESS>
259	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
260	</ADDRESS>
261	</BODY>
262	</HTML>