Edit File - File Manager

Edit File: traceback.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 
 <title>27.9. traceback — Print or retrieve a stack traceback &mdash; Python v2.6.6 documentation</title>
 <link rel="stylesheet" href="../_static/default.css" type="text/css" />
 <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
 <script type="text/javascript">
 var DOCUMENTATION_OPTIONS = {
 URL_ROOT: '../',
 VERSION: '2.6.6',
 COLLAPSE_MODINDEX: false,
 FILE_SUFFIX: '.html',
 HAS_SOURCE: true
 };
 </script>
 <script type="text/javascript" src="../_static/jquery.js"></script>
 <script type="text/javascript" src="../_static/doctools.js"></script>
 <link rel="search" type="application/opensearchdescription+xml"
 title="Search within Python v2.6.6 documentation"
 href="../_static/opensearch.xml"/>
 <link rel="author" title="About these documents" href="../about.html" />
 <link rel="copyright" title="Copyright" href="../copyright.html" />
 <link rel="top" title="Python v2.6.6 documentation" href="../index.html" />
 <link rel="up" title="27. Python Runtime Services" href="python.html" />
 <link rel="next" title="27.10. __future__ — Future statement definitions" href="__future__.html" />
 <link rel="prev" title="27.8. atexit — Exit handlers" href="atexit.html" />
 <link rel="shortcut icon" type="image/png" href="../_static/py.png" />

</head>
 <body>
 <div class="related">
 <h3>Navigation</h3>
 <ul>
 <li class="right" style="margin-right: 10px">
 <a href="../genindex.html" title="General Index"
 accesskey="I">index</a></li>
 <li class="right" >
 <a href="../modindex.html" title="Global Module Index"
 accesskey="M">modules</a> |</li>
 <li class="right" >
 <a href="__future__.html" title="27.10. __future__ — Future statement definitions"
 accesskey="N">next</a> |</li>
 <li class="right" >
 <a href="atexit.html" title="27.8. atexit — Exit handlers"
 accesskey="P">previous</a> |</li>
 <li><img src="../_static/py.png" alt=""
 style="vertical-align: middle; margin-top: -1px"/></li>
 <li><a href="../index.html">Python v2.6.6 documentation</a> &raquo;</li>

<li><a href="index.html" >The Python Standard Library</a> &raquo;</li>
 <li><a href="python.html" accesskey="U">27. Python Runtime Services</a> &raquo;</li> 
 </ul>
 </div>

<div class="document">
 <div class="documentwrapper">
 <div class="bodywrapper">
 <div class="body">
 
 <div class="section" id="module-traceback">
<h1>27.9. <tt class="xref docutils literal">traceback</tt> &#8212; Print or retrieve a stack traceback<a class="headerlink" href="#module-traceback" title="Permalink to this headline">¶</a></h1>
This module provides a standard interface to extract, format and print stack
traces of Python programs. It exactly mimics the behavior of the Python
interpreter when it prints a stack trace. This is useful when you want to print
stack traces under program control, such as in a &#8220;wrapper&#8221; around the
interpreter.
The module uses traceback objects &#8212; this is the object type that is stored in
the variables <a title="sys.exc_traceback" class="reference external" href="sys.html#sys.exc_traceback"><tt class="xref docutils literal">sys.exc_traceback</tt></a> (deprecated) and <a title="sys.last_traceback" class="reference external" href="sys.html#sys.last_traceback"><tt class="xref docutils literal">sys.last_traceback</tt></a> and
returned as the third item from <a title="sys.exc_info" class="reference external" href="sys.html#sys.exc_info"><tt class="xref docutils literal">sys.exc_info()</tt></a>.
The module defines the following functions:
<dl class="function">
<dt id="traceback.print_tb">
<tt class="descclassname">traceback.</tt><tt class="descname">print_tb</tt><big>(</big>traceback[, limit[, file]]<big>)</big><a class="headerlink" href="#traceback.print_tb" title="Permalink to this definition">¶</a></dt>
<dd>Print up to limit stack trace entries from traceback. If limit is omitted
or <tt class="xref docutils literal">None</tt>, all entries are printed. If file is omitted or <tt class="xref docutils literal">None</tt>, the
output goes to <tt class="docutils literal">sys.stderr</tt>; otherwise it should be an open file or file-like
object to receive the output.</dd></dl>

