boost/libs/python/doc/v2/lvalue_from_pytype.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2
   3 <!-- Copyright David Abrahams 2006. Distributed under the Boost -->
   4 <!-- Software License, Version 1.0. (See accompanying -->
   5 <!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
   6 <html>
   7   <head>
   8     <meta name="generator" content=
   9     "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org">
  10     <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
  11     <link rel="stylesheet" type="text/css" href="../boost.css">
  12
  13     <title>Boost.Python - &lt;boost/python/lvalue_from_python.hpp&gt;</title>
  14   </head>
  15
  16   <body>
  17     <table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
  18     "header">
  19       <tr>
  20         <td valign="top" width="300">
  21           <h3><a href="../../../../index.htm"><img height="86" width="277"
  22           alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3>
  23         </td>
  24
  25         <td valign="top">
  26           <h1 align="center"><a href="../index.html">Boost.Python</a></h1>
  27
  28           <h2 align="center">Header
  29           &lt;boost/python/lvalue_from_pytype.hpp&gt;</h2>
  30         </td>
  31       </tr>
  32     </table>
  33     <hr>
  34
  35     <h2>Contents</h2>
  36
  37     <dl class="page-index">
  38       <dt><a href="#introduction">Introduction</a></dt>
  39
  40       <dt><a href="#classes">Classes</a></dt>
  41
  42       <dd>
  43         <dl class="page-index">
  44           <dt><a href="#lvalue_from_pytype-spec">Class Template
  45           <code>lvalue_from_pytype</code></a></dt>
  46
  47           <dd>
  48             <dl class="page-index">
  49               <dt><a href="#lvalue_from_pytype-spec-synopsis">Class Template
  50               <code>lvalue_from_pytype</code> synopsis</a></dt>
  51
  52               <dt><a href="#lvalue_from_pytype-spec-ctors">Class Template
  53               <code>lvalue_from_pytype</code> constructor</a></dt>
  54             </dl>
  55           </dd>
  56         </dl>
  57
  58         <dl class="page-index">
  59           <dt><a href="#extract_identity-spec">Class Template
  60           <code>extract_identity</code></a></dt>
  61
  62           <dd>
  63             <dl class="page-index">
  64               <dt><a href="#extract_identity-spec-synopsis">Class Template
  65               <code>extract_identity</code> synopsis</a></dt>
  66
  67               <dt><a href="#extract_identity-spec-statics">Class Template
  68               <code>extract_identity</code> static functions</a></dt>
  69             </dl>
  70           </dd>
  71
  72           <dt><a href="#extract_member-spec">Class Template
  73           <code>extract_member</code></a></dt>
  74
  75           <dd>
  76             <dl class="page-index">
  77               <dt><a href="#extract_member-spec-synopsis">Class Template
  78               <code>extract_member</code> synopsis</a></dt>
  79
  80               <dt><a href="#extract_member-spec-statics">Class Template
  81               <code>extract_member</code> static functions</a></dt>
  82             </dl>
  83           </dd>
  84         </dl>
  85       </dd>
  86
  87       <dt><a href="#examples">Example</a></dt>
  88     </dl>
  89     <hr>
  90
  91     <h2><a name="introduction"></a>Introduction</h2>
  92     <code>&lt;boost/python/lvalue_from_pytype.hpp&gt;</code> supplies a
  93     facility for extracting C++ objects from within Python instances of a
  94     given type. This is typically useful for dealing with "traditional"
  95     Python extension types.
  96
  97     <h2><a name="classes"></a>Classes</h2>
  98
  99     <h3><a name="lvalue_from_pytype-spec"></a>Class template
 100     <code>lvalue_from_pytype</code></h3>
 101
 102     <p>Class template <code>lvalue_from_pytype</code> will register
 103     from_python converters which, given an object of the given Python type,
 104     can extract references and pointers to a particular C++ type. Its
 105     template arguments are:</p>
 106
 107     <table border="1" summary="lvalue_from_pytype template parameters">
 108       <caption>
 109         <b><code>lvalue_from_pytype</code> Requirements</b><br>
 110          In the table below, <b><code>x</code></b> denotes an object of type
 111         <code>PythonObject&amp;</code>
 112       </caption>
 113
 114       <tr>
 115         <th>Parameter</th>
 116
 117         <th>Requirements</th>
 118
 119         <th>Semantics</th>
 120       </tr>
 121
 122       <tr>
 123         <td><code>Extractor</code></td>
 124
 125         <td>a model of <a href=
 126         "Extractor.html#Extractor-concept">Extractor</a> whose execute
 127         function returns a reference type.</td>
 128
 129         <td>Extracts the lvalue from the Python object once its type has been
 130         confirmed</td>
 131       </tr>
 132
 133       <tr>
 134         <td><code>python_type</code></td>
 135
 136         <td>A compile-time constant <code><a href=
 137         "http://www.python.org/doc/2.2/ext/dnt-type-methods.html">PyTypeObject</a>*</code></td>
 138
 139         <td>The Python type of instances convertible by this converter.
 140         Python subtypes are also convertible.</td>
 141       </tr>
 142     </table>
 143
 144     <h4><a name="lvalue_from_pytype-spec-synopsis"></a>Class template
 145     <code>lvalue_from_pytype</code> synopsis</h4>
 146 <pre>
 147 namespace boost { namespace python
 148 {
 149    template &lt;class Extractor, PyTypeObject const* python_type&gt;
 150    struct lvalue_from_pytype
 151    {
 152        lvalue_from_pytype();
 153    };
 154 }}
 155 </pre>
 156
 157     <h4><a name="lvalue_from_pytype-spec-ctors"></a>Class template
 158     <code>lvalue_from_pytype</code> constructor</h4>
 159 <pre>
 160 lvalue_from_pytype();
 161 </pre>
 162
 163     <dl class="function-semantics">
 164       <dt><b>Effects:</b> Registers converters which can convert Python
 165       objects of the given type to lvalues of the type returned by
 166       <code>Extractor::execute</code>.</dt>
 167     </dl>
 168
 169     <h3><a name="extract_identity-spec"></a>Class template
 170     <code>extract_identity</code></h3>
 171
 172     <p><code>extract_identity</code> is a model of <a href=
 173     "Extractor.html#Extractor-concept">Extractor</a> which can be used in the
 174     common case where the C++ type to be extracted is the same as the Python
 175     object type.</p>
 176
 177     <h4><a name="extract_identity-spec-synopsis"></a>Class template
 178     <code>extract_identity</code> synopsis</h4>
 179 <pre>
 180 namespace boost { namespace python
 181 {
 182    template &lt;class InstanceType&gt;
 183    struct extract_identity
 184    {
 185       static InstanceType&amp; execute(InstanceType&amp; c);
 186    };
 187 }}
 188 </pre>
 189
 190     <h4><a name="extract_identity-spec-statics"></a>Class template
 191     <code>extract_identity</code> static functions</h4>
 192 <pre>
 193 InstanceType&amp; execute(InstanceType&amp; c);
 194 </pre>
 195
 196     <dl class="function-semantics">
 197       <dt><b>Returns:</b> <code>c</code></dt>
 198     </dl>
 199
 200     <h3><a name="extract_member-spec"></a>Class template
 201     <code>extract_member</code></h3>
 202
 203     <p><code>extract_member</code> is a model of <a href=
 204     "Extractor.html#Extractor-concept">Extractor</a> which can be used in the
 205     common case in the common case where the C++ type to be extracted is a
 206     member of the Python object.</p>
 207
 208     <h4><a name="extract_member-spec-synopsis"></a>Class template
 209     <code>extract_member</code> synopsis</h4>
 210 <pre>
 211 namespace boost { namespace python
 212 {
 213    template &lt;class InstanceType, class MemberType, MemberType (InstanceType::*member)&gt;
 214    struct extract_member
 215    {
 216       static MemberType&amp; execute(InstanceType&amp; c);
 217    };
 218 }}
 219 </pre>
 220
 221     <h4><a name="extract_member-spec-statics"></a>Class template
 222     <code>extract_member</code> static functions</h4>
 223 <pre>
 224 static MemberType&amp; execute(InstanceType&amp; c);
 225 </pre>
 226
 227     <dl class="function-semantics">
 228       <dt><b>Returns:</b> <code>c.*member</code></dt>
 229     </dl>
 230
 231     <h2><a name="examples"></a>Example</h2>
 232     This example presumes that someone has implemented the standard <a href=
 233     "http://www.python.org/doc/2.2/ext/dnt-basics.html">noddy example
 234     module</a> from the Python documentation, and we want to build a module
 235     which manipulates <code>Noddy</code>s. Since
 236     <code>noddy_NoddyObject</code> is so simple that it carries no
 237     interesting information, the example is a bit contrived: it assumes you
 238     want to keep track of one particular object for some reason. This module
 239     would have to be dynamically linked to the module which defines
 240     <code>noddy_NoddyType</code>.
 241
 242     <h3>C++ module definition</h3>
 243 <pre>
 244 #include &lt;boost/python/module.hpp&gt;
 245 #include &lt;boost/python/handle.hpp&gt;
 246 #include &lt;boost/python/borrowed.hpp&gt;
 247 #include &lt;boost/python/lvalue_from_pytype.hpp&gt;
 248
 249 // definition lifted from the Python docs
 250 typedef struct {
 251    PyObject_HEAD
 252 } noddy_NoddyObject;
 253
 254 using namespace boost::python;
 255 static handle&lt;noddy_NoddyObject&gt; cache;
 256
 257 bool is_cached(noddy_NoddyObject* x)
 258 {
 259    return x == cache.get();
 260 }
 261
 262 void set_cache(noddy_NoddyObject* x)
 263 {
 264    cache = handle&lt;noddy_NoddyObject&gt;(borrowed(x));
 265 }
 266
 267 BOOST_PYTHON_MODULE(noddy_cache)
 268 {
 269    def("is_cached", is_cached);
 270    def("set_cache", set_cache);
 271
 272    // register Noddy lvalue converter
 273    lvalue_from_pytype&lt;extract_identity&lt;noddy_NoddyObject&gt;,&amp;noddy_NoddyType&gt;();
 274 }
 275 </pre>
 276
 277     <h3>Python code</h3>
 278 <pre>
 279 &gt;&gt;&gt; import noddy
 280 &gt;&gt;&gt; n = noddy.new_noddy()
 281 &gt;&gt;&gt; import noddy_cache
 282 &gt;&gt;&gt; noddy_cache.is_cached(n)
 283 0
 284 &gt;&gt;&gt; noddy_cache.set_cache(n)
 285 &gt;&gt;&gt; noddy_cache.is_cached(n)
 286 1
 287 &gt;&gt;&gt; noddy_cache.is_cached(noddy.new_noddy())
 288 0
 289 </pre>
 290
 291     <p>Revised
 292     <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
 293   20 November, 2002
 294   <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
 295     </p>
 296
 297     <p><i>&copy; Copyright <a href=
 298     "../../../../people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p>
 299   </body>
 300 </html>
 301