C++ Boost

Boost.Python

Headers <boost/python/class.hpp>, <boost/python/class_fwd.hpp>


Contents

Introduction
Classes
Class template class_
Class class_ synopsis
Class class_ constructors
Class class_ modifier functions
Class class_ observer functions
Class template bases
Class bases synopsis
Class template args
Class args synopsis
Example(s)

Introduction

<boost/python/class.hpp> defines the interface through which users expose their C++ classes to Python. It declares the class_ class template, which is parameterized on the class type being exposed, and the args and bases utility class templates in the anonymous namespace (the latter definitions will probably be moved in a future release).

<boost/python/class_fwd.hpp> contains a forward declaration of the class_ class template.

Classes

Class template class_<T, Bases, HolderGenerator>

Creates a Python class associated with the C++ type passed as its first parameter. Its template arguments are:

Parameter Requirements Default
T A class type.
Bases An MPL sequence of C++ base classes of T. An unspecified empty sequence
HolderGenerator A model of HolderGenerator. boost::python::objects::value_holder_generator

Class template class_ synopsis

namespace boost { namespace python
{

  template <class T
            , class Bases = none
            , class HolderGenerator = objects::value_holder_generator>
  class class_
  {
    class_();
    class_(char const* name);

    template <class F>
    class_& def(char const* name, F f);

    template <class Fn, class CallPolicy>
    class_& def(char const* name, Fn fn, CallPolicy policy);
    
    template <class Args>
    class_& def_init(Args const& = Args());

    class_& def_init();

    ref object() const;
  };
}}

Class template class_ constructors

class_()
Requires: The platform's std::type_info::name() implementation produces a string which corresponds to the type's declaration in C++
Effects: Constructs a class_ object which generates a Boost.Python extension class with the same name as T.
Rationale: Many platforms can generate reasonable names for Python classes without user intervention.
class_(char const* name)
Requires: name is a ntbs which conforms to Python's identifier naming rules.
Effects: Constructs a class_ object which generates a Boost.Python extension class named name.
Rationale: Gives the user full control over class naming.

Class template class_ modifier functions

template <class F>
class_& def(char const* name, F f)

template <class Fn, class CallPolicy>
class_& def(char const* name, Fn f, CallPolicy policy)
Requires: f is a non-null pointer-to-function or pointer-to-member-function. name is a ntbs which conforms to Python's identifier naming rules. In the first form, the return type of f is not a reference and is not a pointer other than char const* or PyObject*. In the second form policy is a model of CallPolicies.
Effects: Adds the result of make_function(f) to the Boost.Python extension class being defined, with the given name. If the extension class already has an attribute named name, the usual overloading procedure applies.
Returns: *this
template <class Args>
class_& def_init(Args const& argument_types)

class_& def_init()
Requires: in the first form, argument_types must be an MPL sequence of C++ argument types (A1, A2,... AN) such that if a1, a2... aN are objects of type A1, A2,... AN respectively, the expression T(a1, a2... aN) is valid. In the second form, the expression T() must be valid.
Effects: Adds the result of make_constructor<T,Args,HolderGenerator>() to the Boost.Python extension class being defined with the name "__init__". If the 2nd form is used, an unspecified empty MPL sequence type is substituted for Args. If the extension class already has an "__init__" attribute, the usual overloading procedure applies.
Returns: *this
Rationale: Allows users to easily expose a class' constructor to Python.

Class template class_ observer functions

ref object() const;
Returns: A ref object which holds a reference to the Boost.Python extension class object created by the class_ constructor.
Rationale: Mostly not needed by users, since module::add() uses this to insert the extension class in the module.

Class template args<T1, T2,...TN>

Essentially an alias for boost::mpl::type_list which users can use in def_init calls to make their code more readable. Currently it is in the global unnammed namespace, but that will probably change.

Class template args synopsis

namespace
{
  template <T1 = unspecified,...TN = unspecified>
  struct args : ::boost::mpl::type_list<T1,...TN>::type
  {};
}

Class template bases<T1, T2,...TN>

Essentially an alias for boost::mpl::type_list which users can use in class_<...> instantiations to make their code more readable. Currently it is in the global unnammed namespace, but that will probably change.

Class template bases synopsis

namespace
{
  template <T1 = unspecified,...TN = unspecified>
  struct bases : ::boost::mpl::type_list<T1,...TN>::type
  {};
}

Example(s)

Given a C++ class declaration:

class Foo : public Bar, public Baz
{
 public:
   Foo(int, char const*);
   Foo(double);

   std::string const& name() { return m_name; }
   void name(char const*);
 private:
   ...
};
A corresponding Boost.Python extension class can be created with:
using namespace boost::python;
ref foo =
class_<Foo,bases<Bar,Baz> >()
   .def_init(args<int,char const*>())
   .def_init(args<double>())
   .def("get_name", &Foo::get_name, return_internal_reference<>())
   .def("set_name", &Foo::set_name)
   .object();
Revised 05 November, 2001

© Copyright Dave Abrahams 2002. All Rights Reserved.