# Boost.Python - <boost/python/class.hpp>, <boost/python/class_fwd.hpp>

###

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