ceph/src/boost/libs/python/doc/reference/to_python_converter.qbk

   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]