1 [section boost/python/lvalue_from_pytype.hpp]
3 <boost/python/lvalue_from_pytype.hpp> supplies a facility for extracting C++ objects from within Python instances of a given type. This is typically useful for dealing with "traditional" Python extension types.
5 [section Class template `lvalue_from_pytype`]
6 Class template lvalue_from_pytype will register from_python converters which, given an object of the given Python type, can extract references and pointers to a particular C++ type. Its template arguments are:
8 In the table below, x denotes an object of type PythonObject&
10 [[Parameter][Requirements][Semantics]]
11 [[Extractor][a model of [link concepts.extractor `Extractor`] whose execute function returns a reference type.][Extracts the lvalue from the Python object once its type has been confirmed]]
12 [[python_type][A compile-time constant [@http://www.python.org/doc/2.2/ext/dnt-type-methods.html `PyTypeObject*`]][The Python type of instances convertible by this converter. Python subtypes are also convertible.]]
15 namespace boost { namespace python
17 template <class Extractor, PyTypeObject const* python_type>
18 struct lvalue_from_pytype
24 [section Class template `lvalue_from_pytype` constructor]
25 ``lvalue_from_pytype();``
27 [[Effects][Registers converters which can convert Python objects of the given type to lvalues of the type returned by Extractor::execute.]]
31 [section Class template `extract_identity`]
32 extract_identity is a model of [link concepts.extractor `Extractor`] which can be used in the common case where the C++ type to be extracted is the same as the Python object type.
34 namespace boost { namespace python
36 template <class InstanceType>
37 struct extract_identity
39 static InstanceType& execute(InstanceType& c);
43 [section Class template `extract_identity` static functions]
44 ``InstanceType& execute(InstanceType& c);``
50 [section Class template `extract_member`]
51 `extract_member` is a model of [link concepts.extractor `Extractor`] which can be used in the common case in the common case where the C++ type to be extracted is a member of the Python object.
53 namespace boost { namespace python
55 template <class InstanceType, class MemberType, MemberType (InstanceType::*member)>
58 static MemberType& execute(InstanceType& c);
62 [section Class template `extract_member` static functions]
63 ``static MemberType& execute(InstanceType& c);``
65 [[Returns][`c.*member`]]
70 This example presumes that someone has implemented the standard noddy example module from the Python documentation, and we want to build a module which manipulates Noddys. Since noddy_NoddyObject 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. This module would have to be dynamically linked to the module which defines noddy_NoddyType.
74 #include <boost/python/module.hpp>
75 #include <boost/python/handle.hpp>
76 #include <boost/python/borrowed.hpp>
77 #include <boost/python/lvalue_from_pytype.hpp>
79 // definition lifted from the Python docs
84 using namespace boost::python;
85 static handle<noddy_NoddyObject> cache;
87 bool is_cached(noddy_NoddyObject* x)
89 return x == cache.get();
92 void set_cache(noddy_NoddyObject* x)
94 cache = handle<noddy_NoddyObject>(borrowed(x));
97 BOOST_PYTHON_MODULE(noddy_cache)
99 def("is_cached", is_cached);
100 def("set_cache", set_cache);
102 // register Noddy lvalue converter
103 lvalue_from_pytype<extract_identity<noddy_NoddyObject>,&noddy_NoddyType>();
109 >>> n = noddy.new_noddy()
110 >>> import noddy_cache
111 >>> noddy_cache.is_cached(n)
113 >>> noddy_cache.set_cache(n)
114 >>> noddy_cache.is_cached(n)
116 >>> noddy_cache.is_cached(noddy.new_noddy())