<dl class="function">
<dt id="traceback.print_exception">
<tt class="descclassname">traceback.</tt><tt class="descname">print_exception</tt><big>(</big>type, value, traceback[, limit[, file]]<big>)</big><a class="headerlink" href="#traceback.print_exception" title="Permalink to this definition">¶</a></dt>
<dd>Print exception information and up to limit stack trace entries from
traceback to file. This differs from <a title="traceback.print_tb" class="reference internal" href="#traceback.print_tb"><tt class="xref docutils literal">print_tb()</tt></a> in the following ways:
(1) if traceback is not <tt class="xref docutils literal">None</tt>, it prints a header <tt class="docutils literal">Traceback (most recent
call last):</tt>; (2) it prints the exception type and value after the stack
trace; (3) if type is <a title="exceptions.SyntaxError" class="reference external" href="exceptions.html#exceptions.SyntaxError"><tt class="xref docutils literal">SyntaxError</tt></a> and value has the appropriate
format, it prints the line where the syntax error occurred with a caret
indicating the approximate position of the error.</dd></dl>

<dl class="function">
<dt id="traceback.print_exc">
<tt class="descclassname">traceback.</tt><tt class="descname">print_exc</tt><big>(</big>[limit[, file]]<big>)</big><a class="headerlink" href="#traceback.print_exc" title="Permalink to this definition">¶</a></dt>
<dd>This is a shorthand for <tt class="docutils literal">print_exception(sys.exc_type, sys.exc_value,
sys.exc_traceback, limit, file)</tt>. (In fact, it uses <a title="sys.exc_info" class="reference external" href="sys.html#sys.exc_info"><tt class="xref docutils literal">sys.exc_info()</tt></a> to
retrieve the same information in a thread-safe way instead of using the
deprecated variables.)</dd></dl>

<dl class="function">
<dt id="traceback.format_exc">
<tt class="descclassname">traceback.</tt><tt class="descname">format_exc</tt><big>(</big>[limit]<big>)</big><a class="headerlink" href="#traceback.format_exc" title="Permalink to this definition">¶</a></dt>
<dd>This is like <tt class="docutils literal">print_exc(limit)</tt> but returns a string instead of printing to a
file.

New in version 2.4.
</dd></dl>

<dl class="function">
<dt id="traceback.print_last">
<tt class="descclassname">traceback.</tt><tt class="descname">print_last</tt><big>(</big>[limit[, file]]<big>)</big><a class="headerlink" href="#traceback.print_last" title="Permalink to this definition">¶</a></dt>
<dd>This is a shorthand for <tt class="docutils literal">print_exception(sys.last_type, sys.last_value,
sys.last_traceback, limit, file)</tt>. In general it will work only after
an exception has reached an interactive prompt (see <a title="sys.last_type" class="reference external" href="sys.html#sys.last_type"><tt class="xref docutils literal">sys.last_type</tt></a>).</dd></dl>

<dl class="function">
<dt id="traceback.print_stack">
<tt class="descclassname">traceback.</tt><tt class="descname">print_stack</tt><big>(</big>[f[, limit[, file]]]<big>)</big><a class="headerlink" href="#traceback.print_stack" title="Permalink to this definition">¶</a></dt>
<dd>This function prints a stack trace from its invocation point. The optional f
argument can be used to specify an alternate stack frame to start. The optional
limit and file arguments have the same meaning as for
<a title="traceback.print_exception" class="reference internal" href="#traceback.print_exception"><tt class="xref docutils literal">print_exception()</tt></a>.</dd></dl>

