###

# 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.