This commit was manufactured by cvs2svn to create tag

'Version_1_21_0'.

[SVN r9525]

example/README

@@ -0,0 +1,6 @@
+To get started with the Boost Python Library, use the examples
+getting_started?.cpp and abstract.cpp.
+
+The files example1.cpp and rwgk1.cpp are obsolete. They are only
+included because the makefiles in the build directory still refer to
+them. This will be fixed later.

example/abstract.cpp

@@ -0,0 +1,34 @@
+// Example by Ullrich Koethe
+#include "boost/python/class_builder.hpp"
+#include <string>
+
+struct Abstract
+{
+    virtual std::string test() = 0;
+};
+
+struct Abstract_callback: Abstract
+{
+    Abstract_callback(PyObject * self)
+    : m_self(self)
+    {}
+
+    std::string test()
+    {
+      return boost::python::callback<std::string>::call_method(m_self, "test");
+    }
+
+    PyObject * m_self;
+};
+
+extern "C"
+DL_EXPORT(void)
+initabstract()
+{
+    boost::python::module_builder a("abstract");
+
+    boost::python::class_builder<Abstract, Abstract_callback>
+        a_class(a, "Abstract");
+    a_class.def(boost::python::constructor<>()); // wrap a constructor
+    a_class.def(&Abstract::test, "test");
+}

example/getting_started1.cpp

@@ -0,0 +1,30 @@
+#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; }
+}
+
+#include <boost/python/class_builder.hpp>
+namespace python = boost::python;
+
+// Python requires an exported function called init<module-name> in every
+// extension module. This is where we build the module contents.
+BOOST_PYTHON_MODULE_INIT(getting_started1)
+{
+  try
+  {
+    // 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");
+  }
+  catch(...)
+  {
+    python::handle_exception(); // Deal with the exception for Python
+  }
+}

example/getting_started2.cpp

@@ -0,0 +1,50 @@
+#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!";
+  }
+}
+
+#include <boost/python/class_builder.hpp>
+namespace python = boost::python;
+
+BOOST_PYTHON_MODULE_INIT(getting_started2)
+{
+  try
+  {
+    // 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");
+  }
+  catch(...)
+  {
+    python::handle_exception(); // Deal with the exception for Python
+  }
+}

example/getting_started3.cpp