<dl class="function">
<dt id="traceback.extract_tb">
<tt class="descclassname">traceback.</tt><tt class="descname">extract_tb</tt><big>(</big>traceback[, limit]<big>)</big><a class="headerlink" href="#traceback.extract_tb" title="Permalink to this definition">¶</a></dt>
<dd>Return a list of up to limit &#8220;pre-processed&#8221; stack trace entries extracted
from the traceback object traceback. It is useful for alternate formatting of
stack traces. If limit is omitted or <tt class="xref docutils literal">None</tt>, all entries are extracted. A
&#8220;pre-processed&#8221; stack trace entry is a quadruple (filename, line number,
function name, text) representing the information that is usually printed
for a stack trace. The text is a string with leading and trailing whitespace
stripped; if the source is not available it is <tt class="xref docutils literal">None</tt>.</dd></dl>

<dl class="function">
<dt id="traceback.extract_stack">
<tt class="descclassname">traceback.</tt><tt class="descname">extract_stack</tt><big>(</big>[f[, limit]]<big>)</big><a class="headerlink" href="#traceback.extract_stack" title="Permalink to this definition">¶</a></dt>
<dd>Extract the raw traceback from the current stack frame. The return value has
the same format as for <a title="traceback.extract_tb" class="reference internal" href="#traceback.extract_tb"><tt class="xref docutils literal">extract_tb()</tt></a>. The optional f and limit
arguments have the same meaning as for <a title="traceback.print_stack" class="reference internal" href="#traceback.print_stack"><tt class="xref docutils literal">print_stack()</tt></a>.</dd></dl>

<dl class="function">
<dt id="traceback.format_list">
<tt class="descclassname">traceback.</tt><tt class="descname">format_list</tt><big>(</big>list<big>)</big><a class="headerlink" href="#traceback.format_list" title="Permalink to this definition">¶</a></dt>
<dd>Given a list of tuples as returned by <a title="traceback.extract_tb" class="reference internal" href="#traceback.extract_tb"><tt class="xref docutils literal">extract_tb()</tt></a> or
<a title="traceback.extract_stack" class="reference internal" href="#traceback.extract_stack"><tt class="xref docutils literal">extract_stack()</tt></a>, return a list of strings ready for printing. Each string
in the resulting list corresponds to the item with the same index in the
argument list. Each string ends in a newline; the strings may contain internal
newlines as well, for those items whose source text line is not <tt class="xref docutils literal">None</tt>.</dd></dl>

<dl class="function">
<dt id="traceback.format_exception_only">
<tt class="descclassname">traceback.</tt><tt class="descname">format_exception_only</tt><big>(</big>type, value<big>)</big><a class="headerlink" href="#traceback.format_exception_only" title="Permalink to this definition">¶</a></dt>
<dd>Format the exception part of a traceback. The arguments are the exception type
and value such as given by <tt class="docutils literal">sys.last_type</tt> and <tt class="docutils literal">sys.last_value</tt>. The return
value is a list of strings, each ending in a newline. Normally, the list
contains a single string; however, for <a title="exceptions.SyntaxError" class="reference external" href="exceptions.html#exceptions.SyntaxError"><tt class="xref docutils literal">SyntaxError</tt></a> exceptions, it
contains several lines that (when printed) display detailed information about
where the syntax error occurred. The message indicating which exception
occurred is the always last string in the list.</dd></dl>

<dl class="function">
<dt id="traceback.format_exception">
<tt class="descclassname">traceback.</tt><tt class="descname">format_exception</tt><big>(</big>type, value, tb[, limit]<big>)</big><a class="headerlink" href="#traceback.format_exception" title="Permalink to this definition">¶</a></dt>
<dd>Format a stack trace and the exception information. The arguments have the
same meaning as the corresponding arguments to <a title="traceback.print_exception" class="reference internal" href="#traceback.print_exception"><tt class="xref docutils literal">print_exception()</tt></a>. The
return value is a list of strings, each ending in a newline and some containing
internal newlines. When these lines are concatenated and printed, exactly the
same text is printed as does <a title="traceback.print_exception" class="reference internal" href="#traceback.print_exception"><tt class="xref docutils literal">print_exception()</tt></a>.</dd></dl>

