Boost.Python - <boost/python/init.hpp>

###  | # Boost.Python ## Headers <boost/python/init.hpp>

## Contents

Introduction
init-expressions
Classes
  Class template `init`
    Class template `init` synopsis
    Class `init` constructors
  Class template `optional`
    Class template `optional` synopsis
Example(s)

## Introduction

`<boost/python/init.hpp>` defines the interface for exposing C++ constructors to Python as extension class `__init__` functions.

## init-expressions

An init-expression is used to describe a family of `__init__` methods to be generated for an extension class, and the result has the following properties:

> docstring: An ntbs whose value will bound to the method's `__doc__` attribute
> keywords: A keyword-expression which will be used to name (a trailing subsequence of) the arguments to the generated `__init__` function(s).
> call policies: An instance of a model of CallPolicies.
> argument types: An MPL sequence of C++ argument types which will be used to construct the wrapped C++ object. An init expression has one or more valid prefixes which are given by a sequence of prefixes of its argument types.

## Classes

### Class template `init<T1 =` unspecified`, T2 =` unspecified`,`...`Tn` = unspecified`>`

A MPL sequence which can be used to specify a family of one or more `__init__` functions. Only the last `T`i supplied may be an instantiation of `optional``<`...`>`.

#### Class template `init` synopsis

    namespace boost { namespace python
    {
      template <T1 = unspecified,...Tn = unspecified>
      struct init
      {
          init(char const* doc = 0);
          template <class Keywords> init(Keywords const& kw, char const* doc = 0);
          template <class Keywords> init(char const* doc, Keywords const& kw);

          template <class CallPolicies>
          unspecified operator[](CallPolicies const& policies) const
      };
    }}

#### Class template `init` constructors

    init(char const* doc = 0);
    template <class Keywords> init(Keywords const& kw, char const* doc = 0);
    template <class Keywords> init(char const* doc, Keywords const& kw);

Requires: If supplied, `doc` is an ntbs. If supplied, `kw` is the result of a
Effects: The result is an init-expression whose docstring is `doc` and whose keywords are a reference to `kw`. If the first form is used, the resulting expression's keywords are empty. The expression's call policies are an instance of default_call_policies. If `T`n is `optional``<U1, U2,`... `U`m`>`, the expression's valid prefixes are given by:

  > (`T1, T2,`...`T`n-1), (`T1, T2,`...`T`n-1 `, U1`), (`T1, T2,`...`T`n-1 `, U1, U2`), ...(`T1, T2,`...`T`n-1 `, U1, U2,`...`U`m).

  Otherwise, the expression has one valid prefix given by the the template arguments the user specified.

#### Class template `init` observer functions

    template <class Policies>
    unspecified operator[](Policies const& policies) const

Requires: Policies is a model of CallPolicies.
Effects: Returns a new init-expression with all the same properties as the `init` object except that its call policies are replaced by a reference to `policies`.

### Class template `optional<T1 =` unspecified`, T2 =` unspecified`,`...`Tn` = unspecified`>`

A MPL sequence which can be used to specify the optional arguments to an `__init__` function.

#### Class template `optional` synopsis

    namespace boost { namespace python
    {
      template <T1 = unspecified,...Tn = unspecified>
      struct optional {};
    }}

## Example(s)

Given the C++ declarations:

    class Y;
    class X
    {
     public:
       X(int x, Y* y) : m_y(y) {}
       X(double);
     private:
       Y* m_y;
    };

A corresponding Boost.Python extension class can be created with:

    using namespace boost::python;

    class_<X>("X", "This is X's docstring.",
              init<int,char const*>(args("x","y"), "X.__init__'s docstring")[
                    with_custodian_and_ward<1,3>()]
              )
       .def(init<double>())
       ;

Revised 13 November, 2002

© Copyright Dave Abrahams 2002.