@@ -0,0 +1,120 @@
+/*
+    This example shows how to make an Extension Class "pickleable".
+
+    Python's pickle module implements a basic but powerful algorithm
+    for "pickling" (a.k.a. serializing, marshalling or flattening)
+    nearly arbitrary Python objects.
+
+    The user can influence how an Extension Class instance is pickled
+    by defining three special methods: __getinitargs__(),
+    __getstate__(), and __setstate(). This interface is similar to
+    that for regular Python classes as described in detail in the
+    Python Library Reference for pickle:
+
+    http://www.python.org/doc/current/lib/module-pickle.html
+
+    When an Extension Class instance is pickled, __getinitargs__() is
+    called, if implemented. This method should return a tuple
+    containing the arguments to be passed to the class constructor when
+    the object is restored.
+
+    If there is no __getstate__() method, the instance's __dict__ is
+    pickled if it is not empty. If __getstate__() is defined, it should
+    return an object representing the state of the instance.
+
+    If there is no __setstate__() method, __getstate__() must return a
+    dictionary. When the instance is restored, the items in this dictionary
+    are added to the instance's __dict__.
+
+    If the Extension Class defines __setstate__(), the pickle loader
+    calls it with the result of __getstate__() as arguments. In this
+    case, the state object need not be a dictionary.  The
+    __getstate__() and __setstate__() methods can do what they want.
+
+    If both __getinitargs__() and __getstate__() are defined, the
+    instance is restored by first calling the constructor with
+    the result of __getinitargs__() as argument. After the instance
+    is reconstructed, the __dict__ is updated or __setstate__() is
+    called if implemented.
+
+    The mechanism described here is an exact replication of that one
+    implemented by Jim Fulton's ExtensionClass (included in Zope 2.2.2).
+ */
+
+#include <iostream>
+#include <string>
+
+#include <boost/python/class_builder.hpp>
+namespace python = boost::python;
+
+namespace { // Avoid cluttering the global namespace.
+
+  // A friendly class.
+  class world
+  {
+    private:
+      std::string country;
+      int secret_number;
+    public:
+      world(const std::string& country) : secret_number(0) {
+        this->country = country;
+      }
+      std::string greet() const { return "Hello from " + country + "!"; }
+      std::string get_country() const { return country; }
+      void set_secret_number(int number) { secret_number = number; }
+      int get_secret_number() const { return secret_number; }
+  };
+
+  // Support for pickle.
+  python::tuple world_getinitargs(const world& w) {
+      python::tuple result(1);
+      result.set_item(0, w.get_country());
+      return result;
+  }
+
+  python::tuple world_getstate(const world& w) {
+      python::tuple result(1);
+      result.set_item(0, w.get_secret_number());
+      return result;
+  }
+
+  void world_setstate(world& w, python::tuple state) {
+    if (state.size() != 1) {
+      PyErr_SetString(PyExc_ValueError,
+        "Unexpected argument in call to __setstate__.");
+      throw python::error_already_set();
+    }
+    int number = BOOST_PYTHON_CONVERSION::from_python(state[0].get(),
+      python::type<int>());
+    if (number != 42)
+      w.set_secret_number(number);
+  }
+}
+
+BOOST_PYTHON_MODULE_INIT(getting_started3)
+{
+  try
+  {
+    // Create an object representing this extension module.
+    python::module_builder this_module("getting_started3");
+
+    // Create the Python type object for our extension class.
+    python::class_builder<world> world_class(this_module, "world");
+
+    // Add the __init__ function.
+    world_class.def(python::constructor<std::string>());
+    // Add a regular member function.
+    world_class.def(&world::greet, "greet");
+    world_class.def(&world::get_secret_number, "get_secret_number");
+    world_class.def(&world::set_secret_number, "set_secret_number");
+
+    // Support for pickle.
+    world_class.def(world_getinitargs, "__getinitargs__");
+    world_class.def(world_getstate, "__getstate__");
+    world_class.def(world_setstate, "__setstate__");
+  }
+  catch(...)
+  {
+    python::handle_exception(); // Deal with the exception for Python
+  }
+}

example/getting_started4.cpp

@@ -0,0 +1,102 @@
+#include <boost/python/class_builder.hpp>
+namespace python = boost::python;
+
+namespace { // Avoid cluttering the global namespace.
+
+  // A wrapper is used to define additional constructors.
+  //
+  struct vector_double_wrapper: std::vector<double>
+  {
+    // Tell the compiler how to convert a base class object to
+    // this wrapper object.
+    vector_double_wrapper(PyObject*, const std::vector<double>& vd)
+      : std::vector<double>(vd) {}
+
+    vector_double_wrapper(PyObject* self)
+      : std::vector<double>() {}
+
+    vector_double_wrapper(PyObject* self, const int n)
+      : std::vector<double>(n) {}
+
+    vector_double_wrapper(PyObject* self, python::tuple tuple)
+      : std::vector<double>(tuple.size())
+    {
+      std::vector<double>::iterator vd = begin();
+      for (int i = 0; i < tuple.size(); i++)
+        vd[i] = BOOST_PYTHON_CONVERSION::from_python(tuple[i].get(),
+          python::type<double>());
+    }
+  };
+
+  double getitem(const std::vector<double>& vd, const std::size_t key) {
+    return vd[key];
+  }
+
+  void setitem(std::vector<double>& vd, const std::size_t key,
+               const double &d) {
+    std::vector<double>::iterator vditer = vd.begin();
+    vditer[key] = d;
+  }
+
+  void delitem(std::vector<double>& vd, const std::size_t key) {
+    std::vector<double>::iterator vditer = vd.begin();
+    vd.erase(&vditer[key]);
+  }
+
+  // Convert vector_double to a regular Python tuple.
+  //
+  python::tuple as_tuple(const std::vector<double>& vd)
+  {
+    python::tuple t(vd.size());
+    for (int i = 0; i < vd.size(); i++) t.set_item(i,
+      python::ref(BOOST_PYTHON_CONVERSION::to_python(vd[i])));
+    return t;
+  }
+
+  // Function returning a vector_double object to Python.
+  //
+  std::vector<double> foo(const int n)
+  {
+    std::vector<double> vd(n);
+    std::vector<double>::iterator vditer = vd.begin();
+    for (int i = 0; i < n; i++) vditer[i] = double(i);
+    return vd;
+  }
+
+  // Same as foo(), but avoid copying on return.
+  //
+  std::auto_ptr<std::vector<double> > bar(const int n)
+  {
+    std::auto_ptr<std::vector<double> > vdptr(new std::vector<double>(n));
+    std::vector<double>::iterator vditer = vdptr->begin();
+    for (int i = 0; i < n; i++) vditer[i] = double(10 * i);
+    return vdptr;
+  }
+}
+
+BOOST_PYTHON_MODULE_INIT(getting_started4)
+{
+  try
+  {
+    python::module_builder this_module("getting_started4");
+
+    python::class_builder<std::vector<double>, vector_double_wrapper>
+      vector_double(this_module, "vector_double");
+
+    vector_double.def(python::constructor<>());
+    vector_double.def(python::constructor<const int>());
+    vector_double.def(python::constructor<python::tuple>());
+    vector_double.def(&std::vector<double>::size, "__len__");
+    vector_double.def(getitem, "__getitem__");
+    vector_double.def(setitem, "__setitem__");
+    vector_double.def(delitem, "__delitem__");
+    vector_double.def(as_tuple, "as_tuple");
+
+    this_module.def(foo, "foo");
+    this_module.def(bar, "bar");
+  }
+  catch(...)
+  {
+    python::handle_exception(); // Deal with the exception for Python
+  }
+}