<dl class="function">
<dt id="traceback.format_tb">
<tt class="descclassname">traceback.</tt><tt class="descname">format_tb</tt><big>(</big>tb[, limit]<big>)</big><a class="headerlink" href="#traceback.format_tb" title="Permalink to this definition">¶</a></dt>
<dd>A shorthand for <tt class="docutils literal">format_list(extract_tb(tb, limit))</tt>.</dd></dl>

<dl class="function">
<dt id="traceback.format_stack">
<tt class="descclassname">traceback.</tt><tt class="descname">format_stack</tt><big>(</big>[f[, limit]]<big>)</big><a class="headerlink" href="#traceback.format_stack" title="Permalink to this definition">¶</a></dt>
<dd>A shorthand for <tt class="docutils literal">format_list(extract_stack(f, limit))</tt>.</dd></dl>

<dl class="function">
<dt id="traceback.tb_lineno">
<tt class="descclassname">traceback.</tt><tt class="descname">tb_lineno</tt><big>(</big>tb<big>)</big><a class="headerlink" href="#traceback.tb_lineno" title="Permalink to this definition">¶</a></dt>
<dd>This function returns the current line number set in the traceback object. This
function was necessary because in versions of Python prior to 2.3 when the
<a class="reference external" href="../using/cmdline.html#cmdoption-O">-O</a> flag was passed to Python the <tt class="docutils literal">tb.tb_lineno</tt> was not updated
correctly. This function has no use in versions past 2.3.</dd></dl>

<div class="section" id="traceback-examples">
<h2>27.9.1. Traceback Examples<a class="headerlink" href="#traceback-examples" title="Permalink to this headline">¶</a></h2>
This simple example implements a basic read-eval-print loop, similar to (but
less useful than) the standard Python interactive interpreter loop. For a more
complete implementation of the interpreter loop, refer to the <a title="Facilities to implement read-eval-print loops." class="reference external" href="code.html#module-code"><tt class="xref docutils literal">code</tt></a>
module.
<div class="highlight-python"><div class="highlight"><pre>import sys, traceback

def run_user_code(envdir):
 source = raw_input(&quot;&gt;&gt;&gt; &quot;)
 try:
 exec source in envdir
 except:
 print &quot;Exception in user code:&quot;
 print &#39;-&#39;*60
 traceback.print_exc(file=sys.stdout)
 print &#39;-&#39;*60

envdir = {}
while 1:
 run_user_code(envdir)
</pre></div>
</div>
The following example demonstrates the different ways to print and format the
exception and traceback:
<div class="highlight-python"><div class="highlight"><pre>import sys, traceback

def lumberjack():
 bright_side_of_death()

def bright_side_of_death():
 return tuple()[0]

try:
 lumberjack()
except IndexError:
 exc_type, exc_value, exc_traceback = sys.exc_info()
 print &quot;*** print_tb:&quot;
 traceback.print_tb(exc_traceback, limit=1, file=sys.stdout)
 print &quot;*** print_exception:&quot;
 traceback.print_exception(exc_type, exc_value, exc_traceback,
 limit=2, file=sys.stdout)
 print &quot;*** print_exc:&quot;
 traceback.print_exc()
 print &quot;*** format_exc, first and last line:&quot;
 formatted_lines = traceback.format_exc().splitlines()
 print formatted_lines[0]
 print formatted_lines[-1]
 print &quot;*** format_exception:&quot;
 print repr(traceback.format_exception(exc_type, exc_value,
 exc_traceback))
 print &quot;*** extract_tb:&quot;
 print repr(traceback.extract_tb(exc_traceback))
 print &quot;*** format_tb:&quot;
 print repr(traceback.format_tb(exc_traceback))
 print &quot;*** tb_lineno:&quot;, exc_traceback.tb_lineno
</pre></div>
</div>
The output for the example would look similar to this:
<div class="highlight-python"><pre>*** print_tb:
 File "&lt;doctest...&gt;", line 10, in &lt;module&gt;
 lumberjack()
*** print_exception:
Traceback (most recent call last):
 File "&lt;doctest...&gt;", line 10, in &lt;module&gt;
 lumberjack()
 File "&lt;doctest...&gt;", line 4, in lumberjack
 bright_side_of_death()
IndexError: tuple index out of range
*** print_exc:
Traceback (most recent call last):
 File "&lt;doctest...&gt;", line 10, in &lt;module&gt;
 lumberjack()
 File "&lt;doctest...&gt;", line 4, in lumberjack
 bright_side_of_death()
IndexError: tuple index out of range
*** format_exc, first and last line:
Traceback (most recent call last):
IndexError: tuple index out of range
*** format_exception:
['Traceback (most recent call last):\n',
 ' File "&lt;doctest...&gt;", line 10, in &lt;module&gt;\n lumberjack()\n',
 ' File "&lt;doctest...&gt;", line 4, in lumberjack\n bright_side_of_death()\n',
 ' File "&lt;doctest...&gt;", line 7, in bright_side_of_death\n return tuple()[0]\n',
 'IndexError: tuple index out of range\n']
*** extract_tb:
[('&lt;doctest...&gt;', 10, '&lt;module&gt;', 'lumberjack()'),
 ('&lt;doctest...&gt;', 4, 'lumberjack', 'bright_side_of_death()'),
 ('&lt;doctest...&gt;', 7, 'bright_side_of_death', 'return tuple()[0]')]
*** format_tb:
[' File "&lt;doctest...&gt;", line 10, in &lt;module&gt;\n lumberjack()\n',
 ' File "&lt;doctest...&gt;", line 4, in lumberjack\n bright_side_of_death()\n',
 ' File "&lt;doctest...&gt;", line 7, in bright_side_of_death\n return tuple()[0]\n']
*** tb_lineno: 10</pre>
</div>
The following example shows the different ways to print and format the stack:
<div class="highlight-python"><div class="highlight"><pre>&gt;&gt;&gt; import traceback
&gt;&gt;&gt; def another_function():
... lumberstack()
...
&gt;&gt;&gt; def lumberstack():
... traceback.print_stack()
... print repr(traceback.extract_stack())
... print repr(traceback.format_stack())
...
&gt;&gt;&gt; another_function()
 File &quot;&lt;doctest&gt;&quot;, line 10, in &lt;module&gt;
 another_function()
 File &quot;&lt;doctest&gt;&quot;, line 3, in another_function
 lumberstack()
 File &quot;&lt;doctest&gt;&quot;, line 6, in lumberstack
 traceback.print_stack()
