+ +-+- __class__ | +---+ +----------------------+
+ | m_wrapped_objects -+-->| *-+-->| contains B1_callback |
+ +---------------------+ +---+ +----------------------+
diff --git a/doc/enums.html b/doc/enums.html
new file mode 100644
index 00000000..c58ca34d
--- /dev/null
+++ b/doc/enums.html
@@ -0,0 +1,120 @@
+
+
+ Wrapping enums
+
+
+
+ 
+ Wrapping enums
+
+
+
Because there is in general no way to deduce that a value of arbitrary type T
+is an enumeration constant, the Boost Python Library cannot automatically
+convert enum values to and from Python. To handle this case, you need to decide
+how you want the enum to show up in Python (since Python doesn't have
+enums). Once you have done that, you can write some simple
+from_python() and to_python() functions.
+
+
If you are satisfied with a Python int as a way to represent your enum
+values, we provide a shorthand for these functions. You just need to cause
+boost::python::enum_as_int_converters<EnumType> to be
+instantiated, where
+EnumType is your enumerated type. There are two convenient ways to do this:
+
+
+- Explicit instantiation:
+
+
+ template class boost::python::enum_as_int_converters<my_enum>;
+
+
+Some buggy C++ implementations require a class to be instantiated in the same
+namespace in which it is defined. In that case, the simple incantation above becomes:
+
+
+
+ ...
+} // close my_namespace
+
+// drop into namespace python and explicitly instantiate
+namespace boost { namespace python {
+ template class enum_as_int_converters<my_enum_type>;
+}} // namespace boost::python
+
+namespace my_namespace { // re-open my_namespace
+ ...
+
+
+
+
+ - If you have such an implementation, you may find this technique more convenient
+
+// instantiate as base class in any namespace
+struct EnumTypeConverters
+ : boost::python::enum_as_int_converters<EnumType>
+{
+};
+
+
+
+
Either of the above is equivalent to the following declarations:
+
+BOOST_PYTHON_BEGIN_CONVERSION_NAMESPACE // this is a gcc 2.95.2 bug workaround
+
+ MyEnumType from_python(PyObject* x, boost::python::type<MyEnumType>)
+ {
+ return static_cast<MyEnum>(
+ from_python(x, boost::python::type<long>()));
+ }
+
+ MyEnumType from_python(PyObject* x, boost::python::type<const MyEnumType&>)
+ {
+ return static_cast<MyEnum>(
+ from_python(x, boost::python::type<long>()));
+ }
+
+ PyObject* to_python(MyEnumType x)
+ {
+ return to_python(static_cast<long>(x));
+ }
+BOOST_PYTHON_END_CONVERSION_NAMESPACE
+
+
+
This technique defines the conversions of
+MyEnumType in terms of the conversions for the built-in
+ long type.
+
+You may also want to add a bunch of lines like this to your module
+initialization. These bind the corresponding enum values to the appropriate
+names so they can be used from Python:
+
+
+mymodule.add(boost::python::make_ref(enum_value_1), "enum_value_1");
+mymodule.add(boost::python::make_ref(enum_value_2), "enum_value_2");
+...
+
+
+You can also add these to an extension class definition, if your enum happens to
+be local to a class and you want the analogous interface in Python:
+
+
+my_class_builder.add(boost::python::to_python(enum_value_1), "enum_value_1");
+my_class_builder.add(boost::python::to_python(enum_value_2), "enum_value_2");
+...
+
+
+ Next: Pointers and Smart Pointers
+ Previous: Building an Extension Module
+ Up: Top
+
+ © Copyright David Abrahams 2000. Permission to copy, use, modify,
+ sell and distribute this document is granted provided this copyright
+ notice appears in all copies. This document is provided ``as
+ is'' without express or implied warranty, and with no claim as to
+ its suitability for any purpose.
+
+ Updated: Mar 6, 2001
+
+
+
+
+
+ A Simple Example
+
+
+ Suppose we have the following C++ API which we want to expose in
+ Python:
+
+
+#include <string>
+
+namespace { // Avoid cluttering the global namespace.
+
+ // A couple of simple C++ functions that we want to expose to Python.
+ std::string greet() { return "hello, world"; }
+ int square(int number) { return number * number; }
+}
+
+
+
+
+ Here is the C++ code for a python module called getting_started1
+ which exposes the API.
+
+
+#include <boost/python/class_builder.hpp>
+namespace python = boost::python;
+
+BOOST_PYTHON_MODULE_INIT(getting_started1)
+{
+ // Create an object representing this extension module.
+ python::module_builder this_module("getting_started1");
+
+ // Add regular functions to the module.
+ this_module.def(greet, "greet");
+ this_module.def(square, "square");
+}
+
+
+
+ That's it! If we build this shared library and put it on our
+ PYTHONPATH we can now access our C++ functions from
+ Python.
+
+
+>>> import getting_started1
+>>> print getting_started1.greet()
+hello, world
+>>> number = 11
+>>> print number, '*', number, '=', getting_started1.square(number)
+11 * 11 = 121
+
+
+ Next: Exporting Classes
+ Previous: Comparisons with other systems Up:
+ Top
+
+ © Copyright David Abrahams 2000. Permission to copy, use, modify,
+ sell and distribute this document is granted provided this copyright
+ notice appears in all copies. This document is provided "as is" without
+ express or implied warranty, and with no claim as to its suitability
+ for any purpose.
+
+ Updated: Mar 6, 2000
+
+
+
+
+
+ Exporting Classes
+
+
+ Now let's expose a C++ class to Python:
+
+
+#include <iostream>
+#include <string>
+
+namespace { // Avoid cluttering the global namespace.
+
+ // A friendly class.
+ class hello
+ {
+ public:
+ hello(const std::string& country) { this->country = country; }
+ std::string greet() const { return "Hello from " + country; }
+ private:
+ std::string country;
+ };
+
+ // A function taking a hello object as an argument.
+ std::string invite(const hello& w) {
+ return w.greet() + "! Please come soon!";
+ }
+}
+
+
+ To expose the class, we use a class_builder in addition to the
+ module_builder from the previous example. Class member functions
+ are exposed by using the def() member function on the
+ class_builder:
+
+#include <boost/python/class_builder.hpp>
+namespace python = boost::python;
+
+BOOST_PYTHON_MODULE_INIT(getting_started2)
+{
+ // Create an object representing this extension module.
+ python::module_builder this_module("getting_started2");
+
+ // Create the Python type object for our extension class.
+ python::class_builder<hello> hello_class(this_module, "hello");
+
+ // Add the __init__ function.
+ hello_class.def(python::constructor<std::string>());
+ // Add a regular member function.
+ hello_class.def(&hello::greet, "greet");
+
+ // Add invite() as a regular function to the module.
+ this_module.def(invite, "invite");
+
+ // Even better, invite() can also be made a member of hello_class!!!
+ hello_class.def(invite, "invite");
+}
+
+
+Now we can use the class normally from Python:
+
+
+>>> from getting_started2 import *
+>>> hi = hello('California')
+>>> hi.greet()
+'Hello from California'
+>>> invite(hi)
+'Hello from California! Please come soon!'
+>>> hi.invite()
+'Hello from California! Please come soon!'
+
+
+Notes:
+- We expose the class' constructor by calling def() on the
+ class_builder with an argument whose type is
+ constructor<params>, where params
+ matches the list of constructor argument types:
+
+
+
- Regular member functions are defined by calling def() with a
+ member function pointer and its Python name:
+
+
- Any function added to a class whose initial argument matches the class (or
+any base) will act like a member function in Python.
+
+
- To define a nested class, just pass the enclosing
+class_builder (instead of a module_builder) as the
+first argument to the nested class_builder's constructor.
+
+
+
+
+ We can even make a subclass of hello.world:
+
+
+>>> class wordy(hello):
+... def greet(self):
+... return hello.greet(self) + ', where the weather is fine'
+...
+>>> hi2 = wordy('Florida')
+>>> hi2.greet()
+'Hello from Florida, where the weather is fine'
+>>> invite(hi2)
+'Hello from Florida! Please come soon!'
+
+
+ Pretty cool! You can't do that with an ordinary Python extension type!
+
+ Of course, you may now have a slightly empty feeling in the pit of
+ your little pythonic stomach. Perhaps you wanted to see the following
+ wordy invitation:
+
+
+'Hello from Florida, where the weather is fine! Please come soon!'
+
+
+ After all,
invite calls
hello::greet(), and you
+ reimplemented that in your Python subclass,
wordy. If so,
read on...
+
+
+ Next: Overridable virtual functions
+ Previous: A Simple Example Up:
+ Top
+
+ © Copyright David Abrahams 2000. Permission to copy, use, modify,
+ sell and distribute this document is granted provided this copyright
+ notice appears in all copies. This document is provided "as is" without
+ express or implied warranty, and with no claim as to its suitability
+ for any purpose.
+
+ Updated: Mar 6, 2001
+
+
+
+
+ A Brief Introduction to writing Python extension modules
+
+
+ Interfacing any language to Python involves building a module which can
+ be loaded by the Python interpreter, but which isn't written in Python.
+ This is known as an extension module. Many of the built-in Python
+ libraries are constructed in 'C' this way; Python even supplies its
+ fundamental
+ types using the same mechanism. An extension module can be statically
+ linked with the Python interpreter, but it more commonly resides in a
+ shared library or DLL.
+
+ As you can see from The Python Extending
+ and Embedding Tutorial, writing an extension module normally means
+ worrying about
+
+ This last item typically occupies a great deal of code in an extension
+ module. Remember that Python is a completely dynamic language. A callable
+ object receives its arguments in a tuple; it is up to that object to extract
+ those arguments from the tuple, check their types, and raise appropriate
+ exceptions. There are numerous other tedious details that need to be
+ managed; too many to mention here. The Boost Python Library is designed to
+ lift most of that burden.
+
+
+
+ Another obstacle that most people run into eventually when extending
+ Python is that there's no way to make a true Python class in an extension
+ module. The typical solution is to create a new Python type in the
+ extension module, and then write an additional module in 100% Python. The
+ Python module defines a Python class which dispatches to an instance of
+ the extension type, which it contains. This allows users to write
+ subclasses of the class in the Python module, almost as though they were
+ sublcassing the extension type. Aside from being tedious, it's not really
+ the same as having a true class, because there's no way for the user to
+ override a method of the extension type which is called from the
+ extension module. Boost.Python solves this problem by taking advantage of Python's metaclass
+ feature to provide objects which look, walk, and hiss almost exactly
+ like regular Python classes. Boost.Python classes are actually cleaner than
+ Python classes in some subtle ways; a more detailed discussion will
+ follow (someday).
+ Next: Comparisons with Other Systems Up: Top
+
+ © Copyright David Abrahams 2000. Permission to copy, use, modify,
+ sell and distribute this document is granted provided this copyright
+ notice appears in all copies. This document is provided "as is" without
+ express or implied warranty, and with no claim as to its suitability for
+ any purpose.
+
diff --git a/doc/inheritance.html b/doc/inheritance.html
new file mode 100644
index 00000000..56e96872
--- /dev/null
+++ b/doc/inheritance.html
@@ -0,0 +1,166 @@
+
+
+ Inheritance
+
+
+
+ Inheritance
+
+
+
Inheritance in Python
+
+
+ Boost.Python extension classes support single and multiple-inheritance in
+ Python, just like regular Python classes. You can arbitrarily mix
+ built-in Python classes with extension classes in a derived class'
+ tuple of bases. Whenever a Boost.Python extension class is among the bases for a
+ new class in Python, the result is an extension class:
+
+
+>>> class MyPythonClass:
+... def f(): return 'MyPythonClass.f()'
+...
+>>> import my_extension_module
+>>> class Derived(my_extension_module.MyExtensionClass, MyPythonClass):
+... '''This is an extension class'''
+... pass
+...
+>>> x = Derived()
+>>> x.f()
+'MyPythonClass.f()'
+>>> x.g()
+'MyExtensionClass.g()'
+
+
+
+
+
+ Boost.Python also allows us to represent C++ inheritance relationships so that
+ wrapped derived classes may be passed where values, pointers, or
+ references to a base class are expected as arguments. The
+ declare_base member function of
+ class_builder<> is used to establish the relationship
+ between base and derived classes:
+
+
+
+#include <memory> // for std::auto_ptr<>
+
+struct Base {
+ virtual ~Base() {}
+ virtual const char* name() const { return "Base"; }
+};
+
+struct Derived : Base {
+ Derived() : x(-1) {}
+ virtual const char* name() const { return "Derived"; }
+ int x;
+};
+
+std::auto_ptr<Base> derived_as_base() {
+ return std::auto_ptr<Base>(new Derived);
+}
+
+const char* get_name(const Base& b) {
+ return b.name();
+}
+
+int get_derived_x(const Derived& d) {
+ return d.x;
+}
+
+#include <boost/python/class_builder.hpp>
+
+// namespace alias for code brevity
+namespace python = boost::python;
+
+BOOST_PYTHON_MODULE_INIT(my_module)
+{
+ python::module_builder my_module("my_module");
+
+ python::class_builder<Base> base_class(my_module, "Base");
+ base_class.def(python::constructor<>());
+
+ python::class_builder<Derived> derived_class(my_module, "Derived");
+ derived_class.def(python::constructor<>());
+ // Establish the inheritance relationship between Base and Derived
+ derived_class.declare_base(base_class);
+
+ my_module.def(derived_as_base, "derived_as_base");
+ my_module.def(get_name, "get_name");
+ my_module.def(get_derived_x, "get_derived_x");
+}
+
+
+
+
+ Then, in Python:
+
+
+>>> from my_module import *
+>>> base = Base()
+>>> derived = Derived()
+>>> get_name(base)
+'Base'
+
+
+
objects of wrapped class Derived may be passed where Base is expected
+
+
+>>> get_name(derived)
+'Derived'
+
+
+
objects of wrapped class Derived can be passed where Derived is
+expected but where type information has been lost.
+
+
+>>> get_derived_x(derived_as_base())
+-1
+
+
+
+
Inheritance Without Virtual Functions
+
+
+ If for some reason your base class has no virtual functions but you still want
+ to represent the inheritance relationship between base and derived classes,
+ pass the special symbol boost::python::without_downcast as the 2nd parameter
+ to declare_base:
+
+
+
+struct Base2 {};
+struct Derived2 { int f(); };
+
+ ...
+ python::class_builder<Base> base2_class(my_module, "Base2");
+ base2_class.def(python::constructor<>());
+
+ python::class_builder<Derived2> derived2_class(my_module, "Derived2");
+ derived2_class.def(python::constructor<>());
+ derived_class.declare_base(base_class, python::without_downcast);
+
+
+
+
This approach will allow Derived2 objects to be passed where
+ Base2 is expected, but does not attempt to implicitly convert (downcast)
+ smart-pointers to Base2 into Derived2 pointers,
+ references, or values.
+
+
+ Next: Special Method and Operator Support
+ Previous: Function Overloading
+ Up: Top
+
+ © Copyright David Abrahams 2000. Permission to copy, use, modify,
+ sell and distribute this document is granted provided this copyright
+ notice appears in all copies. This document is provided "as is" without
+ express or implied warranty, and with no claim as to its suitability
+ for any purpose.
+
+ Updated: Nov 26, 2000
+
+
+ Function Overloading
+
+
+
An Example
+
+ To expose overloaded functions in Python, simply def() each
+ one with the same Python name:
+
+
+inline int f1() { return 3; }
+inline int f2(int x) { return x + 1; }
+
+class X {
+public:
+ X() : m_value(0) {}
+ X(int n) : m_value(n) {}
+ int value() const { return m_value; }
+ void value(int v) { m_value = v; }
+private:
+ int m_value;
+};
+ ...
+
+BOOST_PYTHON_MODULE_INIT(overload_demo)
+{
+ try
+ {
+ boost::python::module_builder overload_demo("overload_demo");
+ // Overloaded functions at module scope
+ overload_demo.def(f1, "f");
+ overload_demo.def(f2, "f");
+
+ boost::python::class_builder<X> x_class(overload_demo, "X");
+ // Overloaded constructors
+ x_class.def(boost::python::constructor<>());
+ x_class.def(boost::python::constructor<int>());
+
+ // Overloaded member functions
+ x_class.def((int (X::*)() const)&X::value, "value");
+ x_class.def((void (X::*)(int))&X::value, "value");
+ ...
+
+
+
+
+ Now in Python:
+
+
+>>> from overload_demo import *
+>>> x0 = X()
+>>> x1 = X(1)
+>>> x0.value()
+0
+>>> x1.value()
+1
+>>> x0.value(3)
+>>> x0.value()
+3
+>>> X('hello')
+TypeError: No overloaded functions match (X, string). Candidates are:
+void (*)()
+void (*)(int)
+>>> f()
+3
+>>> f(4)
+5
+
+
+
+
Discussion
+
+ Notice that overloading in the Python module was produced three ways:
+ - by combining the non-overloaded C++ functions
int f1()
+ and int f2(int) and exposing them as f in Python.
+ - by exposing the overloaded constructors of
class X
+ - by exposing the overloaded member functions
X::value.
+
+
+ Techniques 1. and 3. above are really alternatives. In case 3, you need
+ to form a pointer to each of the overloaded functions. The casting
+ syntax shown above is one way to do that in C++. Case 1 does not require
+ complicated-looking casts, but may not be viable if you can't change
+ your C++ interface. N.B. There's really nothing unsafe about casting an
+ overloaded (member) function address this way: the compiler won't let
+ you write it at all unless you get it right.
+
+
An Alternative to Casting
+
+ This approach is not neccessarily better, but may be preferable for some
+ people who have trouble writing out the types of (member) function
+ pointers or simply prefer to avoid all casts as a matter of principle:
+
+
+// Forwarding functions for X::value
+inline void set_x_value(X& self, int v) { self.value(v); }
+inline int get_x_value(X& self) { return self.value(); }
+ ...
+ // Overloaded member functions
+ x_class.def(set_x_value, "value");
+ x_class.def(get_x_value, "value");
+
+
+
Here we are taking advantage of the ability to expose C++ functions at
+namespace scope as Python member functions.
+
+
Overload Resolution
+
+ The function overload resolution mechanism works as follows:
+
+
+
+ - Attribute lookup for extension classes proceeds in the
+ usual Python way using a depth-first, left-to-right search. When a
+ class is found which has a matching attribute, only functions overloaded
+ in the context of that class are candidates for overload resolution. In
+ this sense, overload resolution mirrors the C++ mechanism, where a name
+ in a derived class ``hides'' all functions with the same name from a base
+ class.
+
+
+
- Within a name-space context (extension class or module), overloaded
+ functions are tried in the same order they were
+
def()ed. The first function whose signature can be made to
+ match each argument passed is the one which is ultimately called.
+ This means in particular that you cannot overload the same function on
+ both ``int'' and ``float'' because Python
+ automatically converts either of the two types into the other one.
+ If the ``float'' overload is found first, it is used
+ also used for arguments of type ``int'' as well, and the
+ ``int'' version of the function is never invoked.
+
+
+
+ Next: Inheritance
+ Previous: Overridable Virtual Functions
+ Up: Top
+
+ © Copyright David Abrahams 2001. Permission to copy, use, modify,
+ sell and distribute this document is granted provided this copyright
+ notice appears in all copies. This document is provided ``as
+ is'' without express or implied warranty, and with no claim as to
+ its suitability for any purpose.
+
+ Updated: Mar 6, 2001
+
Overridable Virtual Functions
+
+
+ In the previous example we exposed a simple
+ C++ class in Python and showed that we could write a subclass. We even
+ redefined one of the functions in our derived class. Now we will learn
+ how to make the function behave virtually when called from C++.
+
+
+
+
+In this example, it is assumed that hello::greet() is a virtual
+member function:
+
+
+class hello
+{
+ public:
+ hello(const std::string& country) { this->country = country; }
+ virtual std::string greet() const { return "Hello from " + country; }
+ virtual ~hello(); // Good practice
+ ...
+};
+
+
+
+ We'll need a derived class* to help us
+ dispatch the call to Python. In our derived class, we need the following
+ elements:
+
+
+
+ - A
PyObject* data member (usually
+ called self) that holds a pointer to the Python object corresponding
+ to our C++ hello instance.
+
+ - For each exposed constructor of the
+ base class T, a constructor which takes the same parameters preceded by an initial
+
PyObject* argument. The initial argument should be stored in the self data
+ member described above.
+
+ - If the class being wrapped is ever returned by
+ value from a wrapped function, be sure you do the same for the
+ T's copy constructor: you'll need a constructor taking arguments
+ (PyObject*, const T&).
+
+
- An implementation of each virtual function you may
+ wish to override in Python which uses
+ callback<return-type>::call_method(self, "name", args...) to call
+ the Python override.
+
+
- For each non-pure virtual function meant to be
+ overridable from Python, a static member function (or a free function) taking
+ a reference or pointer to the T as the first parameter and which
+ forwards any additional parameters neccessary to the default
+ implementation of the virtual function. See also this
+ note if the base class virtual function is private.
+
+
+
+
+struct hello_callback : hello
+{
+ // hello constructor storing initial self_ parameter
+ hello_callback(PyObject* self_, const std::string& x) // 2
+ : hello(x), self(self_) {}
+
+ // In case hello is returned by-value from a wrapped function
+ hello_callback(PyObject* self_, const hello& x) // 3
+ : hello(x), self(self_) {}
+
+ // Override greet to call back into Python
+ std::string greet() const // 4
+ { return boost::python::callback<std::string>::call_method(self, "greet"); }
+
+ // Supplies the default implementation of greet
+ static std::string default_greet(const hello& self_) const // 5
+ { return self_.hello::greet(); }
+ private:
+ PyObject* self; // 1
+};
+
+
+
+ Finally, we add hello_callback to the
+ class_builder<> declaration in our module initialization
+ function, and when we define the function, we must tell Boost.Python about the default
+ implementation:
+
+
+// Create the Python type object for our extension class
+boost::python::class_builder<hello,hello_callback> hello_class(hello, "hello");
+// Add a virtual member function
+hello_class.def(&hello::greet, "greet", &hello_callback::default_greet);
+
+
+
+ Now our Python subclass of hello behaves as expected:
+
+
+>>> class wordy(hello):
+... def greet(self):
+... return hello.greet(self) + ', where the weather is fine'
+...
+>>> hi2 = wordy('Florida')
+>>> hi2.greet()
+'Hello from Florida, where the weather is fine'
+>>> invite(hi2)
+'Hello from Florida, where the weather is fine! Please come soon!'
+
+
+ *You may ask, "Why do we need this derived
+ class? This could have been designed so that everything gets done right
+ inside of hello." 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. To unintrusively hook into the virtual functions so that a Python
+ override may be called, we must use a derived class.
+
+
Pure Virtual Functions
+
+
+ A pure virtual function with no implementation is actually a lot easier to
+ deal with than a virtual function with a default implementation. First of
+ all, you obviously don't need to supply
+ a default implementation. Secondly, you don't need to call
+ def() on the extension_class<> instance
+ for the virtual function. In fact, you wouldn't want to: if the
+ corresponding attribute on the Python class stays undefined, you'll get an
+ AttributeError in Python when you try to call the function,
+ indicating that it should have been implemented. For example:
+
+
+struct baz {
+ virtual int pure(int) = 0;
+ int calls_pure(int x) { return pure(x) + 1000; }
+};
+
+struct baz_callback {
+ int pure(int x) { boost::python::callback<int>::call_method(m_self, "pure", x); }
+};
+
+BOOST_PYTHON_MODULE_INIT(foobar)
+{
+ boost::python::module_builder foobar("foobar");
+ boost::python::class_builder<baz,baz_callback> baz_class("baz");
+ baz_class.def(&baz::calls_pure, "calls_pure");
+}
+
+
+
+ Now in Python:
+
+
+>>> from foobar import baz
+>>> x = baz()
+>>> x.pure(1)
+Traceback (innermost last):
+ File "<stdin>", line 1, in ?
+AttributeError: pure
+>>> x.calls_pure(1)
+Traceback (innermost last):
+ File "<stdin>", line 1, in ?
+AttributeError: pure
+>>> class mumble(baz):
+... def pure(self, x): return x + 1
+...
+>>> y = mumble()
+>>> y.pure(99)
+100
+>>> y.calls_pure(99)
+1100
+
+
+Private Non-Pure Virtual Functions
+
+This is one area where some minor intrusiveness on the wrapped library is
+required. Once it has been overridden, the only way to call the base class
+implementation of a private virtual function is to make the derived class a
+friend of the base class. You didn't hear it from me, but most C++
+implementations will allow you to change the declaration of the base class in
+this limited way without breaking binary compatibility (though it will certainly
+break the ODR).
+
+
+
+ Next: Function Overloading
+ Previous: Exporting Classes
+ Up: Top
+
+ © Copyright David Abrahams 2001. Permission to copy, use, modify,
+ sell and distribute this document is granted provided this copyright
+ notice appears in all copies. This document is provided "as is" without
+ express or implied warranty, and with no claim as to its suitability for
+ any purpose.
+
+ Updated: Mar 21, 2001
+
diff --git a/doc/pickle.html b/doc/pickle.html
new file mode 100644
index 00000000..994a78ab
--- /dev/null
+++ b/doc/pickle.html
@@ -0,0 +1,272 @@
+
+
+
Boost.Python Pickle Support
+
+
+
+
+
+
+
Boost.Python Pickle Support
+
+Pickle is a Python module for object serialization, also known
+as persistence, marshalling, or flattening.
+
+
+It is often necessary to save and restore the contents of an object to
+a file. One approach to this problem is to write a pair of functions
+that read and write data from a file in a special format. A powerful
+alternative approach is to use Python's pickle module. Exploiting
+Python's ability for introspection, the pickle module recursively
+converts nearly arbitrary Python objects into a stream of bytes that
+can be written to a file.
+
+
+The Boost Python Library supports the pickle module by emulating the
+interface implemented by Jim Fulton's ExtensionClass module that is
+included in the
+ZOPE
+distribution.
+This interface is similar to that for regular Python classes as
+described in detail in the
+Python Library Reference for pickle.
+
+
+
The Boost.Python Pickle Interface
+
+At the user level, the Boost.Python pickle interface involves three special
+methods:
+
+
+-
+__getinitargs__
+
-
+ When an instance of a Boost.Python extension class is pickled, the
+ pickler tests if the instance has a __getinitargs__ method.
+ This method must return a Python tuple (it is most convenient to use
+ a boost::python::tuple). When the instance is restored by the
+ unpickler, the contents of this tuple are used as the arguments for
+ the class constructor.
+
+
+ If __getinitargs__ is not defined, the class constructor
+ will be called without arguments.
+
+
+
-
+__getstate__
+
+
-
+ When an instance of a Boost.Python extension class is pickled, the
+ pickler tests if the instance has a __getstate__ method.
+ This method should return a Python object representing the state of
+ the instance.
+
+
+ If __getstate__ is not defined, the instance's
+ __dict__ is pickled (if it is not empty).
+
+
+
-
+__setstate__
+
+
-
+ When an instance of a Boost.Python extension class is restored by the
+ unpickler, it is first constructed using the result of
+ __getinitargs__ as arguments (see above). Subsequently the
+ unpickler tests if the new instance has a __setstate__
+ method. If so, this method is called with the result of
+ __getstate__ (a Python object) as the argument.
+
+
+ If __setstate__ is not defined, the result of
+ __getstate__ must be a Python dictionary. The items of this
+ dictionary are added to the instance's __dict__.
+
+
+
+If both
__getstate__ and
__setstate__ are defined,
+the Python object returned by
__getstate__ need not be a
+dictionary. The
__getstate__ and
__setstate__ methods
+can do what they want.
+
+
+
Pitfalls and Safety Guards
+
+In Boost.Python extension modules with many extension classes,
+providing complete pickle support for all classes would be a
+significant overhead. In general complete pickle support should only be
+implemented for extension classes that will eventually be pickled.
+However, the author of a Boost.Python extension module might not
+anticipate correctly which classes need support for pickle.
+Unfortunately, the pickle protocol described above has two important
+pitfalls that the end user of a Boost.Python extension module might not
+be aware of:
+
+
+-
+Pitfall 1:
+Both __getinitargs__ and __getstate__ are not defined.
+
+
-
+ In this situation the unpickler calls the class constructor without
+ arguments and then adds the __dict__ that was pickled by
+ default to that of the new instance.
+
+
+ However, most C++ classes wrapped with Boost.Python will have member
+ data that are not restored correctly by this procedure. To alert the
+ user to this problem, a safety guard is provided. If both
+ __getinitargs__ and __getstate__ are not defined,
+ Boost.Python tests if the class has an attribute
+ __dict_defines_state__. An exception is raised if this
+ attribute is not defined:
+
+
+ RuntimeError: Incomplete pickle support (__dict_defines_state__ not set)
+
+
+ In the rare cases where this is not the desired behavior, the safety
+ guard can deliberately be disabled. The corresponding C++ code for
+ this is, e.g.:
+
+
+ class_builder<your_class> py_your_class(your_module, "your_class");
+ py_your_class.dict_defines_state();
+
+
+ It is also possible to override the safety guard at the Python level.
+ E.g.:
+
+
+ import your_bpl_module
+ class your_class(your_bpl_module.your_class):
+ __dict_defines_state__ = 1
+
+
+
+
-
+Pitfall 2:
+__getstate__ is defined and the instance's __dict__ is not empty.
+
+
-
+ The author of a Boost.Python extension class might provide a
+ __getstate__ method without considering the possibilities
+ that:
+
+
+
+ -
+ his class is used in Python as a base class. Most likely the
+ __dict__ of instances of the derived class needs to be
+ pickled in order to restore the instances correctly.
+
+
+
-
+ the user adds items to the instance's __dict__ directly.
+ Again, the __dict__ of the instance then needs to be
+ pickled.
+
+
+
+
+ To alert the user to this highly unobvious problem, a safety guard is
+ provided. If __getstate__ is defined and the instance's
+ __dict__ is not empty, Boost.Python tests if the class has
+ an attribute __getstate_manages_dict__. An exception is
+ raised if this attribute is not defined:
+
+
+ RuntimeError: Incomplete pickle support (__getstate_manages_dict__ not set)
+
+
+ To resolve this problem, it should first be established that the
+ __getstate__ and __setstate__ methods manage the
+ instances's __dict__ correctly. Note that this can be done
+ both at the C++ and the Python level. Finally, the safety guard
+ should intentionally be overridden. E.g. in C++:
+
+
+ class_builder<your_class> py_your_class(your_module, "your_class");
+ py_your_class.getstate_manages_dict();
+
+
+ In Python:
+
+
+ import your_bpl_module
+ class your_class(your_bpl_module.your_class):
+ __getstate_manages_dict__ = 1
+ def __getstate__(self):
+ # your code here
+ def __setstate__(self, state):
+ # your code here
+
+
+
+
+
Practical Advice
+
+
+-
+ Avoid using __getstate__ if the instance can also be
+ reconstructed by way of __getinitargs__. This automatically
+ avoids Pitfall 2.
+
+
+
-
+ If __getstate__ is required, include the instance's
+ __dict__ in the Python object that is returned.
+
+
+
+
+
Examples
+
+There are three files in
boost/libs/python/example that
+show how so provide pickle support.
+
+
+
+ The C++ class in this example can be fully restored by passing the
+ appropriate argument to the constructor. Therefore it is sufficient
+ to define the pickle interface method
__getinitargs__.
+
+
+
+ The C++ class in this example contains member data that cannot be
+ restored by any of the constructors. Therefore it is necessary to
+ provide the
__getstate__/
__setstate__ pair of
+ pickle interface methods.
+
+
+ For simplicity, the __dict__ is not included in the result
+ of __getstate__. This is not generally recommended, but a
+ valid approach if it is anticipated that the object's
+ __dict__ will always be empty. Note that the safety guards
+ will catch the cases where this assumption is violated.
+
+
+
+ This example is similar to
pickle2.cpp. However, the
+ object's
__dict__ is included in the result of
+
__getstate__. This requires more code but is unavoidable
+ if the object's
__dict__ is not always empty.
+
+
+© Copyright Ralf W. Grosse-Kunstleve 2001. Permission to copy,
+use, modify, sell and distribute this document is granted provided this
+copyright notice appears in all copies. This document is provided "as
+is" without express or implied warranty, and with no claim as to its
+suitability for any purpose.
+
+
+Updated: March 21, 2001
+
+
+ Pointers
+
+
+
+
+
+In general, raw pointers passed to or returned from functions are problematic
+for Boost.Python because pointers have too many potential meanings. Is it an iterator?
+A pointer to a single element? An array? When used as a return value, is the
+caller expected to manage (delete) the pointed-to object or is the pointer
+really just a reference? If the latter, what happens to Python references to the
+referent when some C++ code deletes it?
+
+There are a few cases in which pointers are converted automatically:
+
+
+- Both const- and non-const pointers to wrapped class instances can be passed
+to C++ functions.
+
+
- Values of type
const char* are interpreted as
+null-terminated 'C' strings and when passed to or returned from C++ functions are
+converted from/to Python strings.
+
+
+
+
Can you avoid the problem?
+
+
My first piece of advice to anyone with a case not covered above is
+``find a way to avoid the problem.'' For example, if you have just one
+or two functions that return a pointer to an individual const
+T, and T is a wrapped class, you may be able to write a ``thin
+converting wrapper'' over those two functions as follows:
+
+
+const Foo* f(); // original function
+const Foo& f_wrapper() { return *f(); }
+ ...
+my_module.def(f_wrapper, "f");
+
+
+Foo must have a public copy constructor for this technique to work, since Boost.Python
+converts const T& values to_python by copying the T
+value into a new extension instance.
+
+
Dealing with the problem
+
+
The first step in handling the remaining cases is to figure out what the pointer
+means. Several potential solutions are provided in the examples that follow:
+
+
Returning a pointer to a wrapped type
+
+
Returning a const pointer
+
+
If you have lots of functions returning a const T* for some
+wrapped T, you may want to provide an automatic
+to_python conversion function so you don't have to write lots of
+thin wrappers. You can do this simply as follows:
+
+
+BOOST_PYTHON_BEGIN_CONVERSION_NAMESPACE // this is a gcc 2.95.2 bug workaround
+ PyObject* to_python(const Foo* p) {
+ return to_python(*p); // convert const Foo* in terms of const Foo&
+ }
+BOOST_PYTHON_END_CONVERSION_NAMESPACE
+
+
+
If you can't (afford to) copy the referent, or the pointer is non-const
+
+
If the wrapped type doesn't have a public copy constructor, if copying is
+extremely costly (remember, we're dealing with Python here), or if the
+pointer is non-const and you really need to be able to modify the referent from
+Python, you can use the following dangerous trick. Why dangerous? Because python
+can not control the lifetime of the referent, so it may be destroyed by your C++
+code before the last Python reference to it disappears:
+
+
+BOOST_PYTHON_BEGIN_CONVERSION_NAMESPACE // this is a gcc 2.95.2 bug workaround
+ PyObject* to_python(Foo* p)
+ {
+ return boost::python::python_extension_class_converters<Foo>::smart_ptr_to_python(p);
+ }
+
+ PyObject* to_python(const Foo* p)
+ {
+ return to_python(const_cast<Foo*>(p));
+ }
+BOOST_PYTHON_END_CONVERSION_NAMESPACE
+
+
+This will cause the Foo* to be treated as though it were an owning smart
+pointer, even though it's not. Be sure you don't use the reference for anything
+from Python once the pointer becomes invalid, though. Don't worry too much about
+the
const_cast<> above: Const-correctness is completely lost
+to Python anyway!
+
+
[In/]Out Parameters and Immutable Types
+
+
If you have an interface that uses non-const pointers (or references) as
+in/out parameters to types which in Python are immutable (e.g. int, string),
+there simply is no way to get the same interface in Python. You must
+resort to transforming your interface with simple thin wrappers as shown below:
+
+const void f(int* in_out_x); // original function
+const int f_wrapper(int in_x) { f(in_x); return in_x; }
+ ...
+my_module.def(f_wrapper, "f");
+
+
+
Of course, [in/]out parameters commonly occur only when there is already a
+return value. You can handle this case by returning a Python tuple:
+
+typedef unsigned ErrorCode;
+const char* f(int* in_out_x); // original function
+ ...
+#include <boost/python/objects.hpp>
+const boost::python::tuple f_wrapper(int in_x) {
+ const char* s = f(in_x);
+ return boost::python::tuple(s, in_x);
+}
+ ...
+my_module.def(f_wrapper, "f");
+
+
Now, in Python:
+
+>>> str,out_x = f(3)
+
+
+
+ Previous: Enums
+ Up: Top
+
+ © Copyright David Abrahams 2000. Permission to copy, use, modify,
+ sell and distribute this document is granted provided this copyright
+ notice appears in all copies. This document is provided "as is" without
+ express or implied warranty, and with no claim as to its suitability
+ for any purpose.
+
+ Updated: Nov 26, 2000
+
+
+
+
+
+
Rich Comparisons
+
+
+In Python versions up to and including Python 2.0, support for
+implementing comparisons on user-defined classes and extension types
+was quite simple. Classes could implement a
__cmp__ method
+that was given two instances of a class as arguments, and could only
+return
0 if they were equal or
+1 or
-1 if
+they were not. The method could not raise an exception or return
+anything other than an integer value.
+In Python 2.1,
Rich Comparisons were added (see
+
PEP 207).
+Python classes can now individually overload each of the <, <=,
+>, >=, ==, and != operations.
+
+
+For more detailed information, search for "rich comparison"
+here.
+
+
+Boost.Python supports both automatic overloading and manual overloading
+of the Rich Comparison operators. The compile-time support is
+independent of the Python version that is used when compiling
+Boost.Python extension modules. That is, op_lt for example can
+always be used, and the C++ operator< will always be bound
+to the Python method __lt__. However, the run-time
+behavior will depend on the Python version.
+
+
+With Python versions before 2.1, the Rich Comparison operators will not
+be called by Python when any of the six comparison operators
+(<, <=, ==, !=,
+>, >=) is used in an expression. The only way
+to access the corresponding methods is to call them explicitly, e.g.
+a.__lt__(b). Only with Python versions 2.1 or higher will
+expressions like a < b work as expected.
+
+
+To support Rich Comparisions, the Python C API was modified between
+Python versions 2.0 and 2.1. A new slot was introduced in the
+PyTypeObject structure: tp_richcompare. For backwards
+compatibility, a flag (Py_TPFLAGS_HAVE_RICHCOMPARE) has to be
+set to signal to the Python interpreter that Rich Comparisions are
+supported by a particular type.
+There is only one flag for all the six comparison operators.
+When any of the six operators is wrapped automatically or
+manually, Boost.Python will set this flag. Attempts to use comparison
+operators at the Python level that are not defined at the C++ level
+will then lead to an AttributeError when the Python 2.1
+(or higher) interpreter tries, e.g., a.__lt__(b). That
+is, in general all six operators should be supplied. Automatically
+wrapped operators and manually wrapped operators can be mixed. For
+example:
+ boost::python::class_builder<code> py_code(this_module, "code");
+
+ py_code.def(boost::python::constructor<>());
+ py_code.def(boost::python::constructor<int>());
+ py_code.def(boost::python::operators<( boost::python::op_eq
+ | boost::python::op_ne)>());
+ py_code.def(NotImplemented, "__lt__");
+ py_code.def(NotImplemented, "__le__");
+ py_code.def(NotImplemented, "__gt__");
+ py_code.def(NotImplemented, "__ge__");
+
+
+
NotImplemented is a simple free function that (currently) has
+to be provided by the user. For example:
+ boost::python::ref
+ NotImplemented(const code&, const code&) {
+ return
+ boost::python::ref(Py_NotImplemented, boost::python::ref::increment_count);
+ }
+
+
+See also:
+
+
+
+© Copyright Nicholas K. Sauter & Ralf W. Grosse-Kunstleve 2001.
+Permission to copy, use, modify, sell and distribute this document is
+granted provided this copyright notice appears in all copies. This
+document is provided "as is" without express or implied warranty, and
+with no claim as to its suitability for any purpose.
+
+
+Updated: July 2001
+
+
+
+ 
Special Method and
+ Operator Support
+
+
+ Overview
+
+
+ Boost.Python supports all of the standard
+ special method names supported by real Python class instances
+ except __complex__ (more on the reasons below). In addition, it can quickly and easily expose
+ suitable C++ functions and operators as Python operators. The following
+ categories of special method names are supported:
+
+
+
+
+
+
+ Python provides a number of special operators for basic customization of a
+ class. Only a brief description is provided below; more complete
+ documentation can be found here.
+
+
+ -
+ __init__(self)
+
-
+ Initialize the class instance. For extension classes not subclassed in
+ Python,
__init__ is defined by
+
+ my_class.def(boost::python::constructor<...>())
+
+ (see section "A Simple Example Using Boost.Python").
+
-
+ __del__(self)
+
-
+ Called when the extension instance is about to be destroyed. For extension classes
+ not subclassed in Python,
__del__ is always defined automatically by
+ means of the class' destructor.
+ -
+ __repr__(self)
+
-
+ Create a string representation from which the object can be
+ reconstructed.
+
-
+ __str__(self)
+
-
+ Create a string representation which is suitable for printing.
+
-
+ __lt__(self, other)
+
-
+ __le__(self, other)
+
-
+ __eq__(self, other)
+
-
+ __ne__(self, other)
+
-
+ __gt__(self, other)
+
-
+ __ge__(self, other)
+
-
+ Rich Comparison methods.
+ New in Python 2.1.
+ See Rich Comparisons.
+
-
+ __cmp__(self, other)
+
-
+ Three-way compare function.
+ See Rich Comparisons.
+
-
+ __hash__(self)
+
-
+ Called for the key object for dictionary operations, and by the
+ built-in function hash(). Should return a 32-bit integer usable as a
+ hash value for dictionary operations (only allowed if __cmp__ is also
+ defined)
+
-
+ __nonzero__(self)
+
-
+ called if the object is used as a truth value (e.g. in an if
+ statement)
+
-
+ __call__ (self[, args...])
+
-
+Called when the instance is ``called'' as a function; if this method
+is defined,
x(arg1, arg2, ...) is a shorthand for
+x.__call__(arg1, arg2, ...).
+
+
+ If we have a suitable C++ function that supports any of these features,
+ we can export it like any other function, using its Python special name.
+ For example, suppose that class
Foo provides a string
+ conversion function:
+
+std::string to_string(Foo const& f)
+{
+ std::ostringstream s;
+ s << f;
+ return s.str();
+}
+
+ This function would be wrapped like this:
+
+boost::python::class_builder<Foo> foo_class(my_module, "Foo");
+foo_class.def(&to_string, "__str__");
+
+ Note that Boost.Python also supports
automatic wrapping of
+
__str__ and
__cmp__. This is explained in the
next section and the
Table of
+ Automatically Wrapped Methods.
+
+
+
+
+ Numeric operators can be exposed manually, by defing C++
+ [member] functions that support the standard Python numeric
+ protocols. This is the same basic technique used to expose
+ to_string() as __str__() above, and is covered in detail below. Boost.Python also supports
+ automatic wrapping of numeric operators whenever they have already
+ been defined in C++.
+
+
+
+
+Supose we wanted to expose a C++ class
+ BigNum which supports addition. That is, in C++ we can write:
+
+BigNum a, b, c;
+...
+c = a + b;
+
+
+ To enable the same functionality in Python, we first wrap the
+ BigNum class as usual:
+
+boost::python::class_builder<BigNum> bignum_class(my_module, "BigNum");
+bignum_class.def(boost::python::constructor<>());
+...
+
+ Then we export the addition operator like this:
+
+
+bignum_class.def(boost::python::operators<boost::python::op_add>());
+
+
+ Since BigNum also supports subtraction, multiplication, and division, we
+ want to export those also. This can be done in a single command by
+ ``or''ing the operator identifiers together (a complete list of these
+ identifiers and the corresponding operators can be found in the
Table of Automatically Wrapped Methods):
+
+bignum_class.def(boost::python::operators<(boost::python::op_sub | boost::python::op_mul | boost::python::op_div)>());
+
+ [Note that the or-expression must be enclosed in parentheses.]
+
+
This form of operator definition can be used to wrap unary and
+ homogeneous binary operators (a homogeneous operator has left and
+ right operands of the same type). Now suppose that our C++ library also
+ supports addition of BigNums and plain integers:
+
+
+BigNum a, b;
+int i;
+...
+a = b + i;
+a = i + b;
+
+ To wrap these heterogeneous operators, we need to specify a different type for
+ one of the operands. This is done using the
right_operand
+ and
left_operand templates:
+
+bignum_class.def(boost::python::operators<boost::python::op_add>(), boost::python::right_operand<int>());
+bignum_class.def(boost::python::operators<boost::python::op_add>(), boost::python::left_operand<int>());
+
+ Boost.Python uses overloading to register several variants of the same
+ operation (more on this in the context of
+ coercion). Again, several operators can be exported at once:
+
+bignum_class.def(boost::python::operators<(boost::python::op_sub | boost::python::op_mul | boost::python::op_div)>(),
+ boost::python::right_operand<int>());
+bignum_class.def(boost::python::operators<(boost::python::op_sub | boost::python::op_mul | boost::python::op_div)>(),
+ boost::python::left_operand<int>());
+
+ The type of the operand not mentioned is taken from the class being wrapped. In
+ our example, the class object is
bignum_class, and thus the
+ other operand's type is ``
BigNum const&''. You can override
+ this default by explicitly specifying a type in the
+ operators template:
+
+bignum_class.def(boost::python::operators<boost::python::op_add, BigNum>(), boost::python::right_operand<int>());
+
+
+ Note that automatic wrapping uses the expression
+ ``left + right'' and can be used uniformly
+ regardless of whether the C++ operators are supplied as free functions
+
+
+BigNum operator+(BigNum, BigNum)
+
+
+ or as member functions
+
+
+BigNum::operator+(BigNum).
+
+
+
+ For the Python built-in functions pow() and
+ abs(), there is no corresponding C++ operator. Instead,
+ automatic wrapping attempts to wrap C++ functions of the same name. This
+ only works if those functions are known in namespace
+ python. On some compilers (e.g. MSVC) it might be
+ necessary to add a using declaration prior to wrapping:
+
+
+namespace boost { namespace python {
+ using my_namespace::pow;
+ using my_namespace::abs;
+}
+
+
+
+
+ In some cases, automatic wrapping of operators may be impossible or
+ undesirable. Suppose, for example, that the modulo operation for BigNums
+ is defined by a set of functions called mod():
+
+
+BigNum mod(BigNum const& left, BigNum const& right);
+BigNum mod(BigNum const& left, int right);
+BigNum mod(int left, BigNum const& right);
+
+
+
+ For automatic wrapping of the modulo function, operator%() would be needed.
+ Therefore, the mod()-functions must be wrapped manually. That is, we have
+ to export them explicitly with the Python special name "__mod__":
+
+
+bignum_class.def((BigNum (*)(BigNum const&, BigNum const&))&mod, "__mod__");
+bignum_class.def((BigNum (*)(BigNum const&, int))&mod, "__mod__");
+
+
+
+ The third form of mod() (with int as left operand) cannot
+ be wrapped directly. We must first create a function rmod() with the
+ operands reversed:
+
+
+BigNum rmod(BigNum const& right, int left)
+{
+ return mod(left, right);
+}
+
+
+ This function must be wrapped under the name "__rmod__" (standing for "reverse mod"):
+
+
+bignum_class.def(&rmod, "__rmod__");
+
+
+ Many of the possible operator names can be found in the
Table of Automatically Wrapped Methods. Special treatment is
+ necessary to export the
ternary pow operator.
+
+
+ Automatic and manual wrapping can be mixed arbitrarily. Note that you
+ cannot overload the same operator for a given extension class on both
+ ``int'' and ``float'', because Python implicitly
+ converts these types into each other. Thus, the overloaded variant
+ found first (be it ``int`` or ``float'') will be
+ used for either of the two types.
+
+
+
+ Boost.Python can also be used to expose inplace numeric operations
+ (i.e., += and so forth). These operators must be wrapped
+ manually, as described in the previous section. For example, suppose
+ the class BigNum has an operator+=:
+
+
+BigNum& operator+= (BigNum const& right);
+
+
+ This can be exposed by first writing a wrapper function:
+
+
+BigNum& iadd (BigNum& self, const BigNum& right)
+{
+ return self += right;
+}
+
+
+ and then exposing the wrapper with
+
+
+bignum_class.def(&iadd, "__iadd__");
+
+
+
+
+
+
+
+
+ Plain Python can only execute operators with identical types on the left
+ and right hand side. If it encounters an expression where the types of
+ the left and right operand differ, it tries to coerce these types to a
+ common type before invoking the actual operator. Implementing good
+ coercion functions can be difficult if many type combinations must be
+ supported.
+
+ Boost.Python solves this problem the same way that C++ does: with overloading. This technique drastically
+ simplifies the code neccessary to support operators: you just register
+ operators for all desired type combinations, and Boost.Python automatically
+ ensures that the correct function is called in each case; there is no
+ need for user-defined coercion functions. To enable operator
+ overloading, Boost.Python provides a standard coercion which is implicitly
+ registered whenever automatic operator wrapping is used.
+
+ If you wrap all operator functions manually, but still want to use
+ operator overloading, you have to register the standard coercion
+ function explicitly:
+
+
+// this is not necessary if automatic operator wrapping is used
+bignum_class.def_standard_coerce();
+
+
+ If you encounter a situation where you absolutely need a customized
+ coercion, you can still define the "__coerce__" operator manually. The signature
+ of a coercion function should look like one of the following (the first is
+ the safest):
+
+
+boost::python::tuple custom_coerce(boost::python::reference left, boost::python::reference right);
+boost::python::tuple custom_coerce(PyObject* left, PyObject* right);
+PyObject* custom_coerce(PyObject* left, PyObject* right);
+
+
+ The resulting
tuple must contain two elements which
+ represent the values of
left and
right
+ converted to the same type. Such a function is wrapped as usual:
+
+
+// this must be called before any use of automatic operator
+// wrapping or a call to some_class.def_standard_coerce()
+some_class.def(&custom_coerce, "__coerce__");
+
+
+ Note that the standard coercion (defined by use of automatic
+ operator wrapping on a
class_builder or a call to
+
class_builder::def_standard_coerce()) will never be applied if
+ a custom coercion function has been registered. Therefore, in
+ your coercion function you should call
+
+
+boost::python::standard_coerce(left, right);
+
+
+ for all cases that you don't want to handle yourself.
+
+
+
+
+ In addition to the usual binary pow(x, y) operator (meaning
+ xy), Python also provides a ternary variant that implements
+ xy mod z, presumably using a more efficient algorithm than
+ concatenation of power and modulo operators. Automatic operator wrapping
+ can only be used with the binary variant. Ternary pow() must
+ always be wrapped manually. For a homgeneous ternary pow(),
+ this is done as usual:
+
+
+BigNum power(BigNum const& first, BigNum const& second, BigNum const& modulus);
+typedef BigNum (ternary_function1)(const BigNum&, const BigNum&, const BigNum&);
+...
+bignum_class.def((ternary_function1)&power, "__pow__");
+
+
+ If you want to support this function with non-uniform argument
+ types, wrapping is a little more involved. Suppose you have to wrap:
+
+
+BigNum power(BigNum const& first, int second, int modulus);
+BigNum power(int first, BigNum const& second, int modulus);
+BigNum power(int first, int second, BigNum const& modulus);
+
+
+ The first variant can be wrapped as usual:
+
+
+typedef BigNum (ternary_function2)(const BigNum&, int, int);
+bignum_class.def((ternary_function2)&power, "__pow__");
+
+
+ In the second variant, however,
BigNum appears only as second
+ argument, and in the last one it's the third argument. These functions
+ must be presented to Boost.Python such that that the
BigNum
+ argument appears in first position:
+
+
+BigNum rpower(BigNum const& second, int first, int modulus)
+{
+ return power(first, second, modulus);
+}
+
+BigNum rrpower(BigNum const& modulus, int first, int second)
+{
+ return power(first, second, modulus);
+}
+
+
+
These functions must be wrapped under the names "__rpow__" and "__rrpow__"
+ respectively:
+
+
+bignum_class.def((ternary_function2)&rpower, "__rpow__");
+bignum_class.def((ternary_function2)&rrpower, "__rrpow__");
+
+
+Note that "__rrpow__" is an extension not present in plain Python.
+
+
+
+ Boost.Python can automatically wrap the following
+ special methods:
+
+
+
+
+ |
+ Python Operator Name
+ |
+ Python Expression
+ |
+ C++ Operator Id
+ |
+ C++ Expression Used For Automatic Wrapping
+ with cpp_left = from_python(left,
+ type<Left>()),
+ cpp_right = from_python(right,
+ type<Right>()),
+ and cpp_oper = from_python(oper, type<Oper>())
+ |
+
+ __add__, __radd__
+ |
+ left + right
+ |
+ op_add
+ |
+ cpp_left + cpp_right
+ |
+
+ __sub__, __rsub__
+ |
+ left - right
+ |
+ op_sub
+ |
+ cpp_left - cpp_right
+ |
+
+ __mul__, __rmul__
+ |
+ left * right
+ |
+ op_mul
+ |
+ cpp_left * cpp_right
+ |
+
+ __div__, __rdiv__
+ |
+ left / right
+ |
+ op_div
+ |
+ cpp_left / cpp_right
+ |
+
+ __mod__, __rmod__
+ |
+ left % right
+ |
+ op_mod
+ |
+ cpp_left % cpp_right
+ |
+
+ __divmod__, __rdivmod__
+ |
+ (quotient, remainder)
+ = divmod(left, right)
+ |
+ op_divmod
+ |
+ cpp_left / cpp_right
+
cpp_left % cpp_right
+ |
+
+ __pow__, __rpow__
+ |
+ pow(left, right)
+ (binary power)
+ |
+ op_pow
+ |
+ pow(cpp_left, cpp_right)
+ |
+
+ __rrpow__
+ |
+ pow(left, right, modulo)
+ (ternary power modulo)
+ |
+ no automatic wrapping, special treatment
+ required
+ |
+
+ __lshift__, __rlshift__
+ |
+ left << right
+ |
+ op_lshift
+ |
+ cpp_left << cpp_right
+ |
+
+ __rshift__, __rrshift__
+ |
+ left >> right
+ |
+ op_rshift
+ |
+ cpp_left >> cpp_right
+ |
+
+ __and__, __rand__
+ |
+ left & right
+ |
+ op_and
+ |
+ cpp_left & cpp_right
+ |
+
+ __xor__, __rxor__
+ |
+ left ^ right
+ |
+ op_xor
+ |
+ cpp_left ^ cpp_right
+ |
+
+ __or__, __ror__
+ |
+ left | right
+ |
+ op_or
+ |
+ cpp_left | cpp_right
+
+ |
+
+ __cmp__, __rcmp__
+ |
+ cmp(left, right)
+
See Rich Comparisons.
+ |
+ op_cmp
+ |
+ cpp_left < cpp_right
+
cpp_right < cpp_left
+ |
+
+ __lt__
+
__le__
+
__eq__
+
__ne__
+
__gt__
+
__ge__
+ |
+ left < right
+
left <= right
+
left == right
+
left != right
+
left > right
+
left >= right
+
See Rich Comparisons
+ |
+ op_lt
+
op_le
+
op_eq
+
op_ne
+
op_gt
+
op_ge
+ |
+ cpp_left < cpp_right
+
cpp_left <= cpp_right
+
cpp_left == cpp_right
+
cpp_left != cpp_right
+
cpp_left > cpp_right
+
cpp_left >= cpp_right
+
+ |
+
+ __neg__
+ |
+ -oper (unary negation)
+ |
+ op_neg
+ |
+ -cpp_oper
+ |
+
+ __pos__
+ |
+ +oper (identity)
+ |
+ op_pos
+ |
+ +cpp_oper
+ |
+
+ __abs__
+ |
+ abs(oper) (absolute value)
+ |
+ op_abs
+ |
+ abs(cpp_oper)
+ |
+
+ __invert__
+ |
+ ~oper (bitwise inversion)
+ |
+ op_invert
+ |
+ ~cpp_oper
+ |
+
+ __int__
+ |
+ int(oper) (integer conversion)
+ |
+ op_int
+ |
+ long(cpp_oper)
+ |
+
+ __long__
+ |
+ long(oper)
+ (infinite precision integer conversion)
+ |
+ op_long
+ |
+ PyLong_FromLong(cpp_oper)
+ |
+
+ __float__
+ |
+ float(oper) (float conversion)
+ |
+ op_float
+ |
+ double(cpp_oper)
+ |
+
+ __str__
+ |
+ str(oper) (string conversion)
+ |
+ op_str
+ |
+ std::ostringstream s; s << oper;
+ |
+
+ __coerce__
+ |
+ coerce(left, right)
+ |
+ usually defined automatically, otherwise
+ special treatment required
+ |
+
+
+
+
+ Sequence and mapping operators let wrapped objects behave in accordance
+ to Python's iteration and access protocols. These protocols differ
+ considerably from the ones found in C++. For example, Python's typical
+ iteration idiom looks like
+
+
+for i in S:
+
+
+ while in C++ one writes
+
+
+for (iterator i = S.begin(), end = S.end(); i != end; ++i)
+
+
+
One could try to wrap C++ iterators in order to carry the C++ idiom into
+ Python. However, this does not work very well because
+
+
+- It leads to
+ non-uniform Python code (wrapped sequences support a usage different from
+ Python built-in sequences) and
+
+
- Iterators (e.g.
std::vector::iterator) are often implemented as plain C++
+ pointers which are problematic for any automatic
+ wrapping system.
+
+
+
+ It is a better idea to support the standard Python
+ sequence and mapping protocols for your wrapped containers. These
+ operators have to be wrapped manually because there are no corresponding
+ C++ operators that could be used for automatic wrapping. The Python
+ documentation lists the relevant
+ container operators. In particular, expose __getitem__, __setitem__
+ and remember to raise the appropriate Python exceptions
+ (PyExc_IndexError for sequences,
+ PyExc_KeyError for mappings) when the requested item is not
+ present.
+
+
+ In the following example, we expose std::map<std::size_t,std::string>:
+
+
+typedef std::map<std::size_t, std::string> StringMap;
+
+// A helper function for dealing with errors. Throw a Python exception
+// if p == m.end().
+void throw_key_error_if_end(
+ const StringMap& m,
+ StringMap::const_iterator p,
+ std::size_t key)
+{
+ if (p == m.end())
+ {
+ PyErr_SetObject(PyExc_KeyError, boost::python::converters::to_python(key));
+ boost::python::throw_error_already_set();
+ }
+}
+
+// Define some simple wrapper functions which match the Python protocol
+// for __getitem__, __setitem__, and __delitem__. Just as in Python, a
+// free function with a ``self'' first parameter makes a fine class method.
+
+const std::string& get_item(const StringMap& self, std::size_t key)
+{
+ const StringMap::const_iterator p = self.find(key);
+ throw_key_error_if_end(self, p, key);
+ return p->second;
+}
+
+// Sets the item corresponding to key in the map.
+void StringMapPythonClass::set_item(StringMap& self, std::size_t key, const std::string& value)
+{
+ self[key] = value;
+}
+
+// Deletes the item corresponding to key from the map.
+void StringMapPythonClass::del_item(StringMap& self, std::size_t key)
+{
+ const StringMap::iterator p = self.find(key);
+ throw_key_error_if_end(self, p, key);
+ self.erase(p);
+}
+
+class_builder<StringMap> string_map(my_module, "StringMap");
+string_map.def(boost::python::constructor<>());
+string_map.def(&StringMap::size, "__len__");
+string_map.def(get_item, "__getitem__");
+string_map.def(set_item, "__setitem__");
+string_map.def(del_item, "__delitem__");
+
+
+
+ Then in Python:
+
+
+>>> m = StringMap()
+>>> m[1]
+Traceback (innermost last):
+ File "<stdin>", line 1, in ?
+KeyError: 1
+>>> m[1] = 'hello'
+>>> m[1]
+'hello'
+>>> del m[1]
+>>> m[1] # prove that it's gone
+Traceback (innermost last):
+ File "<stdin>", line 1, in ?
+KeyError: 1
+>>> del m[2]
+Traceback (innermost last):
+ File "<stdin>", line 1, in ?
+KeyError: 2
+>>> len(m)
+0
+>>> m[0] = 'zero'
+>>> m[1] = 'one'
+>>> m[2] = 'two'
+>>> m[3] = 'three'
+>>> len(m)
+4
+
+
+
+
+
+
+ Just like built-in Python classes, Boost.Python extension classes support special
+ the usual attribute access methods __getattr__,
+ __setattr__, and __delattr__.
+ Because writing these functions can
+ be tedious in the common case where the attributes being accessed are
+ known statically, Boost.Python checks the special names
+
+
+ -
+
__getattr__<name>__
+ -
+
__setattr__<name>__
+ -
+
__delattr__<name>__
+
+
+ to provide functional access to the attribute
<name>. This
+ facility can be used from C++ or entirely from Python. For example, the
+ following shows how we can implement a ``computed attribute'' in Python:
+
+
+>>> class Range(AnyBoost.PythonExtensionClass):
+... def __init__(self, start, end):
+... self.start = start
+... self.end = end
+... def __getattr__length__(self):
+... return self.end - self.start
+...
+>>> x = Range(3, 9)
+>>> x.length
+6
+
+
+
+ Direct Access to Data Members
+
+
+ Boost.Python uses the special
+ __xxxattr__<name>__ functionality described above
+ to allow direct access to data members through the following special
+ functions on class_builder<> and
+ extension_class<>:
+
+ -
+
def_getter(pointer-to-member, name) //
+ read access to the member via attribute name
+ -
+
def_setter(pointer-to-member, name) //
+ write access to the member via attribute name
+ -
+
def_readonly(pointer-to-member, name)
+ // read-only access to the member via attribute name
+ -
+
def_read_write(pointer-to-member,
+ name) // read/write access to the member via attribute
+ name
+
+
+ Note that the first two functions, used alone, may produce surprising
+ behavior. For example, when def_getter() is used, the
+ default functionality for setattr() and
+ delattr() remains in effect, operating on items in the extension
+ instance's name-space (i.e., its __dict__). For that
+ reason, you'll usually want to stick with def_readonly and
+ def_read_write.
+
+ For example, to expose a std::pair<int,long> we
+ might write:
+
+
+typedef std::pair<int,long> Pil;
+int first(const Pil& x) { return x.first; }
+long second(const Pil& x) { return x.second; }
+ ...
+my_module.def(first, "first");
+my_module.def(second, "second");
+
+class_builder<Pil> pair_int_long(my_module, "Pair");
+pair_int_long.def(boost::python::constructor<>());
+pair_int_long.def(boost::python::constructor<int,long>());
+pair_int_long.def_read_write(&Pil::first, "first");
+pair_int_long.def_read_write(&Pil::second, "second");
+
+
+
+ Now your Python class has attributes first and
+ second which, when accessed, actually modify or reflect the
+ values of corresponding data members of the underlying C++ object. Now
+ in Python:
+
+
+>>> x = Pair(3,5)
+>>> x.first
+3
+>>> x.second
+5
+>>> x.second = 8
+>>> x.second
+8
+>>> second(x) # Prove that we're not just changing the instance __dict__
+8
+
+
+
+
+ That, dear reader, is one problem we don't know how to solve. The
+ Python source contains the following fragment, indicating the
+ special-case code really is hardwired:
+
+
+/* XXX Hack to support classes with __complex__ method */
+if (PyInstance_Check(r)) { ...
+
+
+
+Next: A Peek Under the Hood
+Previous: Inheritance
+Up: Top
+
+ © Copyright David Abrahams and Ullrich Köthe 2000.
+ Permission to copy, use, modify, sell and distribute this document is
+ granted provided this copyright notice appears in all copies. This
+ document is provided ``as is'' without express or implied
+ warranty, and with no claim as to its suitability for any purpose.
+
+ Updated: Nov 26, 2000
+
+
+
+
+ A Peek Under the Hood
+
+
+ Declaring a class_builder<T> causes the instantiation
+ of an extension_class<T> to which it forwards all
+ member function calls and which is doing most of the real work.
+ extension_class<T> is a subclass of
+ PyTypeObject, the struct which Python's 'C' API uses
+ to describe a type. An instance of the
+ extension_class<> becomes the Python type object
+ corresponding to hello::world. When we add it to the module it goes into the
+ module's dictionary to be looked up under the name "world".
+
+ Boost.Python uses C++'s template argument deduction mechanism to determine the
+ types of arguments to functions (except constructors, for which we must
+ provide an argument list
+ because they can't be named in C++). Then, it calls the appropriate
+ overloaded functions PyObject*
+ to_python(S) and
+ S'from_python(PyObject*,
+ type<S>) which convert between any C++
+ type S and a PyObject*, the type which represents a
+ reference to any Python object in its 'C' API. The extension_class<T>
+ template defines a whole raft of these conversions (for T, T*,
+ T&, std::auto_ptr<T>, etc.), using the same inline
+ friend function technique employed by the boost operators
+ library.
+
+ Because the to_python and from_python functions
+ for a user-defined class are defined by
+ extension_class<T>, it is important that an instantiation of
+ extension_class<T> is visible to any code which wraps
+ a C++ function with a T, T*, const T&, etc. parameter or
+ return value. In particular, you may want to create all of the classes at
+ the top of your module's init function, then def the member
+ functions later to avoid problems with inter-class dependencies.
+
+ Next: Building a Module with Boost.Python
+ Previous: Special Method and Operator Support
+ Up: Top
+
+ © Copyright David Abrahams 2000. Permission to copy, use, modify,
+ sell and distribute this document is granted provided this copyright
+ notice appears in all copies. This document is provided "as is" without
+ express or implied warranty, and with no claim as to its suitability for
+ any purpose.
+
+ Updated: Nov 26, 2000
+
diff --git a/include/boost/python.hpp b/include/boost/python.hpp
deleted file mode 100644
index ca81cce2..00000000
--- a/include/boost/python.hpp
+++ /dev/null
@@ -1,62 +0,0 @@
-// Copyright David Abrahams 2002. Permission to copy, use,
-// modify, sell and distribute this software is granted provided this
-// copyright notice appears in all copies. This software is provided
-// "as is" without express or implied warranty, and with no claim as
-// to its suitability for any purpose.
-#ifndef PYTHON_DWA2002810_HPP
-# define PYTHON_DWA2002810_HPP
-
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-
-#endif PYTHON_DWA2002810_HPP
diff --git a/include/boost/python/converter/rvalue_from_python_data.hpp b/include/boost/python/converter/rvalue_from_python_data.hpp
index c9e9ff03..7f512830 100644
--- a/include/boost/python/converter/rvalue_from_python_data.hpp
+++ b/include/boost/python/converter/rvalue_from_python_data.hpp
@@ -94,8 +94,7 @@ struct rvalue_from_python_data : rvalue_from_python_storage
{
# if (!defined(__MWERKS__) || __MWERKS__ >= 0x3000) \
&& (!defined(__EDG_VERSION__) || __EDG_VERSION__ >= 245) \
- && (!defined(__DECCXX_VER) || __DECCXX_VER > 60590014) \
- && !(defined(__APPLE__) && defined(__MACH__) && __APPLE_CC__ <= 1161)
+ && (!defined(__DECCXX_VER) || __DECCXX_VER > 60590014)
// This must always be a POD struct with m_data its first member.
BOOST_STATIC_ASSERT(BOOST_PYTHON_OFFSETOF(rvalue_from_python_storage,stage1) == 0);
# endif
diff --git a/include/boost/python/errors.hpp b/include/boost/python/errors.hpp
index cd0b3586..4c47aca8 100644
--- a/include/boost/python/errors.hpp
+++ b/include/boost/python/errors.hpp
@@ -46,9 +46,11 @@ inline T* expect_non_null(T* x)
return x;
}
+# ifdef BOOST_PYTHON_V2
// Return source if it is an instance of pytype; throw an appropriate
// exception otherwise.
BOOST_PYTHON_DECL PyObject* pytype_check(PyTypeObject* pytype, PyObject* source);
+# endif
}} // namespace boost::python
diff --git a/include/boost/python/init.hpp b/include/boost/python/init.hpp
index 2707f7b7..589f8ac0 100644
--- a/include/boost/python/init.hpp
+++ b/include/boost/python/init.hpp
@@ -138,16 +138,16 @@ struct init_base
init_base(char const* doc_, detail::keyword_range const& keywords_)
: m_doc(doc_), m_keywords(keywords_)
{}
-
+
init_base(char const* doc_)
: m_doc(doc_)
{}
-
+
DerivedT const& derived() const
{
return *static_cast(this);
}
-
+
char const* doc_string() const
{
return m_doc;
@@ -162,7 +162,7 @@ struct init_base
{
return default_call_policies();
}
-
+
private: // data members
char const* m_doc;
detail::keyword_range m_keywords;
@@ -192,7 +192,7 @@ class init_with_call_policies
{
return this->m_policies;
}
-
+
private: // data members
CallPoliciesT m_policies;
};
@@ -355,7 +355,7 @@ namespace detail
if (keywords.second > keywords.first)
--keywords.second;
-
+
typename mpl::pop_front::type next;
define_class_init_helper::apply(cl, policies, next, doc, keywords);
}
diff --git a/include/boost/python/operators.hpp b/include/boost/python/operators.hpp
index 7087f83a..df401f85 100644
--- a/include/boost/python/operators.hpp
+++ b/include/boost/python/operators.hpp
@@ -1,332 +1,555 @@
-// Copyright David Abrahams 2002. Permission to copy, use,
-// modify, sell and distribute this software is granted provided this
-// copyright notice appears in all copies. This software is provided
-// "as is" without express or implied warranty, and with no claim as
-// to its suitability for any purpose.
-#ifndef OPERATORS_DWA2002530_HPP
-# define OPERATORS_DWA2002530_HPP
+// (C) Copyright Ullrich Koethe and David Abrahams 2000-2001. Permission to
+// copy, use, modify, sell and distribute this software is granted provided
+// this copyright notice appears in all copies. This software is provided "as
+// is" without express or implied warranty, and with no claim as to its
+// suitability for any purpose.
+//
+// The authors gratefully acknowlege the support of Dragon Systems, Inc., in
+// producing this work.
+//
+// Revision History:
+// 23 Jan 2001 - Another stupid typo fix by Ralf W. Grosse-Kunstleve (David Abrahams)
+// 20 Jan 2001 - Added a fix from Ralf W. Grosse-Kunstleve (David Abrahams)
+#ifndef OPERATORS_UK112000_H_
+# define OPERATORS_UK112000_H_
+# ifdef BOOST_PYTHON_V2
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-# include
-# include
+# include
-namespace boost { namespace python {
+# else
+
+# include
+# include
+
+// When STLport is used with native streams, _STL::ostringstream().str() is not
+// _STL::string, but std::string. This confuses to_python(), so we'll use
+// strstream instead. Also, GCC 2.95.2 doesn't have sstream.
+# if defined(__SGI_STL_PORT) ? defined(__SGI_STL_OWN_IOSTREAMS) : (!defined(__GNUC__) || __GNUC__ > 2)
+# define BOOST_PYTHON_USE_SSTREAM
+# endif
+
+# if defined(BOOST_PYTHON_USE_SSTREAM)
+# include
+# else
+# include
+# endif
+
+namespace boost { namespace python {
+
+BOOST_PYTHON_DECL tuple standard_coerce(ref l, ref r);
+
+namespace detail {
+
+ // helper class for automatic operand type detection
+ // during operator wrapping.
+ struct auto_operand {};
+}
+
+// Define operator ids that can be or'ed together
+// (boost::python::op_add | boost::python::op_sub | boost::python::op_mul).
+// This allows to wrap several operators in one line.
+enum operator_id
+{
+ op_add = 0x1,
+ op_sub = 0x2,
+ op_mul = 0x4,
+ op_div = 0x8,
+ op_mod = 0x10,
+ op_divmod =0x20,
+ op_pow = 0x40,
+ op_lshift = 0x80,
+ op_rshift = 0x100,
+ op_and = 0x200,
+ op_xor = 0x400,
+ op_or = 0x800,
+ op_neg = 0x1000,
+ op_pos = 0x2000,
+ op_abs = 0x4000,
+ op_invert = 0x8000,
+ op_int = 0x10000,
+ op_long = 0x20000,
+ op_float = 0x40000,
+ op_str = 0x80000,
+ op_cmp = 0x100000,
+ op_gt = 0x200000,
+ op_ge = 0x400000,
+ op_lt = 0x800000,
+ op_le = 0x1000000,
+ op_eq = 0x2000000,
+ op_ne = 0x4000000
+};
+
+// Wrap the operators given by "which". Usage:
+// foo_class.def(boost::python::operators<(boost::python::op_add | boost::python::op_sub)>());
+template
+struct operators {};
+
+// Wrap heterogeneous operators with given left operand type. Usage:
+// foo_class.def(boost::python::operators<(boost::python::op_add | boost::python::op_sub)>(),
+// boost::python::left_operand());
+template
+struct left_operand {};
+
+// Wrap heterogeneous operators with given right operand type. Usage:
+// foo_class.def(boost::python::operators<(boost::python::op_add | boost::python::op_sub)>(),
+// boost::python::right_operand());
+template
+struct right_operand {};
namespace detail
{
- // This is essentially the old v1 to_python(). It will be eliminated
- // once the public interface for to_python is settled on.
- template
- PyObject* convert_result(T const& x)
+ template
+ struct operand_select
{
- return converter::arg_to_python(x).release();
- }
+ template
+ struct wrapped
+ {
+ typedef Specified type;
+ };
+ };
- // Operator implementation template declarations. The nested apply
- // declaration here keeps MSVC6 happy.
- template struct operator_l
+ template <>
+ struct operand_select
{
- template struct apply;
+ template
+ struct wrapped
+ {
+ typedef const wrapped_type& type;
+ };
+ };
+
+ template struct define_operator;
+
+ // Base class which grants access to extension_class_base::add_method() to its derived classes
+ struct add_operator_base
+ {
+ protected:
+ static inline void add_method(extension_class_base* target, function* method, const char* name)
+ { target->add_method(method, name); }
+ };
+
+//
+// choose_op, choose_unary_op, and choose_rop
+//
+// These templates use "poor man's partial specialization" to generate the
+// appropriate add_method() call (if any) for a given operator and argument set.
+//
+// Usage:
+// choose_op<(which & op_add)>::template args::add(ext_class);
+//
+// (see extension_class<>::def_operators() for more examples).
+//
+ template
+ struct choose_op
+ {
+ template
+ struct args : add_operator_base
+ {
+ static inline void add(extension_class_base* target)
+ {
+ typedef define_operator def_op;
+ add_method(target,
+ new typename def_op::template operator_function(),
+ def_op::name());
+ }
+
+ };
+ };
+
+ // specialization for 0 has no effect
+ template <>
+ struct choose_op<0>
+ {
+ template
+ struct args
+ {
+ static inline void add(extension_class_base*)
+ {
+ }
+
+ };
};
- template struct operator_r
+ template
+ struct choose_unary_op
{
- template struct apply;
- };
-
- template struct operator_1
- {
- template struct apply;
- };
-
- // MSVC6 doesn't want us to do this sort of inheritance on a nested
- // class template, so we use this layer of indirection to avoid
- // ::template<...> on the nested apply functions below
- template
- struct operator_l_inner
- : operator_l::template apply
- {};
-
- template
- struct operator_r_inner
- : operator_r::template apply
- {};
-
- template
- struct operator_1_inner
- : operator_1::template apply
- {};
-
- // Define three different binary_op templates which take care of
- // these cases:
- // self op self
- // self op R
- // L op self
- //
- // The inner apply metafunction is used to adjust the operator to
- // the class type being defined. Inheritance of the outer class is
- // simply used to provide convenient access to the operation's
- // name().
-
- // self op self
- template
- struct binary_op : operator_l
- {
- template
- struct apply : operator_l_inner
+ template
+ struct args : add_operator_base
{
+ static inline void add(extension_class_base* target)
+ {
+ typedef define_operator def_op;
+ add_method(target,
+ new typename def_op::template operator_function(),
+ def_op::name());
+ }
+
};
};
-
- // self op R
- template
- struct binary_op_l : operator_l
- {
- template
- struct apply : operator_l_inner
- {
- };
- };
-
- // L op self
- template
- struct binary_op_r : operator_r
- {
- template
- struct apply : operator_r_inner
- {
- };
- };
-
- template
- struct unary_op : operator_1
- {
- template
- struct apply : operator_1_inner
- {
- };
- };
-
- // This type is what actually gets returned from operators used on
- // self_t
- template
- struct operator_
- : mpl::if_<
- is_same
- , typename mpl::if_<
- is_same
- , binary_op
- , binary_op_l::type>
- >::type
- , typename mpl::if_<
- is_same
- , unary_op
- , binary_op_r::type>
- >::type
- >::type
- {
- };
-}
-
-# define BOOST_PYTHON_BINARY_OPERATION(id, rid, expr) \
-namespace detail \
-{ \
- template <> \
- struct operator_l \
- { \
- template \
- struct apply \
- { \
- static inline PyObject* execute(L const& l, R const& r) \
- { \
- return detail::convert_result(expr); \
- } \
- }; \
- static char const* name() { return "__" #id "__"; } \
- }; \
- \
- template <> \
- struct operator_r \
- { \
- template \
- struct apply \
- { \
- static inline PyObject* execute(R const& r, L const& l) \
- { \
- return detail::convert_result(expr); \
- } \
- }; \
- static char const* name() { return "__" #rid "__"; } \
- }; \
-}
-
-# define BOOST_PYTHON_BINARY_OPERATOR(id, rid, op) \
-BOOST_PYTHON_BINARY_OPERATION(id, rid, l op r) \
-namespace self_ns \
-{ \
- template \
- inline detail::operator_ \
- operator##op(L const&, R const&) \
- { \
- return detail::operator_(); \
- } \
-}
-BOOST_PYTHON_BINARY_OPERATOR(add, radd, +)
-BOOST_PYTHON_BINARY_OPERATOR(sub, rsub, -)
-BOOST_PYTHON_BINARY_OPERATOR(mul, rmul, *)
-BOOST_PYTHON_BINARY_OPERATOR(div, rdiv, /)
-BOOST_PYTHON_BINARY_OPERATOR(mod, rmod, %)
-BOOST_PYTHON_BINARY_OPERATOR(lshift, rlshift, <<)
-BOOST_PYTHON_BINARY_OPERATOR(rshift, rrshift, >>)
-BOOST_PYTHON_BINARY_OPERATOR(and, rand, &)
-BOOST_PYTHON_BINARY_OPERATOR(xor, rxor, ^)
-BOOST_PYTHON_BINARY_OPERATOR(or, ror, |)
-BOOST_PYTHON_BINARY_OPERATOR(gt, lt, >)
-BOOST_PYTHON_BINARY_OPERATOR(ge, le, >=)
-BOOST_PYTHON_BINARY_OPERATOR(lt, gt, <)
-BOOST_PYTHON_BINARY_OPERATOR(le, ge, <=)
-BOOST_PYTHON_BINARY_OPERATOR(eq, eq, ==)
-BOOST_PYTHON_BINARY_OPERATOR(ne, ne, !=)
-# undef BOOST_PYTHON_BINARY_OPERATOR
-
-// pow isn't an operator in C++; handle it specially.
-BOOST_PYTHON_BINARY_OPERATION(pow, rpow, pow(l,r))
-# undef BOOST_PYTHON_BINARY_OPERATION
-
-namespace self_ns
-{
-# ifndef BOOST_NO_ARGUMENT_DEPENDENT_LOOKUP
- template
- inline detail::operator_
- pow(L const&, R const&)
+ // specialization for 0 has no effect
+ template <>
+ struct choose_unary_op<0>
{
- return detail::operator_();
- }
-# else
- // When there's no argument-dependent lookup, we need these
- // overloads to handle the case when everything is imported into the
- // global namespace. Note that the plain overload below does /not/
- // take const& arguments. This is needed by MSVC6 at least, or it
- // complains of ambiguities, since there's no partial ordering.
- inline detail::operator_
- pow(self_t, self_t)
+ template
+ struct args
+ {
+ static inline void add(extension_class_base*)
+ {
+ }
+
+ };
+ };
+
+ template
+ struct choose_rop
{
- return detail::operator_();
- }
- template
- inline detail::operator_
- pow(self_t const&, R const&)
+ template
+ struct args : add_operator_base
+ {
+ static inline void add(extension_class_base* target)
+ {
+ typedef define_operator def_op;
+ add_method(target,
+ new typename def_op::template roperator_function(),
+ def_op::rname());
+ }
+
+ };
+ };
+
+ // specialization for 0 has no effect
+ template <>
+ struct choose_rop<0>
{
- return detail::operator_();
- }
- template
- inline detail::operator_
- pow(L const&, self_t const&)
- {
- return detail::operator_();
- }
-# endif
-}
+ template
+ struct args
+ {
+ static inline void add(extension_class_base*)
+ {
+ }
+
+ };
+ };
-# define BOOST_PYTHON_INPLACE_OPERATOR(id, op) \
-namespace detail \
-{ \
- template <> \
- struct operator_l \
- { \
- template \
- struct apply \
- { \
- static inline PyObject* \
- execute(back_reference l, R const& r) \
- { \
- l.get() op r; \
- return python::incref(l.source().ptr()); \
- } \
- }; \
- static char const* name() { return "__" #id "__"; } \
- }; \
-} \
-namespace self_ns \
-{ \
- template \
- inline detail::operator_ \
- operator##op(self_t const&, R const&) \
- { \
- return detail::operator_(); \
- } \
-}
+// Fully specialize define_operator for all operators defined in operator_id above.
+// Every specialization defines one function object for normal operator calls and one
+// for operator calls with operands reversed ("__r*__" function variants).
+// Specializations for most operators follow a standard pattern: execute the expression
+// that uses the operator in question. This standard pattern is realized by the following
+// macros so that the actual specialization can be done by just calling a macro.
+# define PY_DEFINE_BINARY_OPERATORS(id, oper) \
+ template <> \
+ struct define_operator \
+ { \
+ template \
+ struct operator_function : function \
+ { \
+ PyObject* do_call(PyObject* arguments, PyObject* /* keywords */) const \
+ { \
+ tuple args(ref(arguments, ref::increment_count)); \
+ \
+ return BOOST_PYTHON_CONVERSION::to_python( \
+ BOOST_PYTHON_CONVERSION::from_python(args[0].get(), boost::python::type()) oper \
+ BOOST_PYTHON_CONVERSION::from_python(args[1].get(), boost::python::type())); \
+ } \
+ \
+ const char* description() const \
+ { return "__" #id "__"; } \
+ }; \
+ \
+ template \
+ struct roperator_function : function \
+ { \
+ PyObject* do_call(PyObject* arguments, PyObject* /* keywords */) const \
+ { \
+ tuple args(ref(arguments, ref::increment_count)); \
+ \
+ return BOOST_PYTHON_CONVERSION::to_python( \
+ BOOST_PYTHON_CONVERSION::from_python(args[1].get(), boost::python::type()) oper \
+ BOOST_PYTHON_CONVERSION::from_python(args[0].get(), boost::python::type())); \
+ } \
+ \
+ const char* description() const \
+ { return "__r" #id "__"; } \
+ \
+ }; \
+ \
+ static const char * name() { return "__" #id "__"; } \
+ static const char * rname() { return "__r" #id "__"; } \
+ }
-BOOST_PYTHON_INPLACE_OPERATOR(iadd,+=)
-BOOST_PYTHON_INPLACE_OPERATOR(isub,-=)
-BOOST_PYTHON_INPLACE_OPERATOR(imul,*=)
-BOOST_PYTHON_INPLACE_OPERATOR(idiv,/=)
-BOOST_PYTHON_INPLACE_OPERATOR(imod,%=)
-BOOST_PYTHON_INPLACE_OPERATOR(ilshift,<<=)
-BOOST_PYTHON_INPLACE_OPERATOR(irshift,>>=)
-BOOST_PYTHON_INPLACE_OPERATOR(iand,&=)
-BOOST_PYTHON_INPLACE_OPERATOR(ixor,^=)
-BOOST_PYTHON_INPLACE_OPERATOR(ior,|=)
-
-# define BOOST_PYTHON_UNARY_OPERATOR(id, op, func_name) \
-namespace detail \
-{ \
- template <> \
- struct operator_1 \
- { \
- template \
- struct apply \
- { \
- static PyObject* execute(T const& x) \
- { \
- return detail::convert_result(op(x)); \
- } \
- }; \
- static char const* name() { return "__" #id "__"; } \
- }; \
-} \
-namespace self_ns \
-{ \
- inline detail::operator_ \
- func_name(self_t const&) \
- { \
- return detail::operator_(); \
- } \
-}
-# undef BOOST_PYTHON_INPLACE_OPERATOR
+# define PY_DEFINE_UNARY_OPERATORS(id, oper) \
+ template <> \
+ struct define_operator \
+ { \
+ template \
+ struct operator_function : function \
+ { \
+ PyObject* do_call(PyObject* arguments, PyObject* /* keywords */) const \
+ { \
+ tuple args(ref(arguments, ref::increment_count)); \
+ \
+ return BOOST_PYTHON_CONVERSION::to_python( \
+ oper(BOOST_PYTHON_CONVERSION::from_python(args[0].get(), boost::python::type()))); \
+ } \
+ \
+ const char* description() const \
+ { return "__" #id "__"; } \
+ }; \
+ \
+ static const char * name() { return "__" #id "__"; } \
+ }
-BOOST_PYTHON_UNARY_OPERATOR(neg, -, operator-)
-BOOST_PYTHON_UNARY_OPERATOR(pos, +, operator+)
-BOOST_PYTHON_UNARY_OPERATOR(abs, abs, abs)
-BOOST_PYTHON_UNARY_OPERATOR(invert, ~, operator~)
-BOOST_PYTHON_UNARY_OPERATOR(int, long, int_)
-BOOST_PYTHON_UNARY_OPERATOR(long, PyLong_FromLong, long_)
-BOOST_PYTHON_UNARY_OPERATOR(float, double, float_)
-BOOST_PYTHON_UNARY_OPERATOR(complex, std::complex, complex_)
-BOOST_PYTHON_UNARY_OPERATOR(str, lexical_cast, str)
-# undef BOOST_PYTHON_UNARY_OPERATOR
+ PY_DEFINE_BINARY_OPERATORS(add, +);
+ PY_DEFINE_BINARY_OPERATORS(sub, -);
+ PY_DEFINE_BINARY_OPERATORS(mul, *);
+ PY_DEFINE_BINARY_OPERATORS(div, /);
+ PY_DEFINE_BINARY_OPERATORS(mod, %);
+ PY_DEFINE_BINARY_OPERATORS(lshift, <<);
+ PY_DEFINE_BINARY_OPERATORS(rshift, >>);
+ PY_DEFINE_BINARY_OPERATORS(and, &);
+ PY_DEFINE_BINARY_OPERATORS(xor, ^);
+ PY_DEFINE_BINARY_OPERATORS(or, |);
+ PY_DEFINE_BINARY_OPERATORS(gt, >);
+ PY_DEFINE_BINARY_OPERATORS(ge, >=);
+ PY_DEFINE_BINARY_OPERATORS(lt, <);
+ PY_DEFINE_BINARY_OPERATORS(le, <=);
+ PY_DEFINE_BINARY_OPERATORS(eq, ==);
+ PY_DEFINE_BINARY_OPERATORS(ne, !=);
+
+ PY_DEFINE_UNARY_OPERATORS(neg, -);
+ PY_DEFINE_UNARY_OPERATORS(pos, +);
+ PY_DEFINE_UNARY_OPERATORS(abs, abs);
+ PY_DEFINE_UNARY_OPERATORS(invert, ~);
+ PY_DEFINE_UNARY_OPERATORS(int, long);
+ PY_DEFINE_UNARY_OPERATORS(long, PyLong_FromLong);
+ PY_DEFINE_UNARY_OPERATORS(float, double);
+
+# undef PY_DEFINE_BINARY_OPERATORS
+# undef PY_DEFINE_UNARY_OPERATORS
+
+// Some operators need special treatment, e.g. because there is no corresponding
+// expression in C++. These are specialized manually.
+
+// pow(): Manual specialization needed because an error message is required if this
+// function is called with three arguments. The "power modulo" operator is not
+// supported by define_operator, but can be wrapped manually (see special.html).
+ template <>
+ struct define_operator
+ {
+ template
+ struct operator_function : function
+ {
+ PyObject* do_call(PyObject* arguments, PyObject* /* keywords */) const
+ {
+ tuple args(ref(arguments, ref::increment_count));
+
+ if (args.size() == 3 && args[2]->ob_type != Py_None->ob_type)
+ {
+ PyErr_SetString(PyExc_TypeError, "expected 2 arguments, got 3");
+ throw_argument_error();
+ }
+
+ return BOOST_PYTHON_CONVERSION::to_python(
+ pow(BOOST_PYTHON_CONVERSION::from_python(args[0].get(), boost::python::type()),
+ BOOST_PYTHON_CONVERSION::from_python(args[1].get(), boost::python::type())));
+ }
+
+ const char* description() const
+ { return "__pow__"; }
+
+ };
+
+ template
+ struct roperator_function : function
+ {
+ PyObject* do_call(PyObject* arguments, PyObject* /* keywords */) const
+ {
+ tuple args(ref(arguments, ref::increment_count));
+
+ if (args.size() == 3 && args[2]->ob_type != Py_None->ob_type)
+ {
+ PyErr_SetString(PyExc_TypeError, "bad operand type(s) for pow()");
+ throw_argument_error();
+ }
+
+ return BOOST_PYTHON_CONVERSION::to_python(
+ pow(BOOST_PYTHON_CONVERSION::from_python(args[1].get(), boost::python::type()),
+ BOOST_PYTHON_CONVERSION::from_python(args[0].get(), boost::python::type())));
+ }
+
+ const char* description() const
+ { return "__rpow__"; }
+
+ };
+
+ static const char * name() { return "__pow__"; }
+ static const char * rname() { return "__rpow__"; }
+ };
+
+// divmod(): Manual specialization needed because we must actually call two operators and
+// return a tuple containing both results
+ template <>
+ struct define_operator
+ {
+ template
+ struct operator_function : function
+ {
+ PyObject* do_call(PyObject* arguments, PyObject* /* keywords */) const
+ {
+ tuple args(ref(arguments, ref::increment_count));
+ PyObject * res = PyTuple_New(2);
+
+ PyTuple_SET_ITEM(res, 0,
+ BOOST_PYTHON_CONVERSION::to_python(
+ BOOST_PYTHON_CONVERSION::from_python(args[0].get(), boost::python::type()) /
+ BOOST_PYTHON_CONVERSION::from_python(args[1].get(), boost::python::type())));
+ PyTuple_SET_ITEM(res, 1,
+ BOOST_PYTHON_CONVERSION::to_python(
+ BOOST_PYTHON_CONVERSION::from_python(args[0].get(), boost::python::type()) %
+ BOOST_PYTHON_CONVERSION::from_python(args[1].get(), boost::python::type())));
+
+ return res;
+ }
+
+ const char* description() const
+ { return "__divmod__"; }
+
+ };
+
+ template
+ struct roperator_function : function
+ {
+ PyObject* do_call(PyObject* arguments, PyObject* /* keywords */) const
+ {
+ tuple args(ref(arguments, ref::increment_count));
+ PyObject * res = PyTuple_New(2);
+
+ PyTuple_SET_ITEM(res, 0,
+ BOOST_PYTHON_CONVERSION::to_python(
+ BOOST_PYTHON_CONVERSION::from_python(args[1].get(), boost::python::type()) /
+ BOOST_PYTHON_CONVERSION::from_python(args[0].get(), boost::python::type())));
+ PyTuple_SET_ITEM(res, 1,
+ BOOST_PYTHON_CONVERSION::to_python(
+ BOOST_PYTHON_CONVERSION::from_python(args[1].get(), boost::python::type()) %
+ BOOST_PYTHON_CONVERSION::from_python(args[0].get(), boost::python::type())));
+
+ return res;
+ }
+
+ const char* description() const
+ { return "__rdivmod__"; }
+
+ };
+
+ static const char * name() { return "__divmod__"; }
+ static const char * rname() { return "__rdivmod__"; }
+ };
+
+// cmp(): Manual specialization needed because there is no three-way compare in C++.
+// It is implemented by two one-way comparisons with operators reversed in the second.
+ template <>
+ struct define_operator
+ {
+ template
+ struct operator_function : function
+ {
+ PyObject* do_call(PyObject* arguments, PyObject* /* keywords */) const
+ {
+ tuple args(ref(arguments, ref::increment_count));
+
+ return BOOST_PYTHON_CONVERSION::to_python(
+ (BOOST_PYTHON_CONVERSION::from_python(args[0].get(), boost::python::type()) <
+ BOOST_PYTHON_CONVERSION::from_python(args[1].get(), boost::python::type())) ?
+ - 1 :
+ (BOOST_PYTHON_CONVERSION::from_python(args[1].get(), boost::python::type()) <
+ BOOST_PYTHON_CONVERSION::from_python(args[0].get(), boost::python::type())) ?
+ 1 :
+ 0) ;
+ }
+
+ const char* description() const
+ { return "__cmp__"; }
+
+ };
+
+ template
+ struct roperator_function : function
+ {
+ PyObject* do_call(PyObject* arguments, PyObject* /* keywords */) const
+ {
+ tuple args(ref(arguments, ref::increment_count));
+
+ return BOOST_PYTHON_CONVERSION::to_python(
+ (BOOST_PYTHON_CONVERSION::from_python(args[1].get(), boost::python::type()) <
+ BOOST_PYTHON_CONVERSION::from_python(args[0].get(), boost::python::type())) ?
+ - 1 :
+ (BOOST_PYTHON_CONVERSION::from_python(args[0].get(), boost::python::type()) <
+ BOOST_PYTHON_CONVERSION::from_python(args[1].get(), boost::python::type())) ?
+ 1 :
+ 0) ;
+ }
+
+ const char* description() const
+ { return "__rcmp__"; }
+
+ };
+
+ static const char * name() { return "__cmp__"; }
+ static const char * rname() { return "__rcmp__"; }
+ };
+
+# ifndef BOOST_PYTHON_USE_SSTREAM
+ class unfreezer {
+ public:
+ unfreezer(std::ostrstream& s) : m_stream(s) {}
+ ~unfreezer() { m_stream.freeze(false); }
+ private:
+ std::ostrstream& m_stream;
+ };
+# endif
+
+// str(): Manual specialization needed because the string conversion does not follow
+// the standard pattern relized by the macros.
+ template <>
+ struct define_operator
+ {
+ template
+ struct operator_function : function
+ {
+ PyObject* do_call(PyObject* arguments, PyObject*) const
+ {
+ tuple args(ref(arguments, ref::increment_count));
+
+// When STLport is used with native streams, _STL::ostringstream().str() is not
+// _STL::string, but std::string.
+# ifdef BOOST_PYTHON_USE_SSTREAM
+ std::ostringstream s;
+ s << BOOST_PYTHON_CONVERSION::from_python(args[0].get(), boost::python::type());
+ return BOOST_PYTHON_CONVERSION::to_python(s.str());
+# else
+ std::ostrstream s;
+ s << BOOST_PYTHON_CONVERSION::from_python(args[0].get(), boost::python::type()) << char();
+ auto unfreezer unfreeze(s);
+ return BOOST_PYTHON_CONVERSION::to_python(const_cast(s.str()));
+# endif
+ }
+
+ const char* description() const
+ { return "__str__"; }
+
+ };
+
+ static const char * name() { return "__str__"; }
+ };
+
+
+} // namespace detail
}} // namespace boost::python
-# ifdef BOOST_NO_ARGUMENT_DEPENDENT_LOOKUP
-using boost::python::self_ns::abs;
-using boost::python::self_ns::int_;
-using boost::python::self_ns::long_;
-using boost::python::self_ns::float_;
-using boost::python::self_ns::complex_;
-using boost::python::self_ns::str;
-using boost::python::self_ns::pow;
-# endif
-
-#endif // OPERATORS_DWA2002530_HPP
+# undef BOOST_PYTHON_USE_SSTREAM
+# endif
+#endif /* OPERATORS_UK112000_H_ */
diff --git a/test/comprehensive.cpp b/test/comprehensive.cpp
new file mode 100644
index 00000000..e3a756b9
--- /dev/null
+++ b/test/comprehensive.cpp
@@ -0,0 +1,1265 @@
+// (C) Copyright David Abrahams 2000. Permission to copy, use, modify, sell and
+// distribute this software is granted provided this copyright notice appears
+// in all copies. This software is provided "as is" without express or implied
+// warranty, and with no claim as to its suitability for any purpose.
+//
+// The author gratefully acknowleges the support of Dragon Systems, Inc., in
+// producing this work.
+
+// Revision History:
+// 04 Mar 01 Changed name of extension module so it would work with DebugPython,
+// eliminated useless test that aggravated MSVC (David Abrahams)
+#include "comprehensive.hpp"
+#include
+#include // used for portability on broken compilers
+#include // for pow()
+#include
+
+#if defined(__sgi) \
+ && ( (defined(_COMPILER_VERSION) && _COMPILER_VERSION <= 730) \
+ && !defined(__GNUC__))
+inline double pow(int x, int y) { return pow(static_cast(x), y); }
+#endif
+
+namespace bpl_test {
+
+FooCallback::FooCallback(PyObject* self, int x)
+ : Foo(x), m_self(self)
+{
+}
+
+int FooCallback::add_len(const char* x) const
+{
+ // Try to call the "add_len" method on the corresponding Python object.
+ return boost::python::callback::call_method(m_self, "add_len", x);
+}
+
+// A function which Python can call in case bar is not overridden from
+// Python. In true Python style, we use a free function taking an initial self
+// parameter. This function anywhere needn't be a static member of the callback
+// class. The only reason to do it this way is that Foo::add_len is private, and
+// FooCallback is already a friend of Foo.
+int FooCallback::default_add_len(const Foo* self, const char* x)
+{
+ // Don't forget the Foo:: qualification, or you'll get an infinite
+ // recursion!
+ return self->Foo::add_len(x);
+}
+
+// Since Foo::pure() is pure virtual, we don't need a corresponding
+// default_pure(). A failure to override it in Python will result in an
+// exception at runtime when pure() is called.
+std::string FooCallback::pure() const
+{
+ return boost::python::callback::call_method(m_self, "pure");
+}
+
+Foo::PythonClass::PythonClass(boost::python::module_builder& m)
+ : boost::python::class_builder(m, "Foo")
+{
+ def(boost::python::constructor());
+ def(&Foo::mumble, "mumble");
+ def(&Foo::set, "set");
+ def(&Foo::call_pure, "call_pure");
+ def(&Foo::call_add_len, "call_add_len");
+
+ // This is the way we add a virtual function that has a default implementation.
+ def(&Foo::add_len, "add_len", &FooCallback::default_add_len);
+
+ // Since pure() is pure virtual, we are leaving it undefined.
+
+ // And the nested classes.
+ boost::python::class_builder foo_a(*this, "Foo_A");
+ foo_a.def(boost::python::constructor<>());
+ foo_a.def(&Foo::Foo_A::mumble, "mumble");
+
+ boost::python::class_builder foo_b(get_extension_class(),
+ "Foo_B");
+ foo_b.def(boost::python::constructor<>());
+ foo_b.def(&Foo::Foo_B::mumble, "mumble");
+}
+
+BarPythonClass::BarPythonClass(boost::python::module_builder& m)
+ : boost::python::class_builder