<!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>Exception Handling — Python v2.7 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.7',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python v2.7 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.7 documentation" href="../index.html" />
<link rel="up" title="Python/C API Reference Manual" href="index.html" />
<link rel="next" title="Utilities" href="utilities.html" />
<link rel="prev" title="Reference Counting" href="refcounting.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="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="utilities.html" title="Utilities"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="refcounting.html" title="Reference Counting"
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.7 documentation</a> »</li>
<li><a href="index.html" accesskey="U">Python/C API Reference Manual</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="exception-handling">
<span id="exceptionhandling"></span><h1>Exception Handling<a class="headerlink" href="#exception-handling" title="Permalink to this headline">¶</a></h1>
<p>The functions described in this chapter will let you handle and raise Python
exceptions. It is important to understand some of the basics of Python
exception handling. It works somewhat like the Unix <a href="#id1"><span class="problematic" id="id2">:cdata:`errno`</span></a> variable:
there is a global indicator (per thread) of the last error that occurred. Most
functions don’t clear this on success, but will set it to indicate the cause of
the error on failure. Most functions also return an error indicator, usually
<em>NULL</em> if they are supposed to return a pointer, or <tt class="docutils literal"><span class="pre">-1</span></tt> if they return an
integer (exception: the <a href="#id3"><span class="problematic" id="id4">:cfunc:`PyArg_\*`</span></a> functions return <tt class="docutils literal"><span class="pre">1</span></tt> for success and
<tt class="docutils literal"><span class="pre">0</span></tt> for failure).</p>
<p>When a function must fail because some function it called failed, it generally
doesn’t set the error indicator; the function it called already set it. It is
responsible for either handling the error and clearing the exception or
returning after cleaning up any resources it holds (such as object references or
memory allocations); it should <em>not</em> continue normally if it is not prepared to
handle the error. If returning due to an error, it is important to indicate to
the caller that an error has been set. If the error is not handled or carefully
propagated, additional calls into the Python/C API may not behave as intended
and may fail in mysterious ways.</p>
<p id="index-0">The error indicator consists of three Python objects corresponding to the
Python variables <tt class="docutils literal"><span class="pre">sys.exc_type</span></tt>, <tt class="docutils literal"><span class="pre">sys.exc_value</span></tt> and <tt class="docutils literal"><span class="pre">sys.exc_traceback</span></tt>.
API functions exist to interact with the error indicator in various ways. There
is a separate error indicator for each thread.</p>
<div class="section" id="recursion-control">
<h2>Recursion Control<a class="headerlink" href="#recursion-control" title="Permalink to this headline">¶</a></h2>
<p>These two functions provide a way to perform safe recursive calls at the C
level, both in the core and in extension modules. They are needed if the
recursive code does not necessarily invoke Python code (which tracks its
recursion depth automatically).</p>
</div>
<div class="section" id="standard-exceptions">
<span id="standardexceptions"></span><h2>Standard Exceptions<a class="headerlink" href="#standard-exceptions" title="Permalink to this headline">¶</a></h2>
<p>All standard Python exceptions are available as global variables whose names are
<tt class="docutils literal"><span class="pre">PyExc_</span></tt> followed by the Python exception name. These have the type
<a href="#id5"><span class="problematic" id="id6">:ctype:`PyObject\*`</span></a>; they are all class objects. For completeness, here are all
the variables:</p>
<table border="1" class="docutils">
<colgroup>
<col width="49%" />
<col width="38%" />
<col width="14%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">C Name</th>
<th class="head">Python Name</th>
<th class="head">Notes</th>
</tr>
</thead>
<tbody valign="top">
<tr><td><a href="#id7"><span class="problematic" id="id8">:cdata:`PyExc_BaseException`</span></a></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.BaseException" title="exceptions.BaseException"><tt class="xref py py-exc docutils literal"><span class="pre">BaseException</span></tt></a></td>
<td>(1), (4)</td>
</tr>
<tr><td><a href="#id9"><span class="problematic" id="id10">:cdata:`PyExc_Exception`</span></a></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.Exception" title="exceptions.Exception"><tt class="xref py py-exc docutils literal"><span class="pre">Exception</span></tt></a></td>
<td>(1)</td>
</tr>
<tr><td><a href="#id11"><span class="problematic" id="id12">:cdata:`PyExc_StandardError`</span></a></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.StandardError" title="exceptions.StandardError"><tt class="xref py py-exc docutils literal"><span class="pre">StandardError</span></tt></a></td>
<td>(1)</td>
</tr>
<tr><td><a href="#id13"><span class="problematic" id="id14">:cdata:`PyExc_ArithmeticError`</span></a></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.ArithmeticError" title="exceptions.ArithmeticError"><tt class="xref py py-exc docutils literal"><span class="pre">ArithmeticError</span></tt></a></td>
<td>(1)</td>
</tr>
<tr><td><a href="#id15"><span class="problematic" id="id16">:cdata:`PyExc_LookupError`</span></a></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.LookupError" title="exceptions.LookupError"><tt class="xref py py-exc docutils literal"><span class="pre">LookupError</span></tt></a></td>
<td>(1)</td>
</tr>
<tr><td><a href="#id17"><span class="problematic" id="id18">:cdata:`PyExc_AssertionError`</span></a></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.AssertionError" title="exceptions.AssertionError"><tt class="xref py py-exc docutils literal"><span class="pre">AssertionError</span></tt></a></td>
<td> </td>
</tr>
<tr><td><a href="#id19"><span class="problematic" id="id20">:cdata:`PyExc_AttributeError`</span></a></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.AttributeError" title="exceptions.AttributeError"><tt class="xref py py-exc docutils literal"><span class="pre">AttributeError</span></tt></a></td>
<td> </td>
</tr>
<tr><td><a href="#id21"><span class="problematic" id="id22">:cdata:`PyExc_EOFError`</span></a></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.EOFError" title="exceptions.EOFError"><tt class="xref py py-exc docutils literal"><span class="pre">EOFError</span></tt></a></td>
<td> </td>
</tr>
<tr><td><a href="#id23"><span class="problematic" id="id24">:cdata:`PyExc_EnvironmentError`</span></a></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.EnvironmentError" title="exceptions.EnvironmentError"><tt class="xref py py-exc docutils literal"><span class="pre">EnvironmentError</span></tt></a></td>
<td>(1)</td>
</tr>
<tr><td><a href="#id25"><span class="problematic" id="id26">:cdata:`PyExc_FloatingPointError`</span></a></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.FloatingPointError" title="exceptions.FloatingPointError"><tt class="xref py py-exc docutils literal"><span class="pre">FloatingPointError</span></tt></a></td>
<td> </td>
</tr>
<tr><td><a href="#id27"><span class="problematic" id="id28">:cdata:`PyExc_IOError`</span></a></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.IOError" title="exceptions.IOError"><tt class="xref py py-exc docutils literal"><span class="pre">IOError</span></tt></a></td>
<td> </td>
</tr>
<tr><td><a href="#id29"><span class="problematic" id="id30">:cdata:`PyExc_ImportError`</span></a></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.ImportError" title="exceptions.ImportError"><tt class="xref py py-exc docutils literal"><span class="pre">ImportError</span></tt></a></td>
<td> </td>
</tr>
<tr><td><a href="#id31"><span class="problematic" id="id32">:cdata:`PyExc_IndexError`</span></a></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.IndexError" title="exceptions.IndexError"><tt class="xref py py-exc docutils literal"><span class="pre">IndexError</span></tt></a></td>
<td> </td>
</tr>
<tr><td><a href="#id33"><span class="problematic" id="id34">:cdata:`PyExc_KeyError`</span></a></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.KeyError" title="exceptions.KeyError"><tt class="xref py py-exc docutils literal"><span class="pre">KeyError</span></tt></a></td>
<td> </td>
</tr>
<tr><td><a href="#id35"><span class="problematic" id="id36">:cdata:`PyExc_KeyboardInterrupt`</span></a></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.KeyboardInterrupt" title="exceptions.KeyboardInterrupt"><tt class="xref py py-exc docutils literal"><span class="pre">KeyboardInterrupt</span></tt></a></td>
<td> </td>
</tr>
<tr><td><a href="#id37"><span class="problematic" id="id38">:cdata:`PyExc_MemoryError`</span></a></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.MemoryError" title="exceptions.MemoryError"><tt class="xref py py-exc docutils literal"><span class="pre">MemoryError</span></tt></a></td>
<td> </td>
</tr>
<tr><td><a href="#id39"><span class="problematic" id="id40">:cdata:`PyExc_NameError`</span></a></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.NameError" title="exceptions.NameError"><tt class="xref py py-exc docutils literal"><span class="pre">NameError</span></tt></a></td>
<td> </td>
</tr>
<tr><td><a href="#id41"><span class="problematic" id="id42">:cdata:`PyExc_NotImplementedError`</span></a></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.NotImplementedError" title="exceptions.NotImplementedError"><tt class="xref py py-exc docutils literal"><span class="pre">NotImplementedError</span></tt></a></td>
<td> </td>
</tr>
<tr><td><a href="#id43"><span class="problematic" id="id44">:cdata:`PyExc_OSError`</span></a></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.OSError" title="exceptions.OSError"><tt class="xref py py-exc docutils literal"><span class="pre">OSError</span></tt></a></td>
<td> </td>
</tr>
<tr><td><a href="#id45"><span class="problematic" id="id46">:cdata:`PyExc_OverflowError`</span></a></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.OverflowError" title="exceptions.OverflowError"><tt class="xref py py-exc docutils literal"><span class="pre">OverflowError</span></tt></a></td>
<td> </td>
</tr>
<tr><td><a href="#id47"><span class="problematic" id="id48">:cdata:`PyExc_ReferenceError`</span></a></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.ReferenceError" title="exceptions.ReferenceError"><tt class="xref py py-exc docutils literal"><span class="pre">ReferenceError</span></tt></a></td>
<td>(2)</td>
</tr>
<tr><td><a href="#id49"><span class="problematic" id="id50">:cdata:`PyExc_RuntimeError`</span></a></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.RuntimeError" title="exceptions.RuntimeError"><tt class="xref py py-exc docutils literal"><span class="pre">RuntimeError</span></tt></a></td>
<td> </td>
</tr>
<tr><td><a href="#id51"><span class="problematic" id="id52">:cdata:`PyExc_SyntaxError`</span></a></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.SyntaxError" title="exceptions.SyntaxError"><tt class="xref py py-exc docutils literal"><span class="pre">SyntaxError</span></tt></a></td>
<td> </td>
</tr>
<tr><td><a href="#id53"><span class="problematic" id="id54">:cdata:`PyExc_SystemError`</span></a></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.SystemError" title="exceptions.SystemError"><tt class="xref py py-exc docutils literal"><span class="pre">SystemError</span></tt></a></td>
<td> </td>
</tr>
<tr><td><a href="#id55"><span class="problematic" id="id56">:cdata:`PyExc_SystemExit`</span></a></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.SystemExit" title="exceptions.SystemExit"><tt class="xref py py-exc docutils literal"><span class="pre">SystemExit</span></tt></a></td>
<td> </td>
</tr>
<tr><td><a href="#id57"><span class="problematic" id="id58">:cdata:`PyExc_TypeError`</span></a></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><tt class="xref py py-exc docutils literal"><span class="pre">TypeError</span></tt></a></td>
<td> </td>
</tr>
<tr><td><a href="#id59"><span class="problematic" id="id60">:cdata:`PyExc_ValueError`</span></a></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.ValueError" title="exceptions.ValueError"><tt class="xref py py-exc docutils literal"><span class="pre">ValueError</span></tt></a></td>
<td> </td>
</tr>
<tr><td><a href="#id61"><span class="problematic" id="id62">:cdata:`PyExc_WindowsError`</span></a></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.WindowsError" title="exceptions.WindowsError"><tt class="xref py py-exc docutils literal"><span class="pre">WindowsError</span></tt></a></td>
<td>(3)</td>
</tr>
<tr><td><a href="#id63"><span class="problematic" id="id64">:cdata:`PyExc_ZeroDivisionError`</span></a></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.ZeroDivisionError" title="exceptions.ZeroDivisionError"><tt class="xref py py-exc docutils literal"><span class="pre">ZeroDivisionError</span></tt></a></td>
<td> </td>
</tr>
</tbody>
</table>
<p id="index-1">Notes:</p>
<ol class="arabic">
<li><p class="first">This is a base class for other standard exceptions.</p>
</li>
<li><p class="first">This is the same as <a class="reference internal" href="../library/weakref.html#weakref.ReferenceError" title="weakref.ReferenceError"><tt class="xref py py-exc docutils literal"><span class="pre">weakref.ReferenceError</span></tt></a>.</p>
</li>
<li><p class="first">Only defined on Windows; protect code that uses this by testing that the
preprocessor macro <tt class="docutils literal"><span class="pre">MS_WINDOWS</span></tt> is defined.</p>
</li>
<li><p class="first versionadded">
<span class="versionmodified">New in version 2.5.</span></p>
</li>
</ol>
</div>
<div class="section" id="deprecation-of-string-exceptions">
<h2>Deprecation of String Exceptions<a class="headerlink" href="#deprecation-of-string-exceptions" title="Permalink to this headline">¶</a></h2>
<p id="index-2">All exceptions built into Python or provided in the standard library are derived
from <a class="reference internal" href="../library/exceptions.html#exceptions.BaseException" title="exceptions.BaseException"><tt class="xref py py-exc docutils literal"><span class="pre">BaseException</span></tt></a>.</p>
<p>String exceptions are still supported in the interpreter to allow existing code
to run unmodified, but this will also change in a future release.</p>
</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 internal" href="#">Exception Handling</a><ul>
<li><a class="reference internal" href="#recursion-control">Recursion Control</a></li>
<li><a class="reference internal" href="#standard-exceptions">Standard Exceptions</a></li>
<li><a class="reference internal" href="#deprecation-of-string-exceptions">Deprecation of String Exceptions</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="refcounting.html"
title="previous chapter">Reference Counting</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="utilities.html"
title="next chapter">Utilities</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">Report a Bug</a></li>
<li><a href="../_sources/c-api/exceptions.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>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</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="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="utilities.html" title="Utilities"
>next</a> |</li>
<li class="right" >
<a href="refcounting.html" title="Reference Counting"
>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.7 documentation</a> »</li>
<li><a href="index.html" >Python/C API Reference Manual</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2010, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="http://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Aug 09, 2010.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0b2.
</div>
</body>
</html>
