== Pointers and smart pointers ==

Since Python handles memory allocation and garbage collection automatically, the concept of a "pointer" is not meaningful in Python. However, many C++ APIs expose either raw pointers or shared pointers, to wrap these APIs we need to deal with pointers.

=== Raw C++ Pointers ===

The lifetime of C++ objects created by {{{new A}}} can be handled by Python's garbage collection by using the {{{manage_new_object}}} return policy: 

{{{
struct A {
    static A*   create () { return new A; }
    std::string hello  () { return "Hello, is there anybody in there?"; }
};

BOOST_PYTHON_MODULE(pointer)
{
    class_<A>("A",no_init)
        .def("create",&A::create, return_value_policy<manage_new_object>())
        .staticmethod("create")
        .def("hello",&A::hello)
        ;
}
}}}

A sample python program:
{{{
from pointer import *
an_A = A.create()
print an_A.hello()
}}}

=== Smart pointers ===

The usage of smart pointers (e.g. {{{boost::shared_ptr<T>}}}) is another common way to give away ownership of objects in C++. These kinds of smart pointer are automatically handled if you declare their existence when declaring the class to boost::python.  This is done by including the holding type as a template parameter to {{{class_<>}}}, like in the following example:

{{{
#include <string>
#include <boost/shared_ptr.hpp>
#include <boost/python.hpp>

using namespace boost;
using namespace std;
using namespace boost::python;

struct A {
    static shared_ptr<A> create () { return shared_ptr<A>(new A); }
    std::string   hello  () { return "Just nod if you can hear me!"; }
};

BOOST_PYTHON_MODULE(shared_ptr)
{
    class_<A, shared_ptr<A> >("A",init<>())
        .def("create",&A::create )
        .staticmethod("create")
        .def("hello",&A::hello)
    ;
}
}}}

A sample python program:

{{{
from shared_ptr import *
an_A = A.create()
print an_A.hello()
}}}

<<Anchor(OSG_example)>>
=== Smart Pointer Example with OpenSceneGraph ===
The Node.cpp file:
{{{
#include <boost/python.hpp>
#include <osg/ref_ptr>
#include <osg/Node>

using namespace boost::python;
using namespace osg;

// Tag the OpenSceneGraph ref_ptr type as a smart pointer.
namespace boost {
  namespace python {
    template <class T> struct pointee< ref_ptr<T> >
    { typedef T type; };
  }}

// Declare the actual type
BOOST_PYTHON_MODULE(Node) {
  class_<Node, ref_ptr<Node> >("Node")
    ;
}
}}}
This creates an opaque Node pointer.  It can be extended to expose members of Node objects, or used as is to return opaque references to Node objects.  For opaque references, the module must still be imported by the Python app.  If Node.pyd is in a package directory, importing it in the {{{__init__.py}}} file in that directory seems to be a simple, workable solution.