[C++-sig] Boost.Python v2: ** important **

[Joel de Guzman]

Hi Y'all,

I should have posted this a few days ago. Pardon the delay.
Dave has already integrated my latest changes to the codebase
It has been committed to CVS since Tuesday. Everything is
humming along nicely in all compilers supported by Boost.Python.

These changes have been discussed before. Here's a refresher:

You can see a sample in the test directory named "defaults.cpp"
that tests and demonstrates these new capabilities. Most importantly,
when you want to wrap functions (or member functions) that are
either 1) overloaded or 2) has default arguments, there is a facility
now to make it easy to do this. 

For instance, given a function:

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

Before, you needed to write thin wrappers to make Python
recognize foo(int), foo(int, char), foo(int, char, unsigned)
and foo(int, char, unsigned, double). Then tediously inform 
Boost.Python of each of the thin-wrapped functions corresponding
to variations of the function foo.

Now, The macro invocation:

    BOOST_PYTHON_FUNCTION_OVERLOADS(foo_overloads, foo, 1, 4)

Will create the thin wrappers for us. This macro will create a class
"foo_overloads" that can be passed on to def(...) and automatically add
all the foo variants for us. For example:

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

You may *optionally* specify a docstring:

        .def("foo", foo, foo_overloads("my doc string"));

You may also *optionally* specify a call policy:

        .def("foo", foo, foo_overloads("my doc string")[my_call_policy]);

A similar facility is provided for class constructors, again, with or
without default arguments or overloads. For example, given a class X
with a constructor:

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

You can now easily add this constructor to Boost.Python:

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

Notice the use of init<...> and optional<...> to signify the default (optional
arguments). 

You may *optionally* specify a docstring:

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

You may also *optionally* specify a call policy:

    .def(init<int, optional<char, std::string, double> >("my doc string")[my_policy])

Here are the summary of the changes

1. When specifying constructors, there is a new format:

     init<...args..., optional< ...args...> >("docstring")[call_policies()]

Of course any of args, optional, "docstring" and [call_policies()] may be
ommitted (as shown above).

2. The def_init() function is ***obsolete***. It is replaced by a def()
overload which accepts init<...>. Thus:

    // default constructor with docstring
    class_<Y>("Y", init<>("doc of Y init"))
        .def("get_state", &Y::get_state)
        .def(init<int, optional<char, std::string, double> >("doc of
init"))
        .def(init<X*>()[with_custodian_and_ward<1,2>()])
        ;

3. A similar interface applies to the default argument feature:

  X* foo(Y& y, char b = 'D', std::string c = "default", double d = 0.0);

  // Generate overloads for 1-4 parameters
  BOOST_PYTHON_FUNCTION_OVERLOADS(foo_overloads, foo, 1, 4)

    ...
    def("foo", foo, foo_overloads("about
foo")[return_internal_reference<>()])

Here is a list of the possible arguments to def:

    The arguments may be:

        def(name, function)
        def(name, function, policy)
        def(name, function, doc_string)
        def(name, signature, overloads)
        def(name, function, policy, doc_string)
        def(name, function, doc_string, policy)

Where signature and overloads are the new kids in the block as explained above.

Finally, be reminded that ***module is obsolete****. It is dead and has 
been for some time now. 

================================

Have fun!

--Joel