]>
Commit | Line | Data |
---|---|---|
1 | [section boost/python/to_python_converter.hpp] | |
2 | [section Introduction] | |
3 | `to_python_converter` registers a conversion from objects of a given C++ type into a Python object. | |
4 | [endsect] | |
5 | [section Class template `to_python_converter`] | |
6 | `to_python_converter` adds a wrapper around a static member function of its second template parameter, handling low-level details such as insertion into the converter registry. | |
7 | ||
8 | In the table below, x denotes an object of type T | |
9 | [table | |
10 | [[Parameter][Requirements][Description]] | |
11 | [[T][][The C++ type of the source object in the conversion]] | |
12 | [[Conversion][`PyObject* p = Conversion::convert(x)`, | |
13 | `if p == 0`, `PyErr_Occurred() != 0`.][A class type whose static member function convert does the real work of the conversion.]] | |
14 | [[bool has_get_pytype=false][`PyTypeObject const * p = Conversion::get_pytype()`] | |
15 | [Optional member - if Conversion has `get_pytype` member supply `true` for this parameters. If present `get_pytype` is used to document the return type of functions using this conversion. The `get_pytype` may be implemented using the classes and functions from pytype_function.hpp NOTE : For backward compatibility this parameter may be passed after checking if BOOST_PYTHON_SUPPORTS_PY_SIGNATURES is defined (see [link function_invocation_and_creation.function_documentation.boost_python_pytype_function_hpp.example here]).] | |
16 | ]] | |
17 | ||
18 | `` | |
19 | namespace boost { namespace python | |
20 | { | |
21 | template <class T, class Conversion, bool convertion_has_get_pytype_member=false> | |
22 | struct to_python_converter | |
23 | { | |
24 | to_python_converter(); | |
25 | }; | |
26 | }} | |
27 | `` | |
28 | [section Class template `to_python_converter` constructor] | |
29 | ``to_python_converter();`` | |
30 | [variablelist | |
31 | [[Effects][Registers a `to_python` converter which uses `Conversion::convert()` to do its work.]] | |
32 | ] | |
33 | [endsect] | |
34 | [endsect] | |
35 | [section Example] | |
36 | This example presumes that someone has implemented the standard noddy example module from the Python documentation, and placed the corresponding declarations in "noddy.h". Because noddy_NoddyObject is the ultimate trivial extension type, the example is a bit contrived: it wraps a function for which all information is contained in the type of its return value. | |
37 | ||
38 | In C++: | |
39 | `` | |
40 | #include <boost/python/reference.hpp> | |
41 | #include <boost/python/module.hpp> | |
42 | #include "noddy.h" | |
43 | ||
44 | struct tag {}; | |
45 | tag make_tag() { return tag(); } | |
46 | ||
47 | using namespace boost::python; | |
48 | ||
49 | struct tag_to_noddy | |
50 | { | |
51 | static PyObject* convert(tag const& x) | |
52 | { | |
53 | return PyObject_New(noddy_NoddyObject, &noddy_NoddyType); | |
54 | } | |
55 | static PyTypeObject const* get_pytype() | |
56 | { | |
57 | return &noddy_NoddyType; | |
58 | } | |
59 | }; | |
60 | ||
61 | BOOST_PYTHON_MODULE(to_python_converter) | |
62 | { | |
63 | def("make_tag", make_tag); | |
64 | to_python_converter<tag, tag_to_noddy, true>(); //"true" because tag_to_noddy has member get_pytype | |
65 | } | |
66 | `` | |
67 | In Python: | |
68 | `` | |
69 | >>> import to_python_converter | |
70 | >>> def always_none(): | |
71 | ... return None | |
72 | ... | |
73 | >>> def choose_function(x): | |
74 | ... if (x % 2 != 0): | |
75 | ... return to_python_converter.make_tag | |
76 | ... else: | |
77 | ... return always_none | |
78 | ... | |
79 | >>> a = [ choose_function(x) for x in range(5) ] | |
80 | >>> b = [ f() for f in a ] | |
81 | >>> type(b[0]) | |
82 | <type 'NoneType'> | |
83 | >>> type(b[1]) | |
84 | <type 'Noddy'> | |
85 | >>> type(b[2]) | |
86 | <type 'NoneType'> | |
87 | >>> type(b[3]) | |
88 | <type 'Noddy'> | |
89 | `` | |
90 | [endsect] | |
91 | [endsect] |