boost/python
2
0
Fork 0
mirror of https://github.com/boostorg/python.git synced 2026-02-02 21:12:15 +00:00
Code Issues Projects Releases Wiki Activity

initial checkin

Browse Source 
[SVN r12818]
This commit is contained in:
Dave Abrahams
2002-02-15 16:20:22 +00:00
parent 70bb30b95a
commit 4481c3bada
1 changed files with 278 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

278
doc/v2/lvalue_from_python.html Normal file
View File

@@ -0,0 +1,278 @@
<!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 - &lt;boost/python/lvalue_from_python.hpp&gt;</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 &lt;boost/python/lvalue_from_python.hpp&gt;</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>&lt;boost/python/lvalue_from_python.hpp&gt;</code> supplies
a facility for extracting C++ objects from within instances of a
given Python type. This is typically useful for dealing with
&quot;traditional&quot; 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&amp;</code>
</caption>
<tr>
<th>Parameter
<th>Requirements
<th>Description
<th>Default
<tr>
<td><code>python_type</code>
<td>A compile-time constant PyTypeObject*
<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&amp; 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&nbsp;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 &lt;
PyTypeObject const* python_type
, class Value
, class PythonObject = Value
, class Extract = <i>unspecified</i>
&gt;
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&amp;</code>, <code>Value const&amp;</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 &lt;class Class, class Member, Member (Class::*mp)&gt;
struct get_member
{
static Member&amp; execute(Class&amp; c);
};
}}
</pre>
<h4><a name="get_member-spec-statics"></a>Class template <code>get_member</code> static functions</h4>
<pre>
Member&amp; execute(Class&amp; c);
</pre>
<dl class="function-semantics">
<dt><b>Returns:</b> <code>c.*mp</code>
</dl>
<h2><a name="examples"></a>Example(s)</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 &lt;boost/python/reference.hpp&gt;
#include &lt;boost/python/module.hpp&gt;
// 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(&quot;noddy_cache&quot;)
.def(&quot;is_cached&quot;, is_cached)
.def(&quot;set_cache&quot;, set_cache)
;
}
</pre>
<h3>Python code</h3>
<pre>
&gt;&gt;&gt; import noddy
&gt;&gt;&gt; n = noddy.new_noddy()
&gt;&gt;&gt; import noddy_cache
&gt;&gt;&gt; noddy_cache.is_cached(n)
0
&gt;&gt;&gt; noddy_cache.set_cache(n)
&gt;&gt;&gt; noddy_cache.is_cached(n)
1
&gt;&gt;&gt; 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>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave
Abrahams</a> 2002. All Rights Reserved.</i>