[(&#39;&lt;doctest&gt;&#39;, 10, &#39;&lt;module&gt;&#39;, &#39;another_function()&#39;),
 (&#39;&lt;doctest&gt;&#39;, 3, &#39;another_function&#39;, &#39;lumberstack()&#39;),
 (&#39;&lt;doctest&gt;&#39;, 7, &#39;lumberstack&#39;, &#39;print repr(traceback.extract_stack())&#39;)]
[&#39; File &quot;&lt;doctest&gt;&quot;, line 10, in &lt;module&gt;\n another_function()\n&#39;,
 &#39; File &quot;&lt;doctest&gt;&quot;, line 3, in another_function\n lumberstack()\n&#39;,
 &#39; File &quot;&lt;doctest&gt;&quot;, line 8, in lumberstack\n print repr(traceback.format_stack())\n&#39;]
</pre></div>
</div>
This last example demonstrates the final few formatting functions:
<div class="highlight-python"><div class="highlight"><pre>&gt;&gt;&gt; import traceback
&gt;&gt;&gt; traceback.format_list([(&#39;spam.py&#39;, 3, &#39;&lt;module&gt;&#39;, &#39;spam.eggs()&#39;),
... (&#39;eggs.py&#39;, 42, &#39;eggs&#39;, &#39;return &quot;bacon&quot;&#39;)])
[&#39; File &quot;spam.py&quot;, line 3, in &lt;module&gt;\n spam.eggs()\n&#39;,
 &#39; File &quot;eggs.py&quot;, line 42, in eggs\n return &quot;bacon&quot;\n&#39;]
&gt;&gt;&gt; an_error = IndexError(&#39;tuple index out of range&#39;)
&gt;&gt;&gt; traceback.format_exception_only(type(an_error), an_error)
[&#39;IndexError: tuple index out of range\n&#39;]
</pre></div>
</div>
</div>
</div>

</div>
 </div>
 </div>
 <div class="sphinxsidebar">
 <div class="sphinxsidebarwrapper">
 <h3><a href="../contents.html">Table Of Contents</a></h3>
 <ul>
<li><a class="reference external" href="#">27.9. <tt class="docutils literal">traceback</tt> &#8212; Print or retrieve a stack traceback</a><ul>
<li><a class="reference external" href="#traceback-examples">27.9.1. Traceback Examples</a></li>
</ul>
</li>
</ul>

<h4>Previous topic</h4>
 <a href="atexit.html"
 title="previous chapter">27.8. <tt class="docutils literal docutils literal docutils literal">atexit</tt> &#8212; Exit handlers</a>
 <h4>Next topic</h4>
 <a href="__future__.html"
 title="next chapter">27.10. <tt class="docutils literal docutils literal docutils literal">__future__</tt> &#8212; Future statement definitions</a>
<h3>This Page</h3>
<ul class="this-page-menu">
 <li><a href="../bugs.html">Report a Bug</a></li>
 <li><a href="../_sources/library/traceback.txt"
 rel="nofollow">Show Source</a></li>
</ul>

<div id="searchbox" style="display: none">
 <h3>Quick search</h3>
 <form class="search" action="../search.html" method="get">
 <input type="text" name="q" size="18" />
 <input type="submit" value="Go" />
 <input type="hidden" name="check_keywords" value="yes" />
 <input type="hidden" name="area" value="default" />
 </form>
 
 Enter search terms or a module, class or function name.
 
 </div>
 <script type="text/javascript">$('#searchbox').show(0);</script>
 </div>
 </div>
 <div class="clearer"></div>
 </div>
 <div class="related">
 <h3>Navigation</h3>
 <ul>
 <li class="right" style="margin-right: 10px">
 <a href="../genindex.html" title="General Index"
 >index</a></li>
 <li class="right" >
 <a href="../modindex.html" title="Global Module Index"
 >modules</a> |</li>
 <li class="right" >
 <a href="__future__.html" title="27.10. __future__ — Future statement definitions"
 >next</a> |</li>
 <li class="right" >
 <a href="atexit.html" title="27.8. atexit — Exit handlers"
 >previous</a> |</li>
 <li><img src="../_static/py.png" alt=""
 style="vertical-align: middle; margin-top: -1px"/></li>
 <li><a href="../index.html">Python v2.6.6 documentation</a> &raquo;</li>

<li><a href="index.html" >The Python Standard Library</a> &raquo;</li>
 <li><a href="python.html" >27. Python Runtime Services</a> &raquo;</li> 
 </ul>
 </div>
 <div class="footer">
 &copy; <a href="../copyright.html">Copyright</a> 1990-2011, Python Software Foundation.
 
 The Python Software Foundation is a non-profit corporation. 
 <a href="http://www.python.org/psf/donations/">Please donate.</a>
 
 Last updated on Jul 20, 2011.
 <a href="../bugs.html">Found a bug</a>?
 
 Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.6.
 </div>

</body>
</html>

Back to File Manager