example/getting_started5.cpp

@@ -0,0 +1,126 @@
+/*
+   This example shows how to convert a class from and to native
+   Python objects, such as tuples.
+
+   We do not want to expose the helper class MillerIndex as an
+   Extension Class. However, in order to simplify the wrapper code,
+   we want to define from_python() and to_python() functions for
+   class MillerIndex.
+
+   Consider the alternatives:
+
+     - Expose MillerIndex as an Extension Class.
+         We need a constructor MillerIndex(python::tuple).
+         Python function calls become more complex:
+           foo(MillerIndex((1,2,3)) instead of foo((1,2,3))
+         We need a method such as MillerIndex().as_tuple().
+
+     - Define a wrapper function for each function that we
+       want to expose, e.g.:
+          void add(const IndexingSet& ixset, const python::tuple PyMIx)
+
+   The first alternative introduces a new type that the user has to
+   deal with. Other modules using Miller indices might organize them in
+   different ways, for example to increase runtime efficiency for
+   important procedures. This means, the user has to know how to
+   convert between the different kinds of Miller index representations.
+   This can quickly become a nuisance. Relying on native Python data
+   structures minimizes the number of special types the user has to
+   learn and convert. Of course, this argument is only valid for
+   small and relatively simply classes.
+
+   If there are many member functions with MillerIndex arguments, the
+   second alternative is impractical, and concentrating the conversion
+   mechanism in one central place is essential for code
+   maintainability.  An added benefit is that more convenient (smarter)
+   conversion functions can be provided without cluttering the rest of
+   the wrapper code.
+
+ */
+
+#include <string>
+#include <vector>
+#include <boost/python/class_builder.hpp>
+namespace python = boost::python;
+
+namespace { // Avoid cluttering the global namespace.
+
+  // The helper class.
+  //
+  class MillerIndex {
+    public:
+      int v[3];
+  };
+
+  // The main class. Imagine that there are MANY member functions
+  // like add() and get().
+  //
+  class IndexingSet {
+    private:
+      std::vector<MillerIndex> VMIx;
+    public:
+      void add(const MillerIndex& MIx) { VMIx.push_back(MIx); }
+      MillerIndex get(const std::size_t i) const { return VMIx[i]; }
+  };
+}
+
+BOOST_PYTHON_BEGIN_CONVERSION_NAMESPACE
+
+  // Convert a Python tuple to a MillerIndex object.
+  //
+  MillerIndex from_python(PyObject* p, python::type<const MillerIndex&>)
+  {
+    python::tuple tup
+      = python::tuple(python::ref(p, python::ref::increment_count));
+    if (tup.size() != 3) {
+      PyErr_SetString(PyExc_ValueError,
+        "expecting exactly 3 values in tuple.");
+      throw python::error_already_set();
+    }
+    MillerIndex result;
+    for (int i = 0; i < 3; i++)
+      result.v[i] = from_python(tup[i].get(), python::type<int>());
+    return result;
+  }
+
+  // Similar conversion for MillerIndex objects passed by value.
+  // Not actually used, but included to show the principle.
+  //
+  MillerIndex from_python(PyObject* p, python::type<MillerIndex>)
+  {
+    return from_python(p, python::type<const MillerIndex&>());
+  }
+
+  // Convert a MillerIndex object to a Python tuple.
+  //
+  PyObject* to_python(const MillerIndex& hkl)
+  {
+    python::tuple result(3);
+    for (int i = 0; i < 3; i++)
+      result.set_item(i, python::ref(to_python(hkl.v[i])));
+    return result.reference().release();
+  }
+
+BOOST_PYTHON_END_CONVERSION_NAMESPACE
+
+BOOST_PYTHON_MODULE_INIT(getting_started5)
+{
+  try
+  {
+    // Create an object representing this extension module.
+    python::module_builder this_module("getting_started5");
+
+    // Create the Python type object for our extension class.
+    python::class_builder<IndexingSet> ixset_class(this_module, "IndexingSet");
+
+    // Add the __init__ function.
+    ixset_class.def(python::constructor<>());
+    // Add the member functions.
+    ixset_class.def(&IndexingSet::add, "add");
+    ixset_class.def(&IndexingSet::get, "get");
+  }
+  catch(...)
+  {
+    python::handle_exception(); // Deal with the exception for Python
+  }
+}

