Boost.Python

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 fn, 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. If supplied, policy conforms to the CallPolicy concept requirements.

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:
   ...
};

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.