###

# Boost.Python

## Header <register_ptr_to_python.hpp>

## Contents

Introduction
Functions

register_ptr_to_python

Example(s)

## Introduction

`<boost/python/register_ptr_to_python.hpp>` supplies `register_ptr_to_python`, a function template which registers a conversion for smart pointers to Python. The resulting Python object holds a copy of the converted smart pointer, but behaves as though it were a wrapped copy of the pointee. If the pointee type has virtual functions and the class representing its dynamic (most-derived) type has been wrapped, the Python object will be an instance of the wrapper for the most-derived type. More than one smart pointer type for a pointee's class can be registered.

Note that in order to convert a Python `X` object to a `smart_ptr<X>&` (non-const reference), the embedded C++ object must be held by `smart_ptr<X>`, and that when wrapped objects are created by calling the constructor from Python, how they are held is determined by the `HeldType` parameter to `class_<...>` instances.

## Functions

    template <class P>
    void register_ptr_to_python()

Requires: `P` is Dereferenceable.
Effects: Allows conversions to-python of `P` instances.

## Example(s)

### C++ Wrapper Code

Here is an example of a module that contains a class `A` with virtual functions and some functions that work with `boost::shared_ptr<A>`.

    struct A
    {
        virtual int f() { return 0; }
    };

    shared_ptr<A> New() { return shared_ptr<A>( new A() ); }

    int Ok( const shared_ptr<A>& a ) { return a->f(); }

    int Fail( shared_ptr<A>& a ) { return a->f(); }

    struct A_Wrapper: A
    {
        A_Wrapper(PyObject* self_): self(self_) {}
        int f() { return call_method<int>(self, "f"); }
        int default_f() { return A::f(); }
        PyObject* self;
    };

    BOOST_PYTHON_MODULE(register_ptr)
    {
        class_<A, A_Wrapper>("A")
            .def("f", &A::f, &A_Wrapper::default_f)
        ;

        def("New", &New);
        def("Ok", &Call);
        def("Fail", &Fail);

        register_ptr_to_python< shared_ptr<A> >();
    }

### Python Code

    >>> from register_ptr import *
    >>> a = A()
    >>> Ok(a)     # ok, passed as shared_ptr<A>
    0
    >>> Fail(a)   # passed as shared_ptr<A>&, and was created in Python!
    Traceback (most recent call last):
      File "<stdin>", line 1, in ?
    TypeError: bad argument type for built-in operation
    >>>
    >>> na = New()   # now "na" is actually a shared_ptr<A>
    >>> Ok(a)
    0
    >>> Fail(a)
    0
    >>>

If `shared_ptr<A>` is registered as follows:

        class_<A, A_Wrapper, shared_ptr<A> >("A")
            .def("f", &A::f, &A_Wrapper::default_f)
        ;

There will be an error when trying to convert `shared_ptr<A>` to `shared_ptr<A_Wrapper>`:

    >>> a = New()
    Traceback (most recent call last):
    File "<stdin>", line 1, in ?
    TypeError: No to_python (by-value) converter found for C++ type: class boost::shared_ptr<struct A>
    >>>

Revised 24 Jun, 2003

© Copyright Dave Abrahams 2002.