[article Boost.Python Tutorial

[quickbook 1.6]

[authors [de Guzman, Joel], [Abrahams, David]]

[copyright 2002 2003 2004 2005 Joel de Guzman, David Abrahams]

[category inter-language support]

[id tutorial]

[purpose

Reflects C++ classes and functions into Python

]

[license

Distributed under the Boost Software License, Version 1.0.

(See accompanying file LICENSE_1_0.txt or copy at

[@http://www.boost.org/LICENSE_1_0.txt]

]

]

[/ QuickBook Document version 0.9 ]

[def __note__ [$../images/note.png]]

[def __alert__ [$../images/alert.png]]

[def __tip__ [$../images/tip.png]]

[def :-) [$../images/smiley.png]]

[def __jam__ [$../images/jam.png]]

[section QuickStart]

The Boost Python Library is a framework for interfacing Python and

C++. It allows you to quickly and seamlessly expose C++ classes

functions and objects to Python, and vice-versa, using no special

tools -- just your C++ compiler. It is designed to wrap C++ interfaces

non-intrusively, so that you should not have to change the C++ code at

all in order to wrap it, making Boost.Python ideal for exposing

3rd-party libraries to Python. The library's use of advanced

metaprogramming techniques simplifies its syntax for users, so that

wrapping code takes on the look of a kind of declarative interface

definition language (IDL).

[h2 Hello World]

Following C/C++ tradition, let's start with the "hello, world". A C++

Function:

char const* greet()

{

return "hello, world";

}

can be exposed to Python by writing a Boost.Python wrapper:

#include <boost/python.hpp>

BOOST_PYTHON_MODULE(hello_ext)

{

using namespace boost::python;

def("greet", greet);

}

That's it. We're done. We can now build this as a shared library. The

resulting DLL is now visible to Python. Here's a sample Python session:

[python]

>>> import hello_ext

>>> print hello_ext.greet()

hello, world

[c++]

[:['[*Next stop... Building your Hello World module from start to finish...]]]

[endsect]

[section:hello Building Hello World]

[h2 From Start To Finish]

Now the first thing you'd want to do is to build the Hello World module and

try it for yourself in Python. In this section, we will outline the steps

necessary to achieve that. We will use the build tool that comes bundled

with every boost distribution: [*bjam].

[note [*Building without bjam]

Besides bjam, there are of course other ways to get your module built.

What's written here should not be taken as "the one and only way".

There are of course other build tools apart from [^bjam].

Take note however that the preferred build tool for Boost.Python is bjam.

There are so many ways to set up the build incorrectly. Experience shows

that 90% of the "I can't build Boost.Python" problems come from people

who had to use a different tool.

]

We will skip over the details. Our objective will be to simply create

the hello world module and run it in Python. For a complete reference to

building Boost.Python, check out: [@../../../building.html

building.html]. After this brief ['bjam] tutorial, we should have built

the DLLs and run a python program using the extension.

The tutorial example can be found in the directory:

[^libs/python/example/tutorial]. There, you can find:

* hello.cpp

* hello.py

* Jamroot

The [^hello.cpp] file is our C++ hello world example. The [^Jamroot] is

a minimalist ['bjam] script that builds the DLLs for us. Finally,

[^hello.py] is our Python program that uses the extension in

[^hello.cpp].

Before anything else, you should have the bjam executable in your boost

directory or somewhere in your path such that [^bjam] can be executed in

the command line. Pre-built Boost.Jam executables are available for most

platforms. The complete list of Bjam executables can be found

[@http://sourceforge.net/project/showfiles.php?group_id=7586 here].

[h2 Let's Jam!]

__jam__

[@../../../../example/tutorial/Jamroot Here] is our minimalist Jamroot

file. Simply copy the file and tweak [^use-project boost] to where your

boost root directory is and you're OK.

The comments contained in the Jamrules file above should be sufficient

to get you going.

[h2 Running bjam]

['bjam] is run using your operating system's command line interpreter.

[:Start it up.]

A file called user-config.jam in your home directory is used to

configure your tools. In Windows, your home directory can be found by

typing:

[pre

ECHO %HOMEDRIVE%%HOMEPATH%

]

into a command prompt window. Your file should at least have the rules

for your compiler and your python installation. A specific example of

this on Windows would be:

[pre

# MSVC configuration

using msvc : 8.0 ;

# Python configuration

using python : 2.4 : C:/dev/tools/Python/ ;

]

The first rule tells Bjam to use the MSVC 8.0 compiler and associated

tools. The second rule provides information on Python, its version and

where it is located. The above assumes that the Python installation is

in [^C:/dev/tools\/Python/]. If you have one fairly "standard" python

installation for your platform, you might not need to do this.

Now we are ready... Be sure to [^cd] to [^libs/python/example/tutorial]

where the tutorial [^"hello.cpp"] and the [^"Jamroot"] is situated.

Finally:

bjam

It should be building now:

[pre

cd C:\dev\boost\libs\python\example\tutorial

bjam

...patience...

...found 1101 targets...

...updating 35 targets...

]

And so on... Finally:

[pre

Creating library /path-to-boost_python.dll/

Creating library /path-to-'''hello_ext'''.exp/

'''**passed**''' ... hello.test

...updated 35 targets...

]

Or something similar. If all is well, you should now have built the DLLs and

run the Python program.

[:[*There you go... Have fun!]]

[endsect]

[section:exposing Exposing Classes]

Now let's expose a C++ class to Python.

Consider a C++ class/struct that we want to expose to Python:

struct World

{

void set(std::string msg) { this->msg = msg; }

std::string greet() { return msg; }

std::string msg;

};

We can expose this to Python by writing a corresponding Boost.Python

C++ Wrapper:

#include <boost/python.hpp>

using namespace boost::python;

BOOST_PYTHON_MODULE(hello)

{

class_<World>("World")

.def("greet", &World::greet)

.def("set", &World::set)

;

}

Here, we wrote a C++ class wrapper that exposes the member functions

[^greet] and [^set]. Now, after building our module as a shared library, we

may use our class [^World] in Python. Here's a sample Python session:

[python]

>>> import hello

>>> planet = hello.World()

>>> planet.set('howdy')

>>> planet.greet()

'howdy'

[section Constructors]

Our previous example didn't have any explicit constructors.

Since [^World] is declared as a plain struct, it has an implicit default

constructor. Boost.Python exposes the default constructor by default,

which is why we were able to write

>>> planet = hello.World()

We may wish to wrap a class with a non-default constructor. Let us

build on our previous example:

[c++]

struct World

{

World(std::string msg): msg(msg) {} // added constructor

void set(std::string msg) { this->msg = msg; }

std::string greet() { return msg; }

std::string msg;

};

This time [^World] has no default constructor; our previous

wrapping code would fail to compile when the library tried to expose

it. We have to tell [^class_<World>] about the constructor we want to

expose instead.

#include <boost/python.hpp>

using namespace boost::python;

BOOST_PYTHON_MODULE(hello)

{

class_<World>("World", init<std::string>())

.def("greet", &World::greet)

.def("set", &World::set)

;

}

[^init<std::string>()] exposes the constructor taking in a

[^std::string] (in Python, constructors are spelled

"[^"__init__"]").

We can expose additional constructors by passing more [^init<...>]s to

the [^def()] member function. Say for example we have another World

constructor taking in two doubles:

class_<World>("World", init<std::string>())

.def(init<double, double>())

.def("greet", &World::greet)

.def("set", &World::set)

;

On the other hand, if we do not wish to expose any constructors at

all, we may use [^no_init] instead:

class_<Abstract>("Abstract", no_init)

This actually adds an [^__init__] method which always raises a

Python RuntimeError exception.

[endsect]

[section Class Data Members]

Data members may also be exposed to Python so that they can be

accessed as attributes of the corresponding Python class. Each data

member that we wish to be exposed may be regarded as [*read-only] or

[*read-write]. Consider this class [^Var]:

struct Var

{

Var(std::string name) : name(name), value() {}

std::string const name;

float value;

};

Our C++ [^Var] class and its data members can be exposed to Python:

class_<Var>("Var", init<std::string>())

.def_readonly("name", &Var::name)

.def_readwrite("value", &Var::value);

Then, in Python, assuming we have placed our Var class inside the namespace

hello as we did before:

[python]

>>> x = hello.Var('pi')

>>> x.value = 3.14

>>> print x.name, 'is around', x.value

pi is around 3.14

Note that [^name] is exposed as [*read-only] while [^value] is exposed

as [*read-write].

>>> x.name = 'e' # can't change name

Traceback (most recent call last):

File "<stdin>", line 1, in ?

AttributeError: can't set attribute

[endsect]

[section Class Properties]

In C++, classes with public data members are usually frowned

upon. Well designed classes that take advantage of encapsulation hide

the class' data members. The only way to access the class' data is

through access (getter/setter) functions. Access functions expose class

properties. Here's an example:

[c++]

struct Num

{

Num();

float get() const;

void set(float value);

...

};

However, in Python attribute access is fine; it doesn't neccessarily break

encapsulation to let users handle attributes directly, because the

attributes can just be a different syntax for a method call. Wrapping our

[^Num] class using Boost.Python:

class_<Num>("Num")

.add_property("rovalue", &Num::get)

.add_property("value", &Num::get, &Num::set);

And at last, in Python:

[python]

>>> x = Num()

>>> x.value = 3.14

>>> x.value, x.rovalue

(3.14, 3.14)

>>> x.rovalue = 2.17 # error!

Take note that the class property [^rovalue] is exposed as [*read-only]

since the [^rovalue] setter member function is not passed in:

[c++]

.add_property("rovalue", &Num::get)

[endsect]

[section Inheritance]

In the previous examples, we dealt with classes that are not polymorphic.

This is not often the case. Much of the time, we will be wrapping

polymorphic classes and class hierarchies related by inheritance. We will

often have to write Boost.Python wrappers for classes that are derived from

abstract base classes.

Consider this trivial inheritance structure:

struct Base { virtual ~Base(); };

struct Derived : Base {};

And a set of C++ functions operating on [^Base] and [^Derived] object

instances:

void b(Base*);

void d(Derived*);

Base* factory() { return new Derived; }

We've seen how we can wrap the base class [^Base]:

class_<Base>("Base")

/*...*/

;

Now we can inform Boost.Python of the inheritance relationship between

[^Derived] and its base class [^Base]. Thus:

class_<Derived, bases<Base> >("Derived")

/*...*/

;

Doing so, we get some things for free:

# Derived automatically inherits all of Base's Python methods

(wrapped C++ member functions)

# [*If] Base is polymorphic, [^Derived] objects which have been passed to

Python via a pointer or reference to [^Base] can be passed where a pointer

or reference to [^Derived] is expected.

Now, we will expose the C++ free functions [^b] and [^d] and [^factory]:

def("b", b);

def("d", d);

def("factory", factory);

Note that free function [^factory] is being used to generate new

instances of class [^Derived]. In such cases, we use

[^return_value_policy<manage_new_object>] to instruct Python to adopt

the pointer to [^Base] and hold the instance in a new Python [^Base]

object until the the Python object is destroyed. We will see more of

Boost.Python [link tutorial.functions.call_policies call policies] later.

// Tell Python to take ownership of factory's result

def("factory", factory,

return_value_policy<manage_new_object>());

[endsect]

[section Class Virtual Functions]

In this section, we will learn how to make functions behave polymorphically

through virtual functions. Continuing our example, let us add a virtual function

to our [^Base] class:

struct Base

{

virtual ~Base() {}

virtual int f() = 0;

};

One of the goals of Boost.Python is to be minimally intrusive on an existing C++

design. In principle, it should be possible to expose the interface for a 3rd

party library without changing it. It is not ideal to add anything to our class

`Base`. Yet, when you have a virtual function that's going to be overridden in

Python and called polymorphically *from C++*, we'll need to add some

scaffoldings to make things work properly. What we'll do is write a class

wrapper that derives from `Base` that will unintrusively hook into the virtual

functions so that a Python override may be called:

struct BaseWrap : Base, wrapper<Base>

{

int f()

{

return this->get_override("f")();

}

};

Notice too that in addition to inheriting from `Base`, we also multiply-

inherited `wrapper<Base>` (See [@../reference/high_level_components/boost_python_wrapper_hpp.html#high_level_components.boost_python_wrapper_hpp.class_template_wrapper Wrapper]). The

`wrapper` template makes the job of wrapping classes that are meant to

overridden in Python, easier.

[blurb __alert__ [*MSVC6/7 Workaround]

If you are using Microsoft Visual C++ 6 or 7, you have to write `f` as:

`return call<int>(this->get_override("f").ptr());`.]

BaseWrap's overridden virtual member function `f` in effect calls the

corresponding method of the Python object through `get_override`.

Finally, exposing `Base`:

class_<BaseWrap, boost::noncopyable>("Base")

.def("f", pure_virtual(&Base::f))

;

`pure_virtual` signals Boost.Python that the function `f` is a pure virtual

function.

[note [*member function and methods]

Python, like many object oriented languages uses the term [*methods].

Methods correspond roughly to C++'s [*member functions]]

[endsect]

[section Virtual Functions with Default Implementations]

We've seen in the previous section how classes with pure virtual functions are

wrapped using Boost.Python's [@../reference/high_level_components/boost_python_wrapper_hpp.html#high_level_components.boost_python_wrapper_hpp.class_template_wrapper class wrapper]

facilities. If we wish to wrap [*non]-pure-virtual functions instead, the

mechanism is a bit different.

Recall that in the [link tutorial.exposing.class_virtual_functions previous section], we

wrapped a class with a pure virtual function that we then implemented in C++, or

Python classes derived from it. Our base class:

struct Base

{

virtual int f() = 0;

};

had a pure virtual function [^f]. If, however, its member function [^f] was

not declared as pure virtual:

struct Base

{

virtual ~Base() {}

virtual int f() { return 0; }

};

We wrap it this way:

struct BaseWrap : Base, wrapper<Base>

{

int f()

{

if (override f = this->get_override("f"))

return f(); // *note*

return Base::f();

}

int default_f() { return this->Base::f(); }

};

Notice how we implemented `BaseWrap::f`. Now, we have to check if there is an

override for `f`. If none, then we call `Base::f()`.

[blurb __alert__ [*MSVC6/7 Workaround]

If you are using Microsoft Visual C++ 6 or 7, you have to rewrite the line

with the `*note*` as:

`return call<char const*>(f.ptr());`.]

Finally, exposing:

class_<BaseWrap, boost::noncopyable>("Base")

.def("f", &Base::f, &BaseWrap::default_f)

;

Take note that we expose both `&Base::f` and `&BaseWrap::default_f`.

Boost.Python needs to keep track of 1) the dispatch function [^f] and 2) the

forwarding function to its default implementation [^default_f]. There's a

special [^def] function for this purpose.

In Python, the results would be as expected:

[python]

>>> base = Base()

>>> class Derived(Base):

... def f(self):

... return 42

...

>>> derived = Derived()

Calling [^base.f()]:

>>> base.f()

0

Calling [^derived.f()]:

>>> derived.f()

42

[endsect]

[section Class Operators/Special Functions]

[h2 Python Operators]

C is well known for the abundance of operators. C++ extends this to the

extremes by allowing operator overloading. Boost.Python takes advantage of

this and makes it easy to wrap C++ operator-powered classes.

Consider a file position class [^FilePos] and a set of operators that take

on FilePos instances:

[c++]

class FilePos { /*...*/ };

FilePos operator+(FilePos, int);

FilePos operator+(int, FilePos);

int operator-(FilePos, FilePos);

FilePos operator-(FilePos, int);

FilePos& operator+=(FilePos&, int);

FilePos& operator-=(FilePos&, int);

bool operator<(FilePos, FilePos);

The class and the various operators can be mapped to Python rather easily

and intuitively:

class_<FilePos>("FilePos")

.def(self + int()) // __add__

.def(int() + self) // __radd__

.def(self - self) // __sub__

.def(self - int()) // __sub__

.def(self += int()) // __iadd__

.def(self -= other<int>())

.def(self < self); // __lt__

The code snippet above is very clear and needs almost no explanation at

all. It is virtually the same as the operators' signatures. Just take

note that [^self] refers to FilePos object. Also, not every class [^T] that

you might need to interact with in an operator expression is (cheaply)

default-constructible. You can use [^other<T>()] in place of an actual

[^T] instance when writing "self expressions".

[h2 Special Methods]

Python has a few more ['Special Methods]. Boost.Python supports all of the

standard special method names supported by real Python class instances. A

similar set of intuitive interfaces can also be used to wrap C++ functions

that correspond to these Python ['special functions]. Example:

class Rational

{ public: operator double() const; };

Rational pow(Rational, Rational);

Rational abs(Rational);

ostream& operator<<(ostream&,Rational);

class_<Rational>("Rational")

.def(float_(self)) // __float__

.def(pow(self, other<Rational>)) // __pow__

.def(abs(self)) // __abs__

.def(str(self)) // __str__

;

Need we say more?

[note What is the business of `operator<<`?

Well, the method `str` requires the `operator<<` to do its work (i.e.

`operator<<` is used by the method defined by `def(str(self))`.]

[endsect]

[endsect] [/ Exposing Classes ]

[section Functions]

In this chapter, we'll look at Boost.Python powered functions in closer

detail. We will see some facilities to make exposing C++ functions to

Python safe from potential pifalls such as dangling pointers and

references. We will also see facilities that will make it even easier for

us to expose C++ functions that take advantage of C++ features such as

overloading and default arguments.

[:['Read on...]]

But before you do, you might want to fire up Python 2.2 or later and type

[^>>> import this].

[pre

>>> import this

The Zen of Python, by Tim Peters

Beautiful is better than ugly.

Explicit is better than implicit.

Simple is better than complex.

Complex is better than complicated.

Flat is better than nested.

Sparse is better than dense.

Readability counts.

Special cases aren't special enough to break the rules.

Although practicality beats purity.

Errors should never pass silently.

Unless explicitly silenced.

In the face of ambiguity, refuse the temptation to guess.

There should be one-- and preferably only one --obvious way to do it

Although that way may not be obvious at first unless you're Dutch.

Now is better than never.

Although never is often better than *right* now.

If the implementation is hard to explain, it's a bad idea.

If the implementation is easy to explain, it may be a good idea.

Namespaces are one honking great idea -- let's do more of those!

]

[section Call Policies]

In C++, we often deal with arguments and return types such as pointers

and references. Such primitive types are rather, ummmm, low level and

they really don't tell us much. At the very least, we don't know the

owner of the pointer or the referenced object. No wonder languages

such as Java and Python never deal with such low level entities. In

C++, it's usually considered a good practice to use smart pointers

which exactly describe ownership semantics. Still, even good C++

interfaces use raw references and pointers sometimes, so Boost.Python

must deal with them. To do this, it may need your help. Consider the

following C++ function:

X& f(Y& y, Z* z);

How should the library wrap this function? A naive approach builds a

Python X object around result reference. This strategy might or might

not work out. Here's an example where it didn't

>>> x = f(y, z) # x refers to some C++ X

>>> del y

>>> x.some_method() # CRASH!

What's the problem?

Well, what if f() was implemented as shown below:

X& f(Y& y, Z* z)

{

y.z = z;

return y.x;

}

The problem is that the lifetime of result X& is tied to the lifetime

of y, because the f() returns a reference to a member of the y

object. This idiom is is not uncommon and perfectly acceptable in the

context of C++. However, Python users should not be able to crash the

system just by using our C++ interface. In this case deleting y will

invalidate the reference to X. We have a dangling reference.

Here's what's happening:

# [^f] is called passing in a reference to [^y] and a pointer to [^z]

# A reference to [^y.x] is returned

# [^y] is deleted. [^x] is a dangling reference

# [^x.some_method()] is called

# [*BOOM!]

We could copy result into a new object:

[python]

>>> f(y, z).set(42) # Result disappears

>>> y.x.get() # No crash, but still bad

3.14

This is not really our intent of our C++ interface. We've broken our

promise that the Python interface should reflect the C++ interface as

closely as possible.

Our problems do not end there. Suppose Y is implemented as follows:

[c++]

struct Y

{

X x; Z* z;

int z_value() { return z->value(); }

};

Notice that the data member [^z] is held by class Y using a raw

pointer. Now we have a potential dangling pointer problem inside Y:

>>> x = f(y, z) # y refers to z

>>> del z # Kill the z object

>>> y.z_value() # CRASH!

For reference, here's the implementation of [^f] again:

X& f(Y& y, Z* z)

{

y.z = z;

return y.x;

}

Here's what's happening:

# [^f] is called passing in a reference to [^y] and a pointer to [^z]

# A pointer to [^z] is held by [^y]

# A reference to [^y.x] is returned

# [^z] is deleted. [^y.z] is a dangling pointer

# [^y.z_value()] is called

# [^z->value()] is called

# [*BOOM!]

[h2 Call Policies]

Call Policies may be used in situations such as the example detailed above.

In our example, [^return_internal_reference] and [^with_custodian_and_ward]

are our friends:

def("f", f,

return_internal_reference<1,

with_custodian_and_ward<1, 2> >());

What are the [^1] and [^2] parameters, you ask?

return_internal_reference<1

Informs Boost.Python that the first argument, in our case [^Y& y], is the

owner of the returned reference: [^X&]. The "[^1]" simply specifies the

first argument. In short: "return an internal reference [^X&] owned by the

1st argument [^Y& y]".

with_custodian_and_ward<1, 2>

Informs Boost.Python that the lifetime of the argument indicated by ward

(i.e. the 2nd argument: [^Z* z]) is dependent on the lifetime of the

argument indicated by custodian (i.e. the 1st argument: [^Y& y]).

It is also important to note that we have defined two policies above. Two

or more policies can be composed by chaining. Here's the general syntax:

policy1<args...,

policy2<args...,

policy3<args...> > >

Here is the list of predefined call policies. A complete reference detailing

these can be found [@../reference/function_invocation_and_creation/models_of_callpolicies.html here].

* [*with_custodian_and_ward]: Ties lifetimes of the arguments

* [*with_custodian_and_ward_postcall]: Ties lifetimes of the arguments and results

* [*return_internal_reference]: Ties lifetime of one argument to that of result

* [*return_value_policy<T> with T one of:]

* [*reference_existing_object]: naive (dangerous) approach

* [*copy_const_reference]: Boost.Python v1 approach

* [*copy_non_const_reference]:

* [*manage_new_object]: Adopt a pointer and hold the instance

[blurb :-) [*Remember the Zen, Luke:]

"Explicit is better than implicit"

"In the face of ambiguity, refuse the temptation to guess"

]

[endsect]

[section Overloading]

The following illustrates a scheme for manually wrapping an overloaded

member functions. Of course, the same technique can be applied to wrapping

overloaded non-member functions.

We have here our C++ class:

struct X

{

bool f(int a)

{

return true;

}

bool f(int a, double b)

{

return true;

}

bool f(int a, double b, char c)

{

return true;

}

int f(int a, int b, int c)

{

return a + b + c;

};

};

Class X has 4 overloaded functions. We will start by introducing some

member function pointer variables:

bool (X::*fx1)(int) = &X::f;

bool (X::*fx2)(int, double) = &X::f;

bool (X::*fx3)(int, double, char)= &X::f;

int (X::*fx4)(int, int, int) = &X::f;

With these in hand, we can proceed to define and wrap this for Python:

.def("f", fx1)

.def("f", fx2)

.def("f", fx3)

.def("f", fx4)

[endsect]

[section Default Arguments]

Boost.Python wraps (member) function pointers. Unfortunately, C++ function

pointers carry no default argument info. Take a function [^f] with default

arguments:

int f(int, double = 3.14, char const* = "hello");

But the type of a pointer to the function [^f] has no information

about its default arguments:

int(*g)(int,double,char const*) = f; // defaults lost!

When we pass this function pointer to the [^def] function, there is no way

to retrieve the default arguments:

def("f", f); // defaults lost!

Because of this, when wrapping C++ code, we had to resort to manual

wrapping as outlined in the [link tutorial.functions.overloading previous section], or

writing thin wrappers:

// write "thin wrappers"

int f1(int x) { return f(x); }

int f2(int x, double y) { return f(x,y); }

/*...*/

// in module init

def("f", f); // all arguments

def("f", f2); // two arguments

def("f", f1); // one argument

When you want to wrap functions (or member functions) that either:

* have default arguments, or

* are overloaded with a common sequence of initial arguments

[h2 BOOST_PYTHON_FUNCTION_OVERLOADS]

Boost.Python now has a way to make it easier. For instance, given a function:

int foo(int a, char b = 1, unsigned c = 2, double d = 3)

{

/*...*/

}

The macro invocation:

BOOST_PYTHON_FUNCTION_OVERLOADS(foo_overloads, foo, 1, 4)

will automatically create the thin wrappers for us. This macro will create

a class [^foo_overloads] that can be passed on to [^def(...)]. The third

and fourth macro argument are the minimum arguments and maximum arguments,

respectively. In our [^foo] function the minimum number of arguments is 1

and the maximum number of arguments is 4. The [^def(...)] function will

automatically add all the foo variants for us:

def("foo", foo, foo_overloads());

[h2 BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS]

Objects here, objects there, objects here there everywhere. More frequently

than anything else, we need to expose member functions of our classes to

Python. Then again, we have the same inconveniences as before when default

arguments or overloads with a common sequence of initial arguments come

into play. Another macro is provided to make this a breeze.

Like [^BOOST_PYTHON_FUNCTION_OVERLOADS],

[^BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS] may be used to automatically create

the thin wrappers for wrapping member functions. Let's have an example:

struct george

{

void

wack_em(int a, int b = 0, char c = 'x')

{

/*...*/

}

};

The macro invocation:

BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS(george_overloads, wack_em, 1, 3)

will generate a set of thin wrappers for george's [^wack_em] member function

accepting a minimum of 1 and a maximum of 3 arguments (i.e. the third and

fourth macro argument). The thin wrappers are all enclosed in a class named

[^george_overloads] that can then be used as an argument to [^def(...)]:

.def("wack_em", &george::wack_em, george_overloads());

See the [@../reference/function_invocation_and_creation/boost_python_overloads_hpp.html#function_invocation_and_creation.boost_python_overloads_hpp.macros overloads reference]

for details.

[h2 init and optional]

A similar facility is provided for class constructors, again, with

default arguments or a sequence of overloads. Remember [^init<...>]? For example,

given a class X with a constructor:

struct X

{

X(int a, char b = 'D', std::string c = "constructor", double d = 0.0);

/*...*/

}

You can easily add this constructor to Boost.Python in one shot:

.def(init<int, optional<char, std::string, double> >())

Notice the use of [^init<...>] and [^optional<...>] to signify the default

(optional arguments).

[endsect]

[section Auto-Overloading]

It was mentioned in passing in the previous section that

[^BOOST_PYTHON_FUNCTION_OVERLOADS] and [^BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS]

can also be used for overloaded functions and member functions with a

common sequence of initial arguments. Here is an example: