Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

Boost.Python

Header <boost/python/to_python_converter.hpp>

Contents

Introduction
Classes
Class Template to_python_converter
Class Template to_python_converter synopsis
Class Template to_python_converter constructor
Example

Introduction

to_python_converter registers a conversion from objects of a given C++ type into a Python object.

Classes

Class template to_python_converter

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.
to_python_converter template parameters
In the table below, x denotes an object of type T
Parameter Requirements Description
T The C++ type of the source object in the conversion
Conversion PyObject* p = Conversion::convert(x),
if p == 0, PyErr_Occurred() != 0.
A class type whose static member function convert does the real work of the conversion.
bool has_get_pytype = false PyTypeObject const * p = Conversion::get_pytype() . 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 here).

Class template to_python_converter synopsis

namespace boost { namespace python
{
  template <class T, class Conversion, bool convertion_has_get_pytype_member=false>
  struct to_python_converter
  {
      to_python_converter();
  };
}}

Class template to_python_converter constructor

to_python_converter();
Effects: Registers a to_python converter which uses Conversion::convert() to do its work.

Example

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.

C++ module definition

#include <boost/python/reference.hpp>
#include <boost/python/module.hpp>
#include "noddy.h"

struct tag {};
tag make_tag() { return tag(); }

using namespace boost::python;

struct tag_to_noddy
{
    static PyObject* convert(tag const& x)
    {
        return PyObject_New(noddy_NoddyObject, &noddy_NoddyType);
    }
    static PyTypeObject const* get_pytype()
    {
        return &noddy_NoddyType;
    }
};

BOOST_PYTHON_MODULE(to_python_converter)
{
    def("make_tag", make_tag);
    to_python_converter<tag, tag_to_noddy, true>(); //"true" because tag_to_noddy has member get_pytype
}

Python code

>>> import to_python_converter
>>> def always_none():
...     return None
...
>>> def choose_function(x):
...     if (x % 2 != 0):
...         return to_python_converter.make_tag
...     else:
...         return always_none
...
>>> a = [ choose_function(x) for x in range(5) ]
>>> b = [ f() for f in a ]
>>> type(b[0])
<type 'NoneType'>
>>> type(b[1])
<type 'Noddy'>
>>> type(b[2])
<type 'NoneType'>
>>> type(b[3])
<type 'Noddy'>

Revised 11 June, 2007

© Copyright Dave Abrahams 2002.