mirror of
https://github.com/boostorg/python.git
synced 2026-01-21 17:12:22 +00:00
280 lines
8.1 KiB
HTML
280 lines
8.1 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 - <boost/python/lvalue_from_python.hpp></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/lvalue_from_python.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="#lvalue_from_python-spec">Class Template <code>lvalue_from_python</code></a>
|
|
|
|
<dd>
|
|
<dl class="page-index">
|
|
|
|
<dt><a href="#lvalue_from_python-spec-synopsis">Class Template
|
|
<code>lvalue_from_python</code> synopsis</a>
|
|
|
|
<dt><a href="#lvalue_from_python-spec-ctors">Class Template
|
|
<code>lvalue_from_python</code> constructor</a>
|
|
</dl>
|
|
</dl>
|
|
|
|
<dl class="page-index">
|
|
<dt><a href="#get_member-spec">Class Template <code>get_member</code></a>
|
|
|
|
<dd>
|
|
<dl class="page-index">
|
|
|
|
<dt><a href="#get_member-spec-synopsis">Class Template
|
|
<code>get_member</code> synopsis</a>
|
|
|
|
<dt><a href="#get_member-spec-statics">Class Template
|
|
<code>get_member</code> static functions</a>
|
|
</dl>
|
|
</dl>
|
|
|
|
<dt><a href="#examples">Example</a>
|
|
</dl>
|
|
<hr>
|
|
|
|
<h2><a name="introduction"></a>Introduction</h2>
|
|
|
|
<code><boost/python/lvalue_from_python.hpp></code> supplies
|
|
a facility for extracting C++ objects from within instances of a
|
|
given Python type. This is typically useful for dealing with
|
|
"traditional" Python extension types.
|
|
|
|
<h2><a name="classes"></a>Classes</h2>
|
|
|
|
<h3><a name="lvalue_from_python-spec"></a>Class template <code>lvalue_from_python</code></h3>
|
|
|
|
<p>Class template <code>lvalue_from_python</code> will register
|
|
from_python converters which extract a references and pointers to
|
|
a C++ type which is held within an object of a given Python
|
|
type. Its template arguments are:
|
|
|
|
<p>
|
|
|
|
|
|
<table border="1" summary="lvalue_from_python template parameters">
|
|
<caption>
|
|
<b><code>lvalue_from_python</code> Requirements</b><br>
|
|
|
|
In the table below, <b><code>x</code></b> denotes an object of type <code>PythonObject&</code>
|
|
|
|
</caption>
|
|
<tr>
|
|
<th>Parameter
|
|
|
|
<th>Requirements
|
|
|
|
<th>Description
|
|
|
|
<th>Default
|
|
|
|
<tr>
|
|
<td><code>python_type</code>
|
|
|
|
<td>A compile-time constant <code><a
|
|
href="http://www.python.org/doc/current/ext/dnt-type-methods.html">PyTypeObject</a>*</code>
|
|
|
|
<td>The Python type of instances convertible by this
|
|
converter. Python subtypes are also convertible.
|
|
|
|
<tr>
|
|
<td><code>Value</code>
|
|
|
|
<td>A non-reference type.
|
|
|
|
<td>The C++ type to be extracted
|
|
|
|
<tr>
|
|
<td><code>PythonObject</code>
|
|
|
|
<td>initial <code>sizeof(PyObject)</code> bytes are
|
|
layout-compatible with <code>PyObject</code>.
|
|
|
|
<td>The C++ type used to hold Python instances of
|
|
<code>python_type</code>.
|
|
|
|
<td><code>Value</code>
|
|
|
|
<tr>
|
|
<td><code>Extract</code>
|
|
|
|
<td><code>Value& v = Extract::execute(x);</code>
|
|
|
|
<td>A type whose static <code>execute</code> function extracts a <code>Value</code> reference from within an object of type <code>PythonObject</code>.
|
|
|
|
<td>An unspecified type whose <code>execute</code> function consists of <code>return x;</code>
|
|
</table>
|
|
|
|
If only the first two template arguments are supplied, these
|
|
converters extract the entire <code>PythonObject</code> as a
|
|
whole.
|
|
|
|
<p>
|
|
|
|
If the lifetime of the <code>lvalue_from_python</code> object ends
|
|
before the last attempt to convert to one its target types, the
|
|
behavior is undefined. The easiest way to ensure correct behavior
|
|
is to declare an <code>lvalue_from_python</code> instance as a
|
|
static local in a <a
|
|
href="module.html#BOOST_PYTHON_MODULE_INIT-spec">module init
|
|
function</a>, as shown in the <a href="#examples">example</a>
|
|
below.
|
|
|
|
<h4><a name="lvalue_from_python-spec-synopsis"></a>Class template <code>lvalue_from_python</code> synopsis</h4>
|
|
<pre>
|
|
namespace boost { namespace python
|
|
{
|
|
template <
|
|
PyTypeObject const* python_type
|
|
, class Value
|
|
, class PythonObject = Value
|
|
, class Extract = <i>unspecified</i>
|
|
>
|
|
class lvalue_from_python
|
|
{
|
|
lvalue_from_python();
|
|
};
|
|
}}
|
|
</pre>
|
|
|
|
<h4><a name="lvalue_from_python-spec-ctors"></a>Class template <code>lvalue_from_python</code> constructor</h4>
|
|
<pre>
|
|
lvalue_from_python();
|
|
</pre>
|
|
|
|
<dl class="function-semantics">
|
|
|
|
<dt><b>Effects:</b> Registers from_python converters which
|
|
extract
|
|
<code>Value&</code>, <code>Value const&</code>,
|
|
<code>Value*</code>, or <code>Value const*</code> from Python
|
|
objects of type <code>python_type</code> using
|
|
<code>Extract::execute()</code>.
|
|
|
|
</dl>
|
|
|
|
<h3><a name="get_member-spec"></a>Class template <code>get_member</code></h3>
|
|
|
|
<p><code>get_member</code> can be used with
|
|
<code>lvalue_from_python</code> in the common case where the C++
|
|
type to be extracted is a member of the Python object.
|
|
|
|
<h4><a name="get_member-spec-synopsis"></a>Class template <code>get_member</code> synopsis</h4>
|
|
<pre>
|
|
namespace boost { namespace python
|
|
{
|
|
template <class Class, class Member, Member (Class::*mp)>
|
|
struct get_member
|
|
{
|
|
static Member& execute(Class& c);
|
|
};
|
|
}}
|
|
</pre>
|
|
|
|
<h4><a name="get_member-spec-statics"></a>Class template <code>get_member</code> static functions</h4>
|
|
<pre>
|
|
Member& execute(Class& c);
|
|
</pre>
|
|
|
|
<dl class="function-semantics">
|
|
|
|
<dt><b>Returns:</b> <code>c.*mp</code>
|
|
|
|
</dl>
|
|
|
|
|
|
<h2><a name="examples"></a>Example</h2>
|
|
|
|
This example presumes that someone has implemented the standard <a
|
|
href="http://www.python.org/doc/current/ext/dnt-basics.html">noddy
|
|
example module</a> from the Python documentation, and we want to build
|
|
a module which manipulates <code>Noddy</code>s. Since
|
|
<code>noddy_NoddyObject</code> is so simple that it carries no
|
|
interesting information, the example is a bit contrived: it assumes
|
|
you want to keep track of one particular object for some reason.
|
|
|
|
<h3>C++ module definition</h3>
|
|
|
|
<pre>
|
|
#include <boost/python/reference.hpp>
|
|
#include <boost/python/module.hpp>
|
|
|
|
// definition lifted from the Python docs
|
|
typedef struct {
|
|
PyObject_HEAD
|
|
} noddy_NoddyObject;
|
|
|
|
using namespace boost::python;
|
|
static ref cache;
|
|
|
|
bool is_cached(noddy_NoddyObject* x)
|
|
{
|
|
return x == cache.get();
|
|
}
|
|
|
|
void set_cache(noddy_NoddyObject* x)
|
|
{
|
|
cache.reset((PyObject*)x, ref::increment_count);
|
|
}
|
|
|
|
BOOST_PYTHON_MODULE_INIT(noddy_cache)
|
|
{
|
|
module noddy_cache("noddy_cache")
|
|
.def("is_cached", is_cached)
|
|
.def("set_cache", set_cache)
|
|
;
|
|
}
|
|
</pre>
|
|
|
|
<h3>Python code</h3>
|
|
|
|
<pre>
|
|
>>> import noddy
|
|
>>> n = noddy.new_noddy()
|
|
>>> import noddy_cache
|
|
>>> noddy_cache.is_cached(n)
|
|
0
|
|
>>> noddy_cache.set_cache(n)
|
|
>>> noddy_cache.is_cached(n)
|
|
1
|
|
>>> noddy_cache.is_cached(noddy.new_noddy())
|
|
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>
|
|
|