mirror of
https://github.com/boostorg/python.git
synced 2026-01-19 16:32:16 +00:00
233 lines
7.5 KiB
HTML
233 lines
7.5 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<meta name="generator" content="HTML Tidy, see www.w3.org">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<link rel="stylesheet" type="text/css" href="../boost.css">
|
|
|
|
<title>Boost.Python - <{{header}}></title>
|
|
|
|
<table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
|
|
"header">
|
|
<tr>
|
|
<td valign="top" width="300">
|
|
<h3><a href="../../../../index.htm"><img height="86" width="277" alt=
|
|
"C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
|
|
|
|
<td valign="top">
|
|
<h1 align="center">Boost.Python</h1>
|
|
|
|
<h2 align="center">Header <boost/python/errors.hpp></h2>
|
|
</table>
|
|
<hr>
|
|
|
|
<h2>Contents</h2>
|
|
|
|
<dl class="page-index">
|
|
<dt><a href="#introduction">Introduction</a>
|
|
|
|
<dt><a href="#classes">Classes</a>
|
|
|
|
<dd>
|
|
<dl class="page-index">
|
|
<dt><a href="#class-spec">Class <code>error_already_set</code></a>
|
|
|
|
<dd>
|
|
<dl class="page-index">
|
|
<dt><a href="#error_already_set-spec-synopsis">Class
|
|
<code>error_already_set</code> synopsis</a>
|
|
</dl>
|
|
</dl>
|
|
|
|
<dt><a href="#functions">Functions</a>
|
|
|
|
<dd>
|
|
<dl class="page-index">
|
|
<dt><a href="#handle_exception-spec">handle_exception</a>
|
|
|
|
<dt><a href="#expect_non_null-spec">expect_non_null</a>
|
|
</dl>
|
|
|
|
<dt><a href="#examples">Examples</a>
|
|
</dl>
|
|
<hr>
|
|
|
|
<h2><a name="introduction"></a>Introduction</h2>
|
|
|
|
<p><code><boost/python/errors.hpp></code> provides types and
|
|
functions for managing and translating between Python and C++ exceptions.
|
|
This is relatively low-level functionality that is mostly used internally
|
|
by Boost.Python. Users should seldom need it.
|
|
|
|
<h2><a name="classes"></a>Classes</h2>
|
|
|
|
<h3><a name="error_already_set-spec"></a>Class
|
|
<code>error_already_set</code></h3>
|
|
|
|
<p><code>error_already_set</code> is an exception type which can be thrown
|
|
to indicate that a Python error has occurred. If thrown, the precondition
|
|
is that <a href=
|
|
"http://www.python.org/doc/2.2/api/exceptionHandling.html#l2h-71">PyErr_Occurred()</a>
|
|
returns a value convertible to <code>true</code>.
|
|
|
|
<h4><a name="class-spec-synopsis"></a>Class error_already_set synopsis</h4>
|
|
<pre>
|
|
namespace boost { namespace python
|
|
{
|
|
class error_already_set {};
|
|
}}
|
|
</pre>
|
|
|
|
<h2><a name="functions"></a>Functions</h2>
|
|
<pre>
|
|
<a name=
|
|
"handle_exception-spec">template <class T> bool handle_exception</a>(T f) throw();
|
|
|
|
void handle_exception() throw();
|
|
</pre>
|
|
|
|
<dl class="handle_exception-semantics">
|
|
<dt><b>Requires:</b> The first form requires that the expression <code><a
|
|
href=
|
|
"../../../function/doc/reference.html#functionN">function0</a><void>(f)</code>
|
|
is valid. The second form requires that a C++ exception is currently
|
|
being handled (see section 15.1 in the C++ standard).
|
|
|
|
<dt><b>Effects:</b> The first form calls <code>f()</code> inside a
|
|
<code>try</code> block whose <code>catch</code> clauses set an
|
|
appropriate Python exception for the C++ exception caught, returning
|
|
<code>true</code> if an exception was caught, <code>false</code>
|
|
otherwise. The second form passes a function which rethrows the exception
|
|
currently being handled to the first form.
|
|
|
|
<dt><b>Postconditions:</b> No exception is being handled
|
|
|
|
<dt><b>Throws:</b> nothing
|
|
|
|
<dt><b>Rationale:</b> At inter-language boundaries it is important to
|
|
ensure that no C++ exceptions escape, since the calling language usually
|
|
doesn't have the equipment neccessary to properly unwind the stack. Use
|
|
<code>handle_exception</code> to manage exception translation whenever
|
|
your C++ code is called directly from the Python API. This is done for
|
|
you automatically by the usual function wrapping facilities: <a href=
|
|
"make_function.html#make_function-spec">make_function()</a>, <a href=
|
|
"make_function.html#make_constructor-spec">make_constructor()</a>, <a
|
|
href="module.html#def-spec">module::def</a> and <a href=
|
|
"class.html#def-spec">class_::def</a>). The second form can be more
|
|
convenient to use (see the <a href="#examples">example</a> below), but
|
|
various compilers have problems when exceptions are rethrown from within
|
|
an enclosing <code>try</code> block.
|
|
</dl>
|
|
<pre>
|
|
<a name="expect_non_null-spec">PyObject* expect_non_null(PyObject* x);</a>
|
|
|
|
template <class T> T* expect_non_null(T* x);
|
|
</pre>
|
|
|
|
<dl class="expect_non_null-semantics">
|
|
<dt><b>Returns:</b> <code>x</code>
|
|
|
|
<dt><b>Throws:</b> <code><a href=
|
|
"#error_already_set-spec">error_already_set()</a></code> iff <code>x ==
|
|
0</code>.
|
|
|
|
<dt><b>Rationale:</b> Simplifies error-handling when calling many
|
|
functions in the <a href=
|
|
"http://www.python.org/doc/2.2/api/api.html">Python/C API</a>, which
|
|
return 0 on error.
|
|
</dl>
|
|
|
|
<h2><a name="examples"></a>Examples</h2>
|
|
<pre>
|
|
#include <string>
|
|
#include <boost/python/errors.hpp>
|
|
#include <boost/python/reference.hpp>
|
|
|
|
// Returns a std::string which has the same value as obj's "__name__"
|
|
// attribute.
|
|
std::string get_name(boost::python::ref obj)
|
|
{
|
|
// throws if there's no __name__ attribute
|
|
PyObject* p = boost::python::expect_non_null(
|
|
PyObject_GetAttrString(obj.get(), "__name__"));
|
|
|
|
// throws if it's not a Python string
|
|
std::string result(
|
|
boost::python::expect_non_null(
|
|
PyString_AsString(p)));
|
|
|
|
Py_XDECREF(p); // Done with p
|
|
|
|
return result;
|
|
}
|
|
|
|
//
|
|
// Demonstrate form 1 of handle_exception
|
|
//
|
|
|
|
// Place a Python Int object whose value is 1 if a and b have
|
|
// identical "__name__" attributes, 0 otherwise.
|
|
void same_name_impl(PyObject*& result, PyObject* a, PyObject* b)
|
|
{
|
|
result = PyInt_FromLong(
|
|
get_name(boost::python::ref(a1)) == get_name(boost::python::ref(a2)));
|
|
}
|
|
|
|
// This is an example Python 'C' API interface function
|
|
extern "C" PyObject*
|
|
same_name(PyObject* args, PyObject* keywords)
|
|
{
|
|
PyObject* a1;
|
|
PyObject* a2;
|
|
PyObject* result = 0;
|
|
|
|
if (!PyArg_ParseTuple(args, const_cast<char*>("OO"), &a1, &a2))
|
|
return 0;
|
|
|
|
// Use boost::bind to make an object compatible with
|
|
// boost::Function0<void>
|
|
if (boost::python::handle_exception(
|
|
boost::bind<void>(same_name_impl, boost::ref(result), a1, a2)))
|
|
{
|
|
// an exception was thrown; the Python error was set by
|
|
// handle_exception()
|
|
return 0;
|
|
}
|
|
|
|
return result;
|
|
}
|
|
|
|
//
|
|
// Demonstrate form 2 of handle_exception. Not well-supported by all
|
|
// compilers.
|
|
//
|
|
extern "C" PyObject*
|
|
same_name2(PyObject* args, PyObject* keywords)
|
|
{
|
|
PyObject* a1;
|
|
PyObject* a2;
|
|
PyObject* result = 0;
|
|
|
|
if (!PyArg_ParseTuple(args, const_cast<char*>("OO"), &a1, &a2))
|
|
return 0;
|
|
try {
|
|
return PyInt_FromLong(
|
|
get_name(boost::python::ref(a1)) == get_name(boost::python::ref(a2)));
|
|
}
|
|
catch(...)
|
|
{
|
|
// If an exception was thrown, translate it to Python
|
|
boost::python::handle_exception();
|
|
return 0;
|
|
}
|
|
}
|
|
</pre>
|
|
|
|
<p>Revised
|
|
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
|
|
05 November, 2001
|
|
<!--webbot bot="Timestamp" endspan i-checksum="39359" -->
|
|
|
|
|
|
<p><i>© Copyright <a href="../../../../people/dave_abrahams.htm">Dave
|
|
Abrahams</a> 2002. All Rights Reserved.</i>
|
|
|