example/rwgk1.cpp

@@ -0,0 +1,41 @@
+#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; }
+}
+
+#include <boost/python/class_builder.hpp>
+
+namespace python = boost::python;
+
+// Python requires an exported function called init<module-name> in every
+// extension module. This is where we build the module contents.
+extern "C"
+#ifdef _WIN32
+__declspec(dllexport)
+#endif
+void initrwgk1()
+{
+  try
+  {
+    // Create an object representing this extension module.
+    python::module_builder this_module("rwgk1");
+
+    // Add regular functions to the module.
+    this_module.def(greet, "greet");
+    this_module.def(square, "square");
+  }
+  catch(...)
+  {
+    python::handle_exception(); // Deal with the exception for Python
+  }
+}
+
+// Win32 DLL boilerplate
+#if defined(_WIN32)
+#include <windows.h>
+extern "C" BOOL WINAPI DllMain(HINSTANCE, DWORD, LPVOID) { return 1; }
+#endif // _WIN32

example/test_abstract.py

@@ -0,0 +1,23 @@
+# Example by Ullrich Koethe
+r'''>>> from abstract import *
+    >>> class A(Abstract):
+    ...     def __init__(self, text):
+    ...             Abstract.__init__(self)  # call the base class constructor
+    ...             self.text = text
+    ...     def test(self):                  # implement abstract function
+    ...             return self.text
+    ...
+    >>> a = A("Hello")
+    >>> a.test()
+    'Hello'
+'''
+
+def run(args = None):
+    if args is not None:
+        import sys
+        sys.argv = args
+    import doctest, test_abstract
+    doctest.testmod(test_abstract)
+
+if __name__ == '__main__':
+    run()

example/test_getting_started1.py

@@ -0,0 +1,17 @@
+r'''>>> import getting_started1
+    >>> print getting_started1.greet()
+    hello, world
+    >>> number = 11
+    >>> print number, '*', number, '=', getting_started1.square(number)
+    11 * 11 = 121
+'''
+
+def run(args = None):
+    if args is not None:
+        import sys
+        sys.argv = args
+    import doctest, test_getting_started1
+    doctest.testmod(test_getting_started1)
+
+if __name__ == '__main__':
+    run()

example/test_getting_started2.py

@@ -0,0 +1,29 @@
+r'''>>> 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!'
+
+    >>> 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!'
+'''
+
+def run(args = None):
+    if args is not None:
+        import sys
+        sys.argv = args
+    import doctest, test_getting_started2
+    doctest.testmod(test_getting_started2)
+
+if __name__ == '__main__':
+    run()

example/test_getting_started3.py

@@ -0,0 +1,56 @@
+r'''>>> import getting_started3
+    >>> import re
+    >>> import pickle
+    >>> getting_started3.world.__module__
+    'getting_started3'
+    >>> getting_started3.world.__safe_for_unpickling__
+    1
+    >>> getting_started3.world.__reduce__()
+    'world'
+    >>> assert re.match(
+    ... "\(<extension class getting_started3.world at [0-9a-fA-FxX]+>, \('Hello',\), \(0,\)\)",
+    ... repr(getting_started3.world('Hello').__reduce__()))
+    >>>
+    >>> for number in (24, 42):
+    ...   wd = getting_started3.world('California')
+    ...   wd.set_secret_number(number)
+    ...   pstr = pickle.dumps(wd)
+    ...   print pstr
+    ...   wl = pickle.loads(pstr)
+    ...   print wd.greet(), wd.get_secret_number()
+    ...   print wl.greet(), wl.get_secret_number()
+    cgetting_started3
+    world
+    p0
+    (S'California'
+    p1
+    tp2
+    R(I24
+    tp3
+    bp4
+    .
+    Hello from California! 24
+    Hello from California! 24
+    cgetting_started3
+    world
+    p0
+    (S'California'
+    p1
+    tp2
+    R(I42
+    tp3
+    bp4
+    .
+    Hello from California! 42
+    Hello from California! 0
+'''
+
+def run(args = None):
+    if args is not None:
+        import sys
+        sys.argv = args
+    import doctest, test_getting_started3
+    doctest.testmod(test_getting_started3)
+
+if __name__ == '__main__':
+    run()

example/test_getting_started4.py

@@ -0,0 +1,35 @@
+r'''>>> import getting_started4
+    >>> v=getting_started4.vector_double()
+    >>> print v.as_tuple()
+    ()
+    >>> v=getting_started4.vector_double(5)
+    >>> print v.as_tuple()
+    (0.0, 0.0, 0.0, 0.0, 0.0)
+    >>> print len(v)
+    5
+    >>> v=getting_started4.vector_double((3,4,5))
+    >>> print v.as_tuple()
+    (3.0, 4.0, 5.0)
+    >>> print v[1]
+    4.0
+    >>> v[1] = 40
+    >>> print v.as_tuple()
+    (3.0, 40.0, 5.0)
+    >>> del v[1]
+    >>> print v.as_tuple()
+    (3.0, 5.0)
+    >>> print getting_started4.foo(11).as_tuple()
+    (0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0)
+    >>> print getting_started4.bar(12).as_tuple()
+    (0.0, 10.0, 20.0, 30.0, 40.0, 50.0, 60.0, 70.0, 80.0, 90.0, 100.0, 110.0)
+'''
+
+def run(args = None):
+    if args is not None:
+        import sys
+        sys.argv = args
+    import doctest, test_getting_started4
+    doctest.testmod(test_getting_started4)
+
+if __name__ == '__main__':
+    run()

example/test_getting_started5.py

@@ -0,0 +1,22 @@
+r'''>>> import getting_started5
+    >>> ixset = getting_started5.IndexingSet()
+    >>> ixset.add((1,2,3))
+    >>> ixset.add((4,5,6))
+    >>> ixset.add((7,8,9))
+    >>> print ixset.get(0)
+    (1, 2, 3)
+    >>> print ixset.get(1)
+    (4, 5, 6)
+    >>> print ixset.get(2)
+    (7, 8, 9)
+'''
+
+def run(args = None):
+    if args is not None:
+        import sys
+        sys.argv = args
+    import doctest, test_getting_started5
+    doctest.testmod(test_getting_started5)
+
+if __name__ == '__main__':
+    run()

example/test_rwgk1.py

@@ -0,0 +1,17 @@
+r'''>>> import rwgk1
+    >>> print rwgk1.greet()
+    hello, world
+    >>> number = 11
+    >>> print number, '*', number, '=', rwgk1.square(number)
+    11 * 11 = 121
+'''
+
+def run(args = None):
+    if args is not None:
+        import sys
+        sys.argv = args
+    import doctest, test_rwgk1
+    doctest.testmod(test_rwgk1)
+
+if __name__ == '__main__':
+    run()