Boost.Python is an open source C++ library which provides a concise
+IDL-like interface for binding C++ classes and functions to
+Python. Leveraging the full power of C++ compile-time introspection
+and of recently developed metaprogramming techniques, this is achieved
+entirely in pure C++, without introducing a new syntax.
+Boost.Python's rich set of features and high-level interface make it
+possible to engineer packages from the ground up as hybrid systems,
+giving programmers easy and coherent access to both the efficient
+compile-time polymorphism of C++ and the extremely convenient run-time
+polymorphism of Python.
Python and C++ are in many ways as different as two languages could
+be: while C++ is usually compiled to machine-code, Python is
+interpreted. Python's dynamic type system is often cited as the
+foundation of its flexibility, while in C++ static typing is the
+cornerstone of its efficiency. C++ has an intricate and difficult
+compile-time meta-language, while in Python, practically everything
+happens at runtime.
+
Yet for many programmers, these very differences mean that Python and
+C++ complement one another perfectly. Performance bottlenecks in
+Python programs can be rewritten in C++ for maximal speed, and
+authors of powerful C++ libraries choose Python as a middleware
+language for its flexible system integration capabilities.
+Furthermore, the surface differences mask some strong similarities:
+
+
'C'-family control structures (if, while, for...)
+
Support for object-orientation, functional programming, and generic
+programming (these are both multi-paradigm programming languages.)
+
Comprehensive operator overloading facilities, recognizing the
+importance of syntactic variability for readability and
+expressivity.
+
High-level concepts such as collections and iterators.
+
High-level encapsulation facilities (C++: namespaces, Python: modules)
+to support the design of re-usable libraries.
+
Exception-handling for effective management of error conditions.
+
C++ idioms in common use, such as handle/body classes and
+reference-counted smart pointers mirror Python reference semantics.
+
+
Given Python's rich 'C' interoperability API, it should in principle
+be possible to expose C++ type and function interfaces to Python with
+an analogous interface to their C++ counterparts. However, the
+facilities provided by Python alone for integration with C++ are
+relatively meager. Compared to C++ and Python, 'C' has only very
+rudimentary abstraction facilities, and support for exception-handling
+is completely missing. 'C' extension module writers are required to
+manually manage Python reference counts, which is both annoyingly
+tedious and extremely error-prone. Traditional extension modules also
+tend to contain a great deal of boilerplate code repetition which
+makes them difficult to maintain, especially when wrapping an evolving
+API.
+
These limitations have lead to the development of a variety of wrapping
+systems. SWIG is probably the most popular package for the
+integration of C/C++ and Python. A more recent development is SIP,
+which was specifically designed for interfacing Python with the Qt
+graphical user interface library. Both SWIG and SIP introduce their
+own specialized languages for customizing inter-language bindings.
+This has certain advantages, but having to deal with three different
+languages (Python, C/C++ and the interface language) also introduces
+practical and mental difficulties. The CXX package demonstrates an
+interesting alternative. It shows that at least some parts of
+Python's 'C' API can be wrapped and presented through a much more
+user-friendly C++ interface. However, unlike SWIG and SIP, CXX does
+not include support for wrapping C++ classes as new Python types.
+
The features and goals of Boost.Python overlap significantly with
+many of these other systems. That said, Boost.Python attempts to
+maximize convenience and flexibility without introducing a separate
+wrapping language. Instead, it presents the user with a high-level
+C++ interface for wrapping C++ classes and functions, managing much of
+the complexity behind-the-scenes with static metaprogramming.
+Boost.Python also goes beyond the scope of earlier systems by
+providing:
+
+
Support for C++ virtual functions that can be overridden in Python.
+
Comprehensive lifetime management facilities for low-level C++
+pointers and references.
+
Support for organizing extensions as Python packages,
+with a central registry for inter-language type conversions.
+
A safe and convenient mechanism for tying into Python's powerful
+serialization engine (pickle).
+
Coherence with the rules for handling C++ lvalues and rvalues that
+can only come from a deep understanding of both the Python and C++
+type systems.
+
+
The key insight that sparked the development of Boost.Python is that
+much of the boilerplate code in traditional extension modules could be
+eliminated using C++ compile-time introspection. Each argument of a
+wrapped C++ function must be extracted from a Python object using a
+procedure that depends on the argument type. Similarly the function's
+return type determines how the return value will be converted from C++
+to Python. Of course argument and return types are part of each
+function's type, and this is exactly the source from which
+Boost.Python deduces most of the information required.
+
This approach leads to user guided wrapping: as much information is
+extracted directly from the source code to be wrapped as is possible
+within the framework of pure C++, and some additional information is
+supplied explicitly by the user. Mostly the guidance is mechanical
+and little real intervention is required. Because the interface
+specification is written in the same full-featured language as the
+code being exposed, the user has unprecedented power available when
+she does need to take control.
The primary goal of Boost.Python is to allow users to expose C++
+classes and functions to Python using nothing more than a C++
+compiler. In broad strokes, the user experience should be one of
+directly manipulating C++ objects from Python.
+
However, it's also important not to translate all interfaces too
+literally: the idioms of each language must be respected. For
+example, though C++ and Python both have an iterator concept, they are
+expressed very differently. Boost.Python has to be able to bridge the
+interface gap.
+
It must be possible to insulate Python users from crashes resulting
+from trivial misuses of C++ interfaces, such as accessing
+already-deleted objects. By the same token the library should
+insulate C++ users from low-level Python 'C' API, replacing
+error-prone 'C' interfaces like manual reference-count management and
+raw PyObject pointers with more-robust alternatives.
+
Support for component-based development is crucial, so that C++ types
+exposed in one extension module can be passed to functions exposed in
+another without loss of crucial information like C++ inheritance
+relationships.
+
Finally, all wrapping must be non-intrusive, without modifying or
+even seeing the original C++ source code. Existing C++ libraries have
+to be wrappable by third parties who only have access to header files
+and binaries.
And now for a preview of Boost.Python, and how it improves on the raw
+facilities offered by Python. Here's a function we might want to
+expose:
+
+char const* greet(unsigned x)
+{
+ static char const* const msgs[] = { "hello", "Boost.Python", "world!" };
+
+ if (x > 2)
+ throw std::range_error("greet: index out of range");
+
+ return msgs[x];
+}
+
+
To wrap this function in standard C++ using the Python 'C' API, we'd
+need something like this:
+
+extern "C" // all Python interactions use 'C' linkage and calling convention
+{
+ // Wrapper to handle argument/result conversion and checking
+ PyObject* greet_wrap(PyObject* args, PyObject * keywords)
+ {
+ int x;
+ if (PyArg_ParseTuple(args, "i", &x)) // extract/check arguments
+ {
+ char const* result = greet(x); // invoke wrapped function
+ return PyString_FromString(result); // convert result to Python
+ }
+ return 0; // error occurred
+ }
+
+ // Table of wrapped functions to be exposed by the module
+ static PyMethodDef methods[] = {
+ { "greet", greet_wrap, METH_VARARGS, "return one of 3 parts of a greeting" }
+ , { NULL, NULL, 0, NULL } // sentinel
+ };
+
+ // module initialization function
+ DL_EXPORT init_hello()
+ {
+ (void) Py_InitModule("hello", methods); // add the methods to the module
+ }
+}
+
+
Now here's the wrapping code we'd use to expose it with Boost.Python:
+
+#include <boost/python.hpp>
+using namespace boost::python;
+BOOST_PYTHON_MODULE(hello)
+{
+ def("greet", greet, "return one of 3 parts of a greeting");
+}
+
+
and here it is in action:
+
+>>> import hello
+>>> for x in range(3):
+... print hello.greet(x)
+...
+hello
+Boost.Python
+world!
+
+
Aside from the fact that the 'C' API version is much more verbose,
+it's worth noting a few things that it doesn't handle correctly:
+
+
The original function accepts an unsigned integer, and the Python
+'C' API only gives us a way of extracting signed integers. The
+Boost.Python version will raise a Python exception if we try to pass
+a negative number to hello.greet, but the other one will proceed
+to do whatever the C++ implementation does when converting an
+negative integer to unsigned (usually wrapping to some very large
+number), and pass the incorrect translation on to the wrapped
+function.
+
That brings us to the second problem: if the C++ greet()
+function is called with a number greater than 2, it will throw an
+exception. Typically, if a C++ exception propagates across the
+boundary with code generated by a 'C' compiler, it will cause a
+crash. As you can see in the first version, there's no C++
+scaffolding there to prevent this from happening. Functions wrapped
+by Boost.Python automatically include an exception-handling layer
+which protects Python users by translating unhandled C++ exceptions
+into a corresponding Python exception.
+
A slightly more-subtle limitation is that the argument conversion
+used in the Python 'C' API case can only get that integer x in
+one way. PyArg_ParseTuple can't convert Python long objects
+(arbitrary-precision integers) which happen to fit in an unsigned
+int but not in a signed long, nor will it ever handle a
+wrapped C++ class with a user-defined implicit operator unsigned
+int() conversion. Boost.Python's dynamic type conversion
+registry allows users to add arbitrary conversion methods.
Although this code has a certain pythonic familiarity, people
+sometimes find the syntax bit confusing because it doesn't look like
+most of the C++ code they're used to. All the same, this is just
+standard C++. Because of their flexible syntax and operator
+overloading, C++ and Python are great for defining domain-specific
+(sub)languages
+(DSLs), and that's what we've done in Boost.Python. To break it down:
+
+class_<World>("World")
+
+
constructs an unnamed object of type class_<World> and passes
+"World" to its constructor. This creates a new-style Python class
+called World in the extension module, and associates it with the
+C++ type World in the Boost.Python type conversion registry. We
+might have also written:
+
+class_<World> w("World");
+
+
but that would've been more verbose, since we'd have to name w
+again to invoke its def() member function:
+
+w.def("greet", &World::greet)
+
+
There's nothing special about the location of the dot for member
+access in the original example: C++ allows any amount of whitespace on
+either side of a token, and placing the dot at the beginning of each
+line allows us to chain as many successive calls to member functions
+as we like with a uniform syntax. The other key fact that allows
+chaining is that class_<> member functions all return a reference
+to *this.
It's occasionally useful to be able to break down the components of a
+Boost.Python class wrapper in this way, but the rest of this article
+will stick to the terse syntax.
+
For completeness, here's the wrapped class in use:
Since our World class is just a plain struct, it has an
+implicit no-argument (nullary) constructor. Boost.Python exposes the
+nullary constructor by default, which is why we were able to write:
+
+>>> planet = hello.World()
+
+
However, well-designed classes in any language may require constructor
+arguments in order to establish their invariants. Unlike Python,
+where __init__ is just a specially-named method, In C++
+constructors cannot be handled like ordinary member functions. In
+particular, we can't take their address: &World::World is an
+error. The library provides a different interface for specifying
+constructors. Given:
This does not result in adding attributes to the World instance
+__dict__, which can result in substantial memory savings when
+wrapping large data structures. In fact, no instance __dict__
+will be created at all unless attributes are explicitly added from
+Python. Boost.Python owes this capability to the new Python 2.2 type
+system, in particular the descriptor interface and property type.
+
In C++, publicly-accessible data members are considered a sign of poor
+design because they break encapsulation, and style guides usually
+dictate the use of "getter" and "setter" functions instead. In
+Python, however, __getattr__, __setattr__, and since 2.2,
+property mean that attribute access is just one more
+well-encapsulated syntactic tool at the programmer's disposal.
+Boost.Python bridges this idiomatic gap by making Python property
+creation directly available to users. If msg were private, we
+could still expose it as attribute in Python as follows:
The ability to write arithmetic operators for user-defined types has
+been a major factor in the success of both languages for numerical
+computation, and the success of packages like NumPy attests to the
+power of exposing operators in extension modules. Boost.Python
+provides a concise mechanism for wrapping operator overloads. The
+example below shows a fragment from a wrapper for the Boost rational
+number library:
The magic is performed using a simplified application of "expression
+templates" [VELD1995], a technique originally developed for
+optimization of high-performance matrix algebra expressions. The
+essence is that instead of performing the computation immediately,
+operators are overloaded to construct a type representing the
+computation. In matrix algebra, dramatic optimizations are often
+available when the structure of an entire expression can be taken into
+account, rather than evaluating each operation "greedily".
+Boost.Python uses the same technique to build an appropriate Python
+method object based on expressions involving self.
C++ inheritance relationships can be represented to Boost.Python by adding
+an optional bases<...> argument to the class_<...> template
+parameter list as follows:
When the class_<...> is created, Python type objects
+corresponding to Base1 and Base2 are looked up in
+Boost.Python's registry, and are used as bases for the new Python
+Derived type object, so methods exposed for the Python Base1
+and Base2 types are automatically members of the Derived
+type. Because the registry is global, this works correctly even if
+Derived is exposed in a different module from either of its
+bases.
+
C++ conversions from Derived to its bases are added to the
+Boost.Python registry. Thus wrapped C++ methods expecting (a
+pointer or reference to) an object of either base type can be
+called with an object wrapping a Derived instance. Wrapped
+member functions of class T are treated as though they have an
+implicit first argument of T&, so these conversions are
+neccessary to allow the base class methods to be called for derived
+objects.
+
+
Of course it's possible to derive new Python classes from wrapped C++
+class instances. Because Boost.Python uses the new-style class
+system, that works very much as for the Python built-in types. There
+is one significant detail in which it differs: the built-in types
+generally establish their invariants in their __new__ function, so
+that derived classes do not need to call __init__ on the base
+class before invoking its methods :
Because C++ object construction is a one-step operation, C++ instance
+data cannot be constructed until the arguments are available, in the
+__init__ function:
+
+>>> class D(SomeBoostPythonClass):
+... def __init__(self):
+... pass
+...
+>>> D().some_boost_python_method()
+Traceback (most recent call last):
+ File "<stdin>", line 1, in ?
+TypeError: bad argument type for built-in operation
+
+
This happened because Boost.Python couldn't find instance data of type
+SomeBoostPythonClass within the D instance; D's __init__
+function masked construction of the base class. It could be corrected
+by either removing D's __init__ function or having it call
+SomeBoostPythonClass.__init__(...) explicitly.
Deriving new types in Python from extension classes is not very
+interesting unless they can be used polymorphically from C++. In
+other words, Python method implementations should appear to override
+the implementation of C++ virtual functions when called through base
+class pointers/references from C++. Since the only way to alter the
+behavior of a virtual function is to override it in a derived class,
+the user must build a special derived class to dispatch a polymorphic
+class' virtual functions:
+
+//
+// interface to wrap:
+//
+class Base
+{
+ public:
+ virtual int f(std::string x) { return 42; }
+ virtual ~Base();
+};
+
+int calls_f(Base const& b, std::string x) { return b.f(x); }
+
+//
+// Wrapping Code
+//
+
+// Dispatcher class
+struct BaseWrap : Base
+{
+ // Store a pointer to the Python object
+ BaseWrap(PyObject* self_) : self(self_) {}
+ PyObject* self;
+
+ // Default implementation, for when f is not overridden
+ int f_default(std::string x) { return this->Base::f(x); }
+ // Dispatch implementation
+ int f(std::string x) { return call_method<int>(self, "f", x); }
+};
+
+...
+ def("calls_f", calls_f);
+ class_<Base, BaseWrap>("Base")
+ .def("f", &Base::f, &BaseWrap::f_default)
+ ;
+
The key element which allows overriding in Python is the
+call_method invocation, which uses the same global type
+conversion registry as the C++ function wrapping does to convert its
+arguments from C++ to Python and its return type from Python to C++.
+
Any constructor signatures you wish to wrap must be replicated with
+an initial PyObject* argument
+
The dispatcher must store this argument so that it can be used to
+invoke call_method
+
The f_default member function is needed when the function being
+exposed is not pure virtual; there's no other way Base::f can be
+called on an object of type BaseWrap, since it overrides f.
Admittedly, this formula is tedious to repeat, especially on a project
+with many polymorphic classes. That it is neccessary reflects some
+limitations in C++'s compile-time introspection capabilities: there's
+no way to enumerate the members of a class and find out which are
+virtual functions. At least one very promising project has been
+started to write a front-end which can generate these dispatchers (and
+other wrapping code) automatically from C++ headers.
+
Pyste is being developed by Bruno da Silva de Oliveira. It builds on
+GCC_XML, which generates an XML version of GCC's internal program
+representation. Since GCC is a highly-conformant C++ compiler, this
+ensures correct handling of the most-sophisticated template code and
+full access to the underlying type system. In keeping with the
+Boost.Python philosophy, a Pyste interface description is neither
+intrusive on the code being wrapped, nor expressed in some unfamiliar
+language: instead it is a 100% pure Python script. If Pyste is
+successful it will mark a move away from wrapping everything directly
+in C++ for many of our users. It will also allow us the choice to
+shift some of the metaprogram code from C++ to Python. We expect that
+soon, not only our users but the Boost.Python developers themselves
+will be "thinking hybrid" about their own code.
Serialization is the process of converting objects in memory to a
+form that can be stored on disk or sent over a network connection. The
+serialized object (most often a plain string) can be retrieved and
+converted back to the original object. A good serialization system will
+automatically convert entire object hierarchies. Python's standard
+pickle module is just such a system. It leverages the language's strong
+runtime introspection facilities for serializing practically arbitrary
+user-defined objects. With a few simple and unintrusive provisions this
+powerful machinery can be extended to also work for wrapped C++ objects.
+Here is an example:
Of course the cPickle module can also be used for faster
+processing.
+
Boost.Python's pickle_suite fully supports the pickle protocol
+defined in the standard Python documentation. Like a __getinitargs__
+function in Python, the pickle_suite's getinitargs() is responsible for
+creating the argument tuple that will be use to reconstruct the pickled
+object. The other elements of the Python pickling protocol,
+__getstate__ and __setstate__ can be optionally provided via C++
+getstate and setstate functions. C++'s static type system allows the
+library to ensure at compile-time that nonsensical combinations of
+functions (e.g. getstate without setstate) are not used.
+
Enabling serialization of more complex C++ objects requires a little
+more work than is shown in the example above. Fortunately the
+object interface (see next section) greatly helps in keeping the
+code manageable.
Experienced 'C' language extension module authors will be familiar
+with the ubiquitous PyObject*, manual reference-counting, and the
+need to remember which API calls return "new" (owned) references or
+"borrowed" (raw) references. These constraints are not just
+cumbersome but also a major source of errors, especially in the
+presence of exceptions.
+
Boost.Python provides a class object which automates reference
+counting and provides conversion to Python from C++ objects of
+arbitrary type. This significantly reduces the learning effort for
+prospective extension module writers.
+
Creating an object from any other type is extremely simple:
+
+object s("hello, world"); // s manages a Python string
+
+
object has templated interactions with all other types, with
+automatic to-python conversions. It happens so naturally that it's
+easily overlooked:
+
+object ten_Os = 10 * s[4]; // -> "oooooooooo"
+
+
In the example above, 4 and 10 are converted to Python objects
+before the indexing and multiplication operations are invoked.
+
The extract<T> class template can be used to convert Python objects
+to C++ types:
+
+double x = extract<double>(o);
+
+
If a conversion in either direction cannot be performed, an
+appropriate exception is thrown at runtime.
+
The object type is accompanied by a set of derived types
+that mirror the Python built-in types such as list, dict,
+tuple, etc. as much as possible. This enables convenient
+manipulation of these high-level types from C++:
This almost looks and works like regular Python code, but it is pure
+C++. Of course we can wrap C++ functions which accept or return
+object instances.
Because of the practical and mental difficulties of combining
+programming languages, it is common to settle a single language at the
+outset of any development effort. For many applications, performance
+considerations dictate the use of a compiled language for the core
+algorithms. Unfortunately, due to the complexity of the static type
+system, the price we pay for runtime performance is often a
+significant increase in development time. Experience shows that
+writing maintainable C++ code usually takes longer and requires far
+more hard-earned working experience than developing comparable Python
+code. Even when developers are comfortable working exclusively in
+compiled languages, they often augment their systems by some type of
+ad hoc scripting layer for the benefit of their users without ever
+availing themselves of the same advantages.
+
Boost.Python enables us to think hybrid. Python can be used for
+rapidly prototyping a new application; its ease of use and the large
+pool of standard libraries give us a head start on the way to a
+working system. If necessary, the working code can be used to
+discover rate-limiting hotspots. To maximize performance these can
+be reimplemented in C++, together with the Boost.Python bindings
+needed to tie them back into the existing higher-level procedure.
+
Of course, this top-down approach is less attractive if it is clear
+from the start that many algorithms will eventually have to be
+implemented in C++. Fortunately Boost.Python also enables us to
+pursue a bottom-up approach. We have used this approach very
+successfully in the development of a toolbox for scientific
+applications. The toolbox started out mainly as a library of C++
+classes with Boost.Python bindings, and for a while the growth was
+mainly concentrated on the C++ parts. However, as the toolbox is
+becoming more complete, more and more newly added functionality can be
+implemented in Python.
+
+
This figure shows the estimated ratio of newly added C++ and Python
+code over time as new algorithms are implemented. We expect this
+ratio to level out near 70% Python. Being able to solve new problems
+mostly in Python rather than a more difficult statically typed
+language is the return on our investment in Boost.Python. The ability
+to access all of our code from Python allows a broader group of
+developers to use it in the rapid development of new applications.
The first version of Boost.Python was developed in 2000 by Dave
+Abrahams at Dragon Systems, where he was privileged to have Tim Peters
+as a guide to "The Zen of Python". One of Dave's jobs was to develop
+a Python-based natural language processing system. Since it was
+eventually going to be targeting embedded hardware, it was always
+assumed that the compute-intensive core would be rewritten in C++ to
+optimize speed and memory footprint1. The project also wanted to
+test all of its C++ code using Python test scripts2. The only
+tool we knew of for binding C++ and Python was SWIG, and at the time
+its handling of C++ was weak. It would be false to claim any deep
+insight into the possible advantages of Boost.Python's approach at
+this point. Dave's interest and expertise in fancy C++ template
+tricks had just reached the point where he could do some real damage,
+and Boost.Python emerged as it did because it filled a need and
+because it seemed like a cool thing to try.
+
This early version was aimed at many of the same basic goals we've
+described in this paper, differing most-noticeably by having a
+slightly more cumbersome syntax and by lack of special support for
+operator overloading, pickling, and component-based development.
+These last three features were quickly added by Ullrich Koethe and
+Ralf Grosse-Kunstleve3, and other enthusiastic contributors arrived
+on the scene to contribute enhancements like support for nested
+modules and static member functions.
+
By early 2001 development had stabilized and few new features were
+being added, however a disturbing new fact came to light: Ralf had
+begun testing Boost.Python on pre-release versions of a compiler using
+the EDG front-end, and the mechanism at the core of Boost.Python
+responsible for handling conversions between Python and C++ types was
+failing to compile. As it turned out, we had been exploiting a very
+common bug in the implementation of all the C++ compilers we had
+tested. We knew that as C++ compilers rapidly became more
+standards-compliant, the library would begin failing on more
+platforms. Unfortunately, because the mechanism was so central to the
+functioning of the library, fixing the problem looked very difficult.
+
Fortunately, later that year Lawrence Berkeley and later Lawrence
+Livermore National labs contracted with Boost Consulting for support
+and development of Boost.Python, and there was a new opportunity to
+address fundamental issues and ensure a future for the library. A
+redesign effort began with the low level type conversion architecture,
+building in standards-compliance and support for component-based
+development (in contrast to version 1 where conversions had to be
+explicitly imported and exported across module boundaries). A new
+analysis of the relationship between the Python and C++ objects was
+done, resulting in more intuitive handling for C++ lvalues and
+rvalues.
+
The emergence of a powerful new type system in Python 2.2 made the
+choice of whether to maintain compatibility with Python 1.5.2 easy:
+the opportunity to throw away a great deal of elaborate code for
+emulating classic Python classes alone was too good to pass up. In
+addition, Python iterators and descriptors provided crucial and
+elegant tools for representing similar C++ constructs. The
+development of the generalized object interface allowed us to
+further shield C++ programmers from the dangers and syntactic burdens
+of the Python 'C' API. A great number of other features including C++
+exception translation, improved support for overloaded functions, and
+most significantly, CallPolicies for handling pointers and
+references, were added during this period.
+
In October 2002, version 2 of Boost.Python was released. Development
+since then has concentrated on improved support for C++ runtime
+polymorphism and smart pointers. Peter Dimov's ingenious
+boost::shared_ptr design in particular has allowed us to give the
+hybrid developer a consistent interface for moving objects back and
+forth across the language barrier without loss of information. At
+first, we were concerned that the sophistication and complexity of the
+Boost.Python v2 implementation might discourage contributors, but the
+emergence of Pyste and several other significant feature
+contributions have laid those fears to rest. Daily questions on the
+Python C++-sig and a backlog of desired improvements show that the
+library is getting used. To us, the future looks bright.
Boost.Python achieves seamless interoperability between two rich and
+complimentary language environments. Because it leverages template
+metaprogramming to introspect about types and functions, the user
+never has to learn a third syntax: the interface definitions are
+written in concise and maintainable C++. Also, the wrapping system
+doesn't have to parse C++ headers or represent the type system: the
+compiler does that work for us.
+
Computationally intensive tasks play to the strengths of C++ and are
+often impossible to implement efficiently in pure Python, while jobs
+like serialization that are trivial in Python can be very difficult in
+pure C++. Given the luxury of building a hybrid software system from
+the ground up, we can approach design with new confidence and power.
In retrospect, it seems that "thinking hybrid" from the
+ground up might have been better for the NLP system: the
+natural component boundaries defined by the pure python
+prototype turned out to be inappropriate for getting the
+desired performance and memory footprint out of the C++ core,
+which eventually caused some redesign overhead on the Python
+side when the core was moved to C++.
We also have some reservations about driving all C++
+testing through a Python interface, unless that's the only way
+it will be ultimately used. Any transition across language
+boundaries with such different object models can inevitably
+mask bugs.
[1]
+ Note that although we tested earlier versions of Boost.Python with Python
+ 2.2, and we don't think we've done anything
+ to break compatibility, this release of Boost.Python may not have been
+ tested with versions of Python earlier than 2.4, so we're not 100% sure
+ that python 2.2 and 2.3 are supported.
+
+ There are two basic models for combining C++ and Python:
+
+
+
+ extending,
+ in which the end-user launches the Python interpreter executable and
+ imports Python “extension modules” written in C++. Think of taking
+ a library written in C++ and giving it a Python interface so Python programmers
+ can use it. From Python, these modules look just like regular Python
+ modules.
+
+
+ embedding,
+ in which the end-user launches a program written in C++ that in turn
+ invokes the Python interpreter as a library subroutine. Think of adding
+ scriptability to an existing application.
+
+
+
+ The key distinction between extending and embedding is the location of the
+ C++ main()
+ function: in the Python interpreter executable, or in some other program,
+ respectively. Note that even when embedding Python in another program, extension
+ modules are often the best way to make C/C++ functionality accessible to
+ Python code, so the use of extension modules is really at the heart
+ of both models.
+
+
+ Except in rare cases, extension modules are built as dynamically-loaded libraries
+ with a single entry point, which means you can change them without rebuilding
+ either the other extension modules or the executable containing main().
+
+ If—instead of letting Boost.Build construct and link with the right libraries
+ automatically—you choose to use a pre-built Boost.Python library, you'll
+ need to think about which one to link with. The Boost.Python binary comes
+ in both static and dynamic flavors. Take care to choose the right flavor
+ for your application. [3]
+
+ The dynamic library is the safest and most-versatile choice:
+
+
+
+ A single copy of the library code is used by all extension modules
+ built with a given toolset. [4]
+
+
+ The library contains a type conversion registry. Because one registry
+ is shared among all extension modules, instances of a class exposed
+ to Python in one dynamically-loaded extension module can be passed
+ to functions exposed in another such module.
+
+ It might be appropriate to use the static Boost.Python library in any of
+ the following cases:
+
+
+
+ You are extending
+ python and the types exposed in your dynamically-loaded extension module
+ don't need to be used by any other Boost.Python extension modules,
+ and you don't care if the core library code is duplicated among them.
+
+
+ You are embedding
+ python in your application and either:
+
+
+ You are targeting a Unix variant OS other than MacOS or AIX,
+ where the dynamically-loaded extension modules can “see”
+ the Boost.Python library symbols that are part of the executable.
+
+
+ Or, you have statically linked some Boost.Python extension modules
+ into your application and you don't care if any dynamically-loaded
+ Boost.Python extension modules are able to use the types exposed
+ by your statically-linked extension modules (and vice-versa).
+
+
+
+
+
+
+
+
[3]
+ Information about how to identify the static and dynamic builds of Boost.Python
+ on Windows
+ / Unix
+ variants
+
+
[4]
+ Because of the way most *nix platforms share symbols among dynamically-loaded
+ objects, I'm not certain that extension modules built with different
+ compiler toolsets will always use different copies of the Boost.Python
+ library when loaded into the same Python instance. Not using different
+ libraries could be a good thing if the compilers have compatible
+ ABIs, because extension modules built with the two libraries would
+ be interoperable. Otherwise, it could spell disaster, since an extension
+ module and the Boost.Python library would have different ideas of
+ such things as class layout. I would appreciate someone doing the
+ experiment to find out what happens.
+
+ As described in the Boost.Build
+ Reference Manual, a file called user-config.jam in
+ your home directory is used to specify the tools and libraries available
+ to the build system. You may need to create or edit user-config.jam to
+ tell Boost.Build how to invoke Python, #include
+ its headers, and link with its libraries.
+
+
+
+
+
Note
+
+
+ If you are using a unix-variant OS and you ran Boost's configure
+ script, it may have generated a user-config.jam
+ for you. [2] If your configure/make sequence was successful and Boost.Python
+ binaries were built, your user-config.jam
+ file is probably already correct.
+
+
+
+ If you have one fairly “standard” python installation for your platform,
+ you might not need to do anything special to describe it. If you haven't
+ configured python in user-config.jam (and
+ you don't specify --without-python
+ on the Boost.Build command line), Boost.Build will automatically execute
+ the equivalent of
+
+
importtoolset:using;
+usingpython;
+
+
+ which automatically looks for Python in the most likely places. However,
+ that only happens when using the Boost.Python project file (e.g. when referred
+ to by another project as in the quickstart method). If instead you are linking
+ against separately-compiled Boost.Python binaries, you should set up a user-config.jam file
+ with at least the minimal incantation above.
+
+ If you have several versions of Python installed, or Python is installed
+ in an unusual way, you may want to supply any or all of the following optional
+ parameters to usingpython.
+
+
+
+
+
version
+
+ the version of Python to use. Should be in Major.Minor format, for
+ example, 2.3. Do not
+ include the subminor version (i.e. not
+ 2.5.1). If you have multiple Python versions
+ installed, the version will usually be the only configuration argument
+ required.
+
+
cmd-or-prefix
+
+ preferably, a command that invokes a Python interpreter. Alternatively,
+ the installation prefix for Python libraries and header files. Only
+ use the alternative formulation if there is no appropriate Python
+ executable available.
+
+
includes
+
+ the #include paths
+ for Python headers. Normally the correct path(s) will be automatically
+ deduced from version
+ and/or cmd-or-prefix.
+
+
libraries
+
+ the path to Python library binaries. On MacOS/Darwin, you can also
+ pass the path of the Python framework. Normally the correct path(s)
+ will be automatically deduced from version
+ and/or cmd-or-prefix.
+
+
condition
+
+ if specified, should be a set of Boost.Build properties that are
+ matched against the build configuration when Boost.Build selects
+ a Python configuration to use. See examples below for details.
+
+
extension-suffix
+
+ A string to append to the name of extension modules before the true
+ filename extension. You almost certainly don't need to use this.
+ Usually this suffix is only used when targeting a Windows debug build
+ of Python, and will be set automatically for you based on the value
+ of the <python-debugging>
+ feature. However, at least one Linux distribution (Ubuntu Feisty
+ Fawn) has a specially configured <python-dbg>
+ package that claims to use such a suffix.
+
+ You can set up your user-config.jam so a bjam built under Windows can
+ build/test both Windows and Cygwin_ python extensions. Just pass <target-os>cygwin
+ in the condition parameter
+ for the cygwin python installation:
+
+ when you put target-os=cygwin in your build request, it should build
+ with the cygwin version of python: _
+
+
bjamtarget-os=cygwintoolset=gcc
+
+
+ This is supposed to work the other way, too (targeting windows python
+ with a Cygwin bjam) but it
+ seems as though the support in Boost.Build's toolsets for building
+ that way is broken at the time of this writing.
+
+ 1. If you should ever have occasion to #include
+ "python.h" directly in a
+ translation unit of a program using Boost.Python, use #include
+ "boost/python/detail/wrap_python.hpp"
+ instead. It handles several issues necessary for use with Boost.Python, one
+ of which is mentioned in the next section.
+
+
+ 2. Be sure not to #include
+ any system headers before wrap_python.hpp. This
+ restriction is actually imposed by Python, or more properly, by Python's
+ interaction with your operating system. See http://docs.python.org/ext/simpleExample.html
+ for details.
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/develop/doc/html/building/installing_boost_python_on_your_.html b/develop/doc/html/building/installing_boost_python_on_your_.html
new file mode 100644
index 00000000..944943a9
--- /dev/null
+++ b/develop/doc/html/building/installing_boost_python_on_your_.html
@@ -0,0 +1,52 @@
+
+
+
+Installing Boost.Python on your System
+
+
+
+
+
+
+
+
+
+ Since Boost.Python is a separately-compiled (as opposed to header-only) library, its user relies on the services
+ of a Boost.Python library binary.
+
+
+ If you need a regular installation of the Boost.Python library binaries on
+ your system, the Boost Getting
+ Started Guide will walk you through the steps of creating one. If
+ building binaries from source, you might want to supply the --with-python
+ argument to bjam (or the
+ --with-libraries=python
+ argument to configure), so
+ only the Boost.Python binary will be built, rather than all the Boost binaries.
+
+ There is no need to “install Boost” in order to get started using Boost.Python.
+ These instructions use Boost.Build
+ projects, which will build those binaries as soon as they're needed. Your
+ first tests may take a little longer while you wait for Boost.Python to build,
+ but doing things this way will save you from worrying about build intricacies
+ like which library binaries to use for a specific compiler configuration
+ and figuring out the right compiler options to use yourself.
+
+
+
+
+
Note
+
+
+
+ Of course it's possible to use other build systems to build Boost.Python
+ and its extensions, but they are not officially supported by Boost. Moreover
+ 99% of all “I can't build Boost.Python” problems
+ come from trying to use another build system without first following
+ these instructions.
+
+
+ If you want to use another system anyway, we suggest that you follow these
+ instructions, and then invoke bjam
+ with the
+
+
+ -a
+ -ofilename
+
+
+ options to dump the build commands it executes to a file, so you can see
+ what your alternate build system needs to do.
+
+ 3. cd into the example/quickstart/ directory of your Boost.Python installation,
+ which contains a small example project.
+
+
+ 4. Invoke bjam. Replace
+ the “stage“ argument
+ from the example invocation from section 5 of the Boost Getting
+ Started Guide with “test,“
+ to build all the test targets. Also add the argument “--verbose-test” to see the output generated by
+ the tests when they are run. On Windows, your bjam
+ invocation might look something like:
+
+ For the sake of concision, the rest of this guide will use unix-style
+ forward slashes in pathnames instead of the backslashes with which Windows
+ users may be more familiar. The forward slashes should work everywhere
+ except in Command
+ Prompt windows, where you should use backslashes.
+
+
+
+ If you followed this procedure successfully, you will have built an extension
+ module called extending
+ and tested it by running a Python script called test_extending.py.
+ You will also have built and run a simple application called embedding that embeds python.
+
+ If you're seeing lots of compiler and/or linker error messages, it's probably
+ because Boost.Build is having trouble finding your Python installation.
+ You might want to pass the --debug-configuration option to bjam the first few times you invoke it,
+ to make sure that Boost.Build is correctly locating all the parts of your
+ Python installation. If it isn't, consider Configuring
+ Boost.Build as detailed below.
+
+
+ If you're still having trouble, Someone on one of the following mailing
+ lists may be able to help:
+
+ Rejoice! If you're new to Boost.Python, at this point it might be a good
+ idea to ignore build issues for a while and concentrate on learning the
+ library by going through the Tutorial
+ and perhaps some of the Reference Manual,
+ trying out what you've learned about the API by modifying the quickstart
+ project.
+
+ If you're content to keep your extension module forever in one source file
+ called extending.cpp, inside your Boost.Python distribution,
+ and import it forever as extending,
+ then you can stop here. However, it's likely that you will want to make
+ a few changes. There are a few things you can do without having to learn
+ Boost.Build in depth.
+
+
+ The project you just built is specified in two files in the current directory:
+ boost-build.jam, which tells bjam
+ where it can find the interpreted code of the Boost build system, and
+ Jamroot, which describes
+ the targets you just built. These files are heavily commented, so they
+ should be easy to modify. Take care, however, to preserve whitespace. Punctuation
+ such as ; will not be recognized
+ as intended by bjam if
+ it is not surrounded by whitespace.
+
+ You'll probably want to copy this project elsewhere so you can change
+ it without modifying your Boost distribution. To do that, simply
+
+
+ a. copy the entire example/quickstart/ directory into a new directory.
+
+
+ b. In the new copies of boost-build.jam
+ and Jamroot, locate the
+ relative path near the top of the file that is clearly marked by a comment,
+ and edit that path so that it refers to the same directory your Boost
+ distribution as it referred to when the file was in its original location
+ in the example/quickstart/
+ directory.
+
+
+ For example, if you moved the project from /home/dave/boost_1_34_0/libs/python/example/quickstart to /home/dave/my-project, you could change the first
+ path in boost-build.jam from
+
+ The names of additional source files involved in building your extension
+ module or embedding application can be listed in Jamroot
+ right alongside extending.cpp
+ or embedding.cpp respectively. Just be sure to leave
+ whitespace around each filename:
+
+
…file1.cppfile2.cppfile3.cpp…
+
+
+ Naturally, if you want to change the name of a source file you can tell
+ Boost.Build about it by editing the name in Jamroot.
+
+ If you are using a version of Python prior to 2.4.1 with a MinGW prior to
+ 3.0.0 (with binutils-2.13.90-20030111-1), you will need to create a MinGW-compatible
+ version of the Python library; the one shipped with Python will only work
+ with a Microsoft-compatible linker. Follow the instructions in the “Non-Microsoft”
+ section of the “Building Extensions: Tips And Tricks” chapter in Installing Python Modules
+ to create libpythonXX.a, where XX
+ corresponds to the major and minor version numbers of your Python installation.
+
+ Python can be built in a special “python debugging” configuration that
+ adds extra checks and instrumentation that can be very useful for developers
+ of extension modules. The data structures used by the debugging configuration
+ contain additional members, so a Python executable
+ built with python debugging enabled cannot be used with an extension module
+ or library compiled without it, and vice-versa.
+
+
+ Since pre-built “python debugging” versions of the Python executable
+ and libraries are not supplied with most distributions of Python, [5] and we didn't want to force our users to build them, Boost.Build
+ does not automatically enable python debugging in its debug
+ build variant (which is the default). Instead there is a special build property
+ called python-debugging that, when used as a build property,
+ will define the right preprocessor symbols and select the right libraries
+ to link with.
+
+
+ On unix-variant platforms, the debugging versions of Python's data structures
+ will only be used if the symbol Py_DEBUG
+ is defined. On many windows compilers, when extension modules are built with
+ the preprocessor symbol _DEBUG,
+ Python defaults to force linking with a special debugging version of the
+ Python DLL. Since that symbol is very commonly used even when Python is not
+ present, Boost.Python temporarily undefines _DEBUG
+ when Python.h is #included from boost/python/detail/wrap_python.hpp -
+ unless BOOST_DEBUG_PYTHON
+ is defined. The upshot is that if you want “python debugging”and you
+ aren't using Boost.Build, you should make sure BOOST_DEBUG_PYTHON
+ is defined, or python debugging will be suppressed.
+
+
+
+
[5]
+ On Unix and similar platforms, a debugging python and associated libraries
+ are built by adding --with-pydebug when configuring the Python build. On
+ Windows, the debugging version of Python is generated by the "Win32
+ Debug" target of the Visual Studio project in the PCBuild subdirectory
+ of a full Python source code distribution.
+
+ Boost.Python uses several configuration
+ macros in <boost/config.hpp>, as well as configuration macros meant
+ to be supplied by the application. These macros are documented here.
+
+ These are the macros that may be defined by an application using Boost.Python.
+ Note that if you extend a strict interpretation of the C++ standard to
+ cover dynamic libraries, using different values of these macros when compiling
+ different libraries (including extension modules and the Boost.Python library
+ itself) is a violation of the ODR. However,
+ we know of no C++ implementations on which this particular violation is
+ detectable or causes any problems.
+
+
+
+
+
+
+
+
+
+
+ Macro
+
+
+
+
+ Default
+
+
+
+
+ Meaning
+
+
+
+
+
+
+
+ BOOST_PYTHON_MAX_ARITY
+
+
+
+
+ 15
+
+
+
+
+ The maximum arity of any function, member function, or constructor
+ to be wrapped, invocation of a Boost.Python function wich is
+ specified as taking arguments x1, x2,...Xn. This includes, in
+ particular, callback mechanisms such as object::operator()(...)
+ or call_method<R>(... ).
+
+
+
+
+
+
+ BOOST_PYTHON_MAX_BASES
+
+
+
+
+ 10
+
+
+
+
+ The maximum number of template arguments to the bases<...>
+ class template, which is used to specify the bases of a wrapped
+ C++ class..
+
+
+
+
+
+
+ BOOST_PYTHON_STATIC_MODULE
+
+
+
+
+ not defined
+
+
+
+
+ If defined, prevents your module initialization function from
+ being treated as an exported symbol on platforms which support
+ that distinction in-code
+
+
+
+
+
+
+ BOOST_PYTHON_ENABLE_CDECL
+
+
+
+
+ not defined
+
+
+
+
+ If defined, allows functions using the __cdecl
+ calling convention to be wrapped.
+
+
+
+
+
+
+ BOOST_PYTHON_ENABLE_STDCALL
+
+
+
+
+ not defined
+
+
+
+
+ If defined, allows functions using the __stdcall
+ calling convention to be wrapped.
+
+
+
+
+
+
+ BOOST_PYTHON_ENABLE_FASTCALL
+
+
+
+
+ not defined
+
+
+
+
+ If defined, allows functions using the __fastcall
+ calling convention to be wrapped.
+
+ These macros are defined by Boost.Python
+ and are implementation details of interest only to implementors and those
+ porting to new platforms.
+
+
+
+
+
+
+
+
+
+
+ Macro
+
+
+
+
+ Default
+
+
+
+
+ Meaning
+
+
+
+
+
+
+
+ BOOST_PYTHON_TYPE_ID_NAME
+
+
+
+
+ not defined
+
+
+
+
+ If defined, this indicates that the type_info comparison across
+ shared library boundaries does not work on this platform. In
+ other words, if shared-lib-1 passes typeid(T) to a function in shared-lib-2
+ which compares it to typeid(T), that comparison may return
+ false. If this macro
+ is #defined, Boost.Python uses and compares typeid(T).name() instead of using and comparing
+ the std::type_info objects directly.
+
+
+
+
+
+
+ BOOST_PYTHON_NO_PY_SIGNATURES
+
+
+
+
+ not defined
+
+
+
+
+ If defined for a module no pythonic signatures are generated
+ for the docstrings of the module functions, and no python type
+ is associated with any of the converters registered by the module.
+ This also reduces the binary size of the module by about 14%
+ (gcc compiled). If defined for the boost_python runtime library,
+ the default for the docstring_options.enable_py_signatures() is set to false.
+
+
+
+
+
+
+ BOOST_PYTHON_SUPPORTS_PY_SIGNATURES
+
+
+
+
+ defined if BOOST_PYTHON_NO_PY_SIGNATURES
+ is undefined
+
+
+
+
+ This macro is defined to enable a smooth transition from older
+ Boost.Python versions which do not support pythonic signatures.
+ For example usage see here.
+
+ If defined the python type of __init__
+ method "self" parameters is properly generated, otherwise
+ object is used. It is undefined by default because it increases
+ the binary size of the module by about 14% (gcc compiled).
+
+ The short answer is: "you can't". This is not a Boost.Python limitation
+ so much as a limitation of C++. The problem is that a Python function is
+ actually data, and the only way of associating data with a C++ function pointer
+ is to store it in a static variable of the function. The problem with that
+ is that you can only associate one piece of data with every C++ function,
+ and we have no way of compiling a new C++ function on-the-fly for every Python
+ function you decide to pass to foo.
+ In other words, this could work if the C++ function is always going to invoke
+ the same Python function, but you probably don't want
+ that.
+
+
+ If you have the luxury of changing the C++ code you're wrapping, pass it
+ an object instead and call
+ that; the overloaded function call operator will invoke the Python function
+ you pass it behind the object.
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/develop/doc/html/faq/compilation_takes_too_much_time_.html b/develop/doc/html/faq/compilation_takes_too_much_time_.html
new file mode 100644
index 00000000..d0967099
--- /dev/null
+++ b/develop/doc/html/faq/compilation_takes_too_much_time_.html
@@ -0,0 +1,42 @@
+
+
+
+Compilation takes too much time and eats too much memory! What can I do to make it faster?
+
+
+
+
+
+
+
+
+
+ The last command requires root privileges because the target directory is
+ /Library/Frameworks/Python.framework/Versions/2.3. However,
+ the installation does not interfere with the Python version that ships with
+ 10.2.8.
+
+
+ It is also crucial to increase the stacksize
+ before starting compilations, e.g.:
+
+
limitstacksize8192k
+
+ If the stacksize is too small
+ the build might crash with internal compiler errors.
+
+
+ Sometimes Apple's compiler exhibits a bug by printing an error like the following
+ while compiling a boost::python::class_<your_type>
+ template instantiation:
+
+
.../inheritance.hpp:44:error:cannot
+ dynamic_cast`p' (of type `struct cctbx::boost_python::<unnamed>::add_pair*
+ ')totype`void*'(sourcetypeisnotpolymorphic)
+
+
+ We do not know a general workaround, but if the definition of your_type can be modified the following
+ was found to work in all cases encountered so far:
+
+
structyour_type
+{
+ // before defining any member data
+#ifdefined(__MACH__)&&defined(__APPLE_CC__)&&__APPLE_CC__==1493
+ booldummy_;
+#endif
+ // now your member data, e.g.
+ doublex;
+ intj;
+ // etc.
+};
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/develop/doc/html/faq/error_c2064_term_does_not_evalua.html b/develop/doc/html/faq/error_c2064_term_does_not_evalua.html
new file mode 100644
index 00000000..d59cc03d
--- /dev/null
+++ b/develop/doc/html/faq/error_c2064_term_does_not_evalua.html
@@ -0,0 +1,77 @@
+
+
+
+error C2064: term does not evaluate to a function taking 2 arguments
+
+
+
+
+
+
+
+
+
+ If you see Microsoft Visual C++ 7.1 (MS Visual Studio .NET 2003) issue an
+ error message like the following it is most likely due to a bug in the compiler:
+
+ If you find that a class_<...> declaration can't fit in
+ a single source file without triggering the error, you can always pass
+ a reference to the class_
+ object to a function in another source file, and call some of its member
+ functions (e.g. .def(...)) in the auxilliary source file:
+
+
+
diff --git a/develop/doc/html/faq/how_can_i_automatically_convert_.html b/develop/doc/html/faq/how_can_i_automatically_convert_.html
new file mode 100644
index 00000000..bb435b77
--- /dev/null
+++ b/develop/doc/html/faq/how_can_i_automatically_convert_.html
@@ -0,0 +1,146 @@
+
+
+
+How can I automatically convert my custom string type to and from a Python string?
+
+
+
+
+
+
+
+
+
+ A custom to_python converter
+ (easy): custom_string_to_python_str
+
+
+ A custom lvalue converter (needs more code): custom_string_from_python_str
+
+
+
+ The custom converters are registered in the global Boost.Python registry
+ near the top of the module initialization function. Once flow control has
+ passed through the registration code the automatic conversions from and to
+ Python strings will work in any module imported in the same process.
+
+ "I am wrapping a function that always returns a pointer to an already-held
+ C++ object."
+
+
+ One way to do that is to hijack the mechanisms used for wrapping a class
+ with virtual functions. If you make a wrapper class with an initial PyObject*
+ constructor argument and store that PyObject* as "self", you can
+ get back to it by casting down to that wrapper type in a thin wrapper function.
+ For example:
+
+
classX{X(int);virtual~X();...};
+X*f();// known to return Xs that are managed by Python objects
+
+
+// wrapping code
+
+structX_wrap:X
+{
+ X_wrap(PyObject*self,intv):self(self),X(v){}
+ PyObject*self;
+};
+
+handle<>f_wrap()
+{
+ X_wrap*xw=dynamic_cast<X_wrap*>(f());
+ assert(xw!=0);
+ returnhandle<>(borrowed(xw->self));
+}
+
+...
+
+def("f",f_wrap());
+class_<X,X_wrap,boost::noncopyable>("X",init<int>())
+ ...
+ ;
+
+
+ Of course, if X has no virtual functions you'll have to use static_cast instead of dynamic_cast
+ with no runtime check that it's valid. This approach also only works if the
+ X object was constructed
+ from Python, because Xs constructed
+ from C++ are of course never X_wrap
+ objects.
+
+
+ Another approach to this requires you to change your C++ code a bit; if that's
+ an option for you it might be a better way to go. work we've been meaning
+ to get to anyway. When a shared_ptr<X>
+ is converted from Python, the shared_ptr actually manages a reference to
+ the containing Python object. When a shared_ptr<X> is converted back
+ to Python, the library checks to see if it's one of those "Python object
+ managers" and if so just returns the original Python object. So you
+ could just write object(p) to get
+ the Python object back. To exploit this you'd have to be able to change the
+ C++ code you're wrapping so that it deals with shared_ptr instead of raw
+ pointers.
+
+
+ There are other approaches too. The functions that receive the Python object
+ that you eventually want to return could be wrapped with a thin wrapper that
+ records the correspondence between the object address and its containing
+ Python object, and you could have your f_wrap function look in that mapping
+ to get the Python object out.
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/develop/doc/html/faq/how_can_i_wrap_a_function_which0.html b/develop/doc/html/faq/how_can_i_wrap_a_function_which0.html
new file mode 100644
index 00000000..fccd1e4f
--- /dev/null
+++ b/develop/doc/html/faq/how_can_i_wrap_a_function_which0.html
@@ -0,0 +1,86 @@
+
+
+
+How can I wrap a function which needs to take ownership of a raw pointer?
+
+
+
+
+
+
+
+
+
+ Even binding the lifetime of a to b via with_custodian_and_ward
+ doesn't prevent the python object a from ultimately trying to delete the
+ object it's pointing to. Is there a way to accomplish a 'transfer-of-ownership'
+ of a wrapped C++ object?
+
+
+ --Bruce Lowery
+
+
+ Yes: Make sure the C++ object is held by auto_ptr:
+
+
class_<A,std::auto_ptr<A>>("A")
+ ...
+ ;
+
+
+ Then make a thin wrapper function which takes an auto_ptr parameter:
+
+ Wrap that as B.add. Note that pointers returned via manage_new_object
+ will also be held by auto_ptr,
+ so this transfer-of-ownership will also work correctly.
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/develop/doc/html/faq/how_can_i_wrap_functions_which_t.html b/develop/doc/html/faq/how_can_i_wrap_functions_which_t.html
new file mode 100644
index 00000000..30c8d102
--- /dev/null
+++ b/develop/doc/html/faq/how_can_i_wrap_functions_which_t.html
@@ -0,0 +1,120 @@
+
+
+
+How can I wrap functions which take C++ containers as arguments?
+
+
+
+
+
+
+
+
+
+ This can be moved to a template so that several types (double, int,
+ long, etc.) can be wrapped
+ with the same code. This technique is used in the file scitbx/include/scitbx/array_family/boost_python/flex_wrapper.h in the "scitbx" package.
+ The file could easily be modified for wrapping std::vector<> instantiations. This type of
+ C++/Python binding is most suitable for containers that may contain a
+ large number of elements (>10000).
+
+
+
+ Using custom rvalue converters. Boost.Python "rvalue converters"
+ match function signatures such as:
+
+
voidfoo(std::vector<double>const&array);// pass by const-reference
+voidfoo(std::vector<double>array);// pass by value
+
+ Some custom rvalue converters are implemented in the file scitbx/include/scitbx/boost_python/container_conversions.h This code can be used to convert
+ from C++ container types such as std::vector<> or std::list<> to Python tuples and vice versa.
+ A few simple examples can be found in the file scitbx/array_family/boost_python/regression_test_module.cpp
+ Automatic C++ container <-> Python tuple conversions are most suitable
+ for containers of moderate size. These converters generate significantly
+ less object code compared to alternative 1 above.
+
+
+
+ A disadvantage of using alternative 2 is that operators such as arithmetic
+ +,-,*,/,% are not available. It would be useful to have custom rvalue converters
+ that convert to a "math_array" type instead of tuples. This is
+ currently not implemented but is possible within the framework of Boost.Python
+ V2 as it will be released in the next couple of weeks. [ed.: this was posted
+ on 2002/03/10]
+
+
+ It would also be useful to also have "custom lvalue converters"
+ such as std::vector<>
+ <-> Python list. These converters would support the modification of
+ the Python list from C++. For example:
+
+ Greg Burley gives the following answer for Unix GCC users:
+
+
+
+ Once you have created a boost python extension for your c++ library or
+ class, you may need to debug the code. Afterall this is one of the reasons
+ for wrapping the library in python. An expected side-effect or benefit
+ of using BPL is that debugging should be isolated to the c++ library that
+ is under test, given that python code is minimal and boost::python either
+ works or it doesn't. (ie. While errors can occur when the wrapping method
+ is invalid, most errors are caught by the compiler ;-).
+
+
+ The basic steps required to initiate a gdb session to debug a c++ library
+ via python are shown here. Note, however that you should start the gdb
+ session in the directory that contains your BPL my_ext.so module.
+
+ Greg's approach works even better using Emacs' "gdb" command, since
+ it will show you each line of source as you step through it.
+
+
+ On Windows, my favorite debugging solution
+ is the debugger that comes with Microsoft Visual C++ 7. This debugger seems
+ to work with code generated by all versions of Microsoft and Metrowerks toolsets;
+ it's rock solid and "just works" without requiring any special
+ tricks from the user.
+
+
+ Raoul Gough has provided the following for gdb on Windows:
+
+
+
+ gdb support for Windows DLLs has improved lately, so it is now possible
+ to debug Python extensions using a few tricks. Firstly, you will need an
+ up-to-date gdb with support for minimal symbol extraction from a DLL. Any
+ gdb from version 6 onwards, or Cygwin gdb-20030214-1 and onwards should
+ do. A suitable release will have a section in the gdb.info file under Configuration
+ - Native - Cygwin Native - Non-debug DLL symbols. Refer to that info section
+ for more details of the procedures outlined here.
+
+
+ Secondly, it seems necessary to set a breakpoint in the Python interpreter,
+ rather than using ^C to break execution. A good place to set this breakpoint
+ is PyOS_Readline, which will stop execution immediately before reading
+ each interactive Python command. You have to let Python start once under
+ the debugger, so that it loads its own DLL, before you can set the breakpoint:
+
+ If you are launching your extension module tests with Boost.Build
+ using the boost-python-runtest rule, you can ask it to launch
+ your debugger for you by adding "--debugger=debugger"
+ to your bjam command-line:
+
+ It can also be extremely useful to add the -d+2
+ option when you run your test, because Boost.Build will then show you the
+ exact commands it uses to invoke it. This will invariably involve setting
+ up PYTHONPATH and other important environment variables such as LD_LIBRARY_PATH
+ which may be needed by your debugger in order to get things to work right.
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/develop/doc/html/faq/i_m_getting_the_attempt_to_retur.html b/develop/doc/html/faq/i_m_getting_the_attempt_to_retur.html
new file mode 100644
index 00000000..0d8593aa
--- /dev/null
+++ b/develop/doc/html/faq/i_m_getting_the_attempt_to_retur.html
@@ -0,0 +1,67 @@
+
+
+
+I'm getting the "attempt to return dangling reference" error. What am I doing wrong?
+
+
+
+
+
+
+
+
+
+ In this case, the Python method invoked by call_method
+ constructs a new Python object. You're trying to return a reference to a
+ C++ object (an instance of classperiod) contained within and owned by that
+ Python object. Because the called method handed back a brand new object,
+ the only reference to it is held for the duration of get_floating_frequency() above. When the function returns, the Python
+ object will be destroyed, destroying the instance of class
+ period, and leaving the returned
+ reference dangling. That's already undefined behavior, and if you try to
+ do anything with that reference you're likely to cause a crash. Boost.Python
+ detects this situation at runtime and helpfully throws an exception instead
+ of letting you do that.
+
+ The longer answer is that it can be patched to be so, but it's complex. You
+ will need to add custom lock/unlock wrapping of every time your code enters
+ Boost.Python (particularly every virtual function override) plus heavily
+ modify boost/python/detail/invoke.hpp with custom unlock/lock wrapping of
+ every time Boost.Python enters your code. You must furthermore take care
+ to not unlock/lock when Boost.Python is invoking iterator
+ changes via invoke.hpp.
+
+
+ There is a patched invoke.hpp posted
+ on the C++-SIG mailing list archives and you can find a real implementation
+ of all the machinery necessary to fully implement this in the TnFOX project
+ at this SourceForge
+ project location.
+
+ Q: /I have an object composed of 12 doubles.
+ A const&
+ to this object is returned by a member function of another class. From the
+ viewpoint of using the returned object in Python I do not care if I get a
+ copy or a reference to the returned object. In Boost.Python I have the choice
+ of using copy_const_reference
+ or return_internal_reference.
+ Are there considerations that would lead me to prefer one over the other,
+ such as size of generated code or memory overhead?/
+
+
+ A:copy_const_reference
+ will make an instance with storage for one of your objects, size=base_size+12*sizeof(double).
+ return_internal_reference
+ will make an instance with storage for a pointer to one of your objects,
+ size=
+ base_size+
+ sizeof(void*). However,
+ it will also create a weak reference object which goes in the source object's
+ weakreflist and a special callback object to manage the lifetime of the internally-referenced
+ object. My guess? copy_const_reference
+ is your friend here, resulting in less overall memory use and less fragmentation,
+ also probably fewer total cycles.
+
+ Q:I have exported my class to
+ python, with many overloaded operators. it works fine for me except the
+ *= operator. It always tells
+ me "can't multiply sequence with non int type". If I use p1.__imul__(p2)
+ instead of p1*=
+ p2, it successfully executes my
+ code. What's wrong with me?
+
+
+ A: There's nothing wrong with you. This
+ is a bug in Python 2.2. You can see the same effect in Pure Python (you can
+ learn a lot about what's happening in Boost.Python by playing with new-style
+ classes in Pure Python).
+
+ If you define custom converters similar to the ones shown above the def_readonly()
+ and def_readwrite()
+ member functions provided by boost::python::class_
+ for direct access to your member data will not work as expected. This is
+ because def_readonly("bar",&foo::bar) is equivalent to:
+
+ In order to define return value policies compatible with the custom conversions
+ replace def_readonly()
+ and def_readwrite()
+ by add_property().
+ E.g.:
+
+ The number of argumnts accepted by a function or member function. Unless
+ otherwise specified, the hidden this
+ argument to member functions is not counted when specifying arity.
+
+
ntbs
+
+ Null-Terminated Byte String, or 'C'-string. C++ string literals are
+ ntbses. An ntbs
+ must never be null.
+
+
raise
+
+ Exceptions in Python are "raised", not "thrown",
+ as they are in C++. When this documentation says that some Python exception
+ is "raised" in the context of C++ code, it means that the corresponding
+ Python exception is set via the Python/'C'
+ API, and throw_error_already_set() is called.
+
+
POD
+
+ A technical term from the C++ standard. Short for "Plain Ol'Data":
+ A POD-struct is an aggregate class that has no non-static data members
+ of type pointer to member, non-POD-struct, non-POD-union (or array of
+ such types) or reference, and has no user-defined copy assign- ment operator
+ and no user-defined destructor. Similarly, a POD-union is an aggregate
+ union that has no non-static data members of type pointer to member,
+ non-POD-struct, non-POD-union (or array of such types) or reference,
+ and has no user-defined copy assignment operator and no user-defined
+ destructor. A POD class is a class that is either a POD-struct or a POD-union.
+ An aggregate is an array or a class (clause 9) with no user-declared
+ constructors (12.1), no private or protected non-static data members
+ (clause 11), no base classes (clause 10), and no virtual functions (10.3).
+
+
ODR
+
+ The "One Definition Rule", which says that any entity in a
+ C++ program must have the same definition in all translation units (object
+ files) which make up a program.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/develop/doc/html/images/alert.png b/develop/doc/html/images/alert.png
new file mode 100644
index 00000000..b4645bc7
Binary files /dev/null and b/develop/doc/html/images/alert.png differ
diff --git a/develop/doc/html/images/blank.png b/develop/doc/html/images/blank.png
new file mode 100644
index 00000000..764bf4f0
Binary files /dev/null and b/develop/doc/html/images/blank.png differ
diff --git a/develop/doc/html/images/boost.png b/develop/doc/html/images/boost.png
new file mode 100644
index 00000000..b4d51fcd
Binary files /dev/null and b/develop/doc/html/images/boost.png differ
diff --git a/develop/doc/html/images/bpl.png b/develop/doc/html/images/bpl.png
new file mode 100644
index 00000000..c2d8c69e
Binary files /dev/null and b/develop/doc/html/images/bpl.png differ
diff --git a/develop/doc/html/images/bpl.svg b/develop/doc/html/images/bpl.svg
new file mode 100644
index 00000000..9a72d2c4
--- /dev/null
+++ b/develop/doc/html/images/bpl.svg
@@ -0,0 +1,224 @@
+
+
\ No newline at end of file
diff --git a/develop/doc/html/images/callouts/1.png b/develop/doc/html/images/callouts/1.png
new file mode 100644
index 00000000..6003ad3a
Binary files /dev/null and b/develop/doc/html/images/callouts/1.png differ
diff --git a/develop/doc/html/images/callouts/1.svg b/develop/doc/html/images/callouts/1.svg
new file mode 100644
index 00000000..e2e87dc5
--- /dev/null
+++ b/develop/doc/html/images/callouts/1.svg
@@ -0,0 +1,15 @@
+
+
+
+
+]>
+
diff --git a/develop/doc/html/images/callouts/10.png b/develop/doc/html/images/callouts/10.png
new file mode 100644
index 00000000..0426f516
Binary files /dev/null and b/develop/doc/html/images/callouts/10.png differ
diff --git a/develop/doc/html/images/callouts/10.svg b/develop/doc/html/images/callouts/10.svg
new file mode 100644
index 00000000..4740f587
--- /dev/null
+++ b/develop/doc/html/images/callouts/10.svg
@@ -0,0 +1,18 @@
+
+
+
+
+]>
+
diff --git a/develop/doc/html/images/callouts/11.png b/develop/doc/html/images/callouts/11.png
new file mode 100644
index 00000000..821afc4f
Binary files /dev/null and b/develop/doc/html/images/callouts/11.png differ
diff --git a/develop/doc/html/images/callouts/11.svg b/develop/doc/html/images/callouts/11.svg
new file mode 100644
index 00000000..09a0b2cf
--- /dev/null
+++ b/develop/doc/html/images/callouts/11.svg
@@ -0,0 +1,16 @@
+
+
+
+
+]>
+
diff --git a/develop/doc/html/images/callouts/12.png b/develop/doc/html/images/callouts/12.png
new file mode 100644
index 00000000..7cec7272
Binary files /dev/null and b/develop/doc/html/images/callouts/12.png differ
diff --git a/develop/doc/html/images/callouts/12.svg b/develop/doc/html/images/callouts/12.svg
new file mode 100644
index 00000000..9794044c
--- /dev/null
+++ b/develop/doc/html/images/callouts/12.svg
@@ -0,0 +1,18 @@
+
+
+
+
+]>
+
diff --git a/develop/doc/html/images/callouts/13.png b/develop/doc/html/images/callouts/13.png
new file mode 100644
index 00000000..5b41e02a
Binary files /dev/null and b/develop/doc/html/images/callouts/13.png differ
diff --git a/develop/doc/html/images/callouts/13.svg b/develop/doc/html/images/callouts/13.svg
new file mode 100644
index 00000000..64268bb4
--- /dev/null
+++ b/develop/doc/html/images/callouts/13.svg
@@ -0,0 +1,20 @@
+
+
+
+
+]>
+
diff --git a/develop/doc/html/images/callouts/14.png b/develop/doc/html/images/callouts/14.png
new file mode 100644
index 00000000..de5bdbd3
Binary files /dev/null and b/develop/doc/html/images/callouts/14.png differ
diff --git a/develop/doc/html/images/callouts/14.svg b/develop/doc/html/images/callouts/14.svg
new file mode 100644
index 00000000..469aa974
--- /dev/null
+++ b/develop/doc/html/images/callouts/14.svg
@@ -0,0 +1,17 @@
+
+
+
+
+]>
+
diff --git a/develop/doc/html/images/callouts/15.png b/develop/doc/html/images/callouts/15.png
new file mode 100644
index 00000000..3fd6ac38
Binary files /dev/null and b/develop/doc/html/images/callouts/15.png differ
diff --git a/develop/doc/html/images/callouts/15.svg b/develop/doc/html/images/callouts/15.svg
new file mode 100644
index 00000000..8202233e
--- /dev/null
+++ b/develop/doc/html/images/callouts/15.svg
@@ -0,0 +1,19 @@
+
+
+
+
+]>
+
diff --git a/develop/doc/html/images/callouts/16.svg b/develop/doc/html/images/callouts/16.svg
new file mode 100644
index 00000000..01d6bf81
--- /dev/null
+++ b/develop/doc/html/images/callouts/16.svg
@@ -0,0 +1,20 @@
+
+
+
+
+]>
+
diff --git a/develop/doc/html/images/callouts/17.svg b/develop/doc/html/images/callouts/17.svg
new file mode 100644
index 00000000..0a04c556
--- /dev/null
+++ b/develop/doc/html/images/callouts/17.svg
@@ -0,0 +1,17 @@
+
+
+
+
+]>
+
diff --git a/develop/doc/html/images/callouts/18.svg b/develop/doc/html/images/callouts/18.svg
new file mode 100644
index 00000000..1cb891b3
--- /dev/null
+++ b/develop/doc/html/images/callouts/18.svg
@@ -0,0 +1,21 @@
+
+
+
+
+]>
+
diff --git a/develop/doc/html/images/callouts/19.svg b/develop/doc/html/images/callouts/19.svg
new file mode 100644
index 00000000..e6fbb179
--- /dev/null
+++ b/develop/doc/html/images/callouts/19.svg
@@ -0,0 +1,20 @@
+
+
+
+
+]>
+
diff --git a/develop/doc/html/images/callouts/2.png b/develop/doc/html/images/callouts/2.png
new file mode 100644
index 00000000..f7c15788
Binary files /dev/null and b/develop/doc/html/images/callouts/2.png differ
diff --git a/develop/doc/html/images/callouts/2.svg b/develop/doc/html/images/callouts/2.svg
new file mode 100644
index 00000000..07d03395
--- /dev/null
+++ b/develop/doc/html/images/callouts/2.svg
@@ -0,0 +1,17 @@
+
+
+
+
+]>
+
diff --git a/develop/doc/html/images/callouts/20.svg b/develop/doc/html/images/callouts/20.svg
new file mode 100644
index 00000000..ccbfd403
--- /dev/null
+++ b/develop/doc/html/images/callouts/20.svg
@@ -0,0 +1,20 @@
+
+
+
+
+]>
+
diff --git a/develop/doc/html/images/callouts/21.svg b/develop/doc/html/images/callouts/21.svg
new file mode 100644
index 00000000..93ec53fd
--- /dev/null
+++ b/develop/doc/html/images/callouts/21.svg
@@ -0,0 +1,18 @@
+
+
+
+
+]>
+
diff --git a/develop/doc/html/images/callouts/22.svg b/develop/doc/html/images/callouts/22.svg
new file mode 100644
index 00000000..f48c5f3f
--- /dev/null
+++ b/develop/doc/html/images/callouts/22.svg
@@ -0,0 +1,20 @@
+
+
+
+
+]>
+
diff --git a/develop/doc/html/images/callouts/23.svg b/develop/doc/html/images/callouts/23.svg
new file mode 100644
index 00000000..66242129
--- /dev/null
+++ b/develop/doc/html/images/callouts/23.svg
@@ -0,0 +1,22 @@
+
+
+
+
+]>
+
diff --git a/develop/doc/html/images/callouts/24.svg b/develop/doc/html/images/callouts/24.svg
new file mode 100644
index 00000000..a3d55253
--- /dev/null
+++ b/develop/doc/html/images/callouts/24.svg
@@ -0,0 +1,19 @@
+
+
+
+
+]>
+
diff --git a/develop/doc/html/images/callouts/25.svg b/develop/doc/html/images/callouts/25.svg
new file mode 100644
index 00000000..56614a97
--- /dev/null
+++ b/develop/doc/html/images/callouts/25.svg
@@ -0,0 +1,21 @@
+
+
+
+
+]>
+
diff --git a/develop/doc/html/images/callouts/26.svg b/develop/doc/html/images/callouts/26.svg
new file mode 100644
index 00000000..56faeaca
--- /dev/null
+++ b/develop/doc/html/images/callouts/26.svg
@@ -0,0 +1,22 @@
+
+
+
+
+]>
+
diff --git a/develop/doc/html/images/callouts/27.svg b/develop/doc/html/images/callouts/27.svg
new file mode 100644
index 00000000..a75c8121
--- /dev/null
+++ b/develop/doc/html/images/callouts/27.svg
@@ -0,0 +1,19 @@
+
+
+
+
+]>
+
diff --git a/develop/doc/html/images/callouts/28.svg b/develop/doc/html/images/callouts/28.svg
new file mode 100644
index 00000000..7f8cf1a3
--- /dev/null
+++ b/develop/doc/html/images/callouts/28.svg
@@ -0,0 +1,23 @@
+
+
+
+
+]>
+
diff --git a/develop/doc/html/images/callouts/29.svg b/develop/doc/html/images/callouts/29.svg
new file mode 100644
index 00000000..cb63adf1
--- /dev/null
+++ b/develop/doc/html/images/callouts/29.svg
@@ -0,0 +1,22 @@
+
+
+
+
+]>
+
diff --git a/develop/doc/html/images/callouts/3.png b/develop/doc/html/images/callouts/3.png
new file mode 100644
index 00000000..3ff0a939
Binary files /dev/null and b/develop/doc/html/images/callouts/3.png differ
diff --git a/develop/doc/html/images/callouts/3.svg b/develop/doc/html/images/callouts/3.svg
new file mode 100644
index 00000000..918be806
--- /dev/null
+++ b/develop/doc/html/images/callouts/3.svg
@@ -0,0 +1,19 @@
+
+
+
+
+]>
+
diff --git a/develop/doc/html/images/callouts/30.svg b/develop/doc/html/images/callouts/30.svg
new file mode 100644
index 00000000..dc43ba1e
--- /dev/null
+++ b/develop/doc/html/images/callouts/30.svg
@@ -0,0 +1,22 @@
+
+
+
+
+]>
+
diff --git a/develop/doc/html/images/callouts/4.png b/develop/doc/html/images/callouts/4.png
new file mode 100644
index 00000000..6aa29fc0
Binary files /dev/null and b/develop/doc/html/images/callouts/4.png differ
diff --git a/develop/doc/html/images/callouts/4.svg b/develop/doc/html/images/callouts/4.svg
new file mode 100644
index 00000000..8eb6a53b
--- /dev/null
+++ b/develop/doc/html/images/callouts/4.svg
@@ -0,0 +1,16 @@
+
+
+
+
+]>
+
diff --git a/develop/doc/html/images/callouts/5.png b/develop/doc/html/images/callouts/5.png
new file mode 100644
index 00000000..36e78586
Binary files /dev/null and b/develop/doc/html/images/callouts/5.png differ
diff --git a/develop/doc/html/images/callouts/5.svg b/develop/doc/html/images/callouts/5.svg
new file mode 100644
index 00000000..ca7a9f22
--- /dev/null
+++ b/develop/doc/html/images/callouts/5.svg
@@ -0,0 +1,18 @@
+
+
+
+
+]>
+
diff --git a/develop/doc/html/images/callouts/6.png b/develop/doc/html/images/callouts/6.png
new file mode 100644
index 00000000..c943676b
Binary files /dev/null and b/develop/doc/html/images/callouts/6.png differ
diff --git a/develop/doc/html/images/callouts/6.svg b/develop/doc/html/images/callouts/6.svg
new file mode 100644
index 00000000..783a0b9d
--- /dev/null
+++ b/develop/doc/html/images/callouts/6.svg
@@ -0,0 +1,19 @@
+
+
+
+
+]>
+
diff --git a/develop/doc/html/images/callouts/7.png b/develop/doc/html/images/callouts/7.png
new file mode 100644
index 00000000..20940de3
Binary files /dev/null and b/develop/doc/html/images/callouts/7.png differ
diff --git a/develop/doc/html/images/callouts/7.svg b/develop/doc/html/images/callouts/7.svg
new file mode 100644
index 00000000..59b3714b
--- /dev/null
+++ b/develop/doc/html/images/callouts/7.svg
@@ -0,0 +1,16 @@
+
+
+
+
+]>
+
diff --git a/develop/doc/html/images/callouts/8.png b/develop/doc/html/images/callouts/8.png
new file mode 100644
index 00000000..d8e34d4a
Binary files /dev/null and b/develop/doc/html/images/callouts/8.png differ
diff --git a/develop/doc/html/images/callouts/8.svg b/develop/doc/html/images/callouts/8.svg
new file mode 100644
index 00000000..c1803a3c
--- /dev/null
+++ b/develop/doc/html/images/callouts/8.svg
@@ -0,0 +1,20 @@
+
+
+
+
+]>
+
diff --git a/develop/doc/html/images/callouts/9.png b/develop/doc/html/images/callouts/9.png
new file mode 100644
index 00000000..abe63607
Binary files /dev/null and b/develop/doc/html/images/callouts/9.png differ
diff --git a/develop/doc/html/images/callouts/9.svg b/develop/doc/html/images/callouts/9.svg
new file mode 100644
index 00000000..bc149d3c
--- /dev/null
+++ b/develop/doc/html/images/callouts/9.svg
@@ -0,0 +1,19 @@
+
+
+
+
+]>
+
diff --git a/develop/doc/html/images/caution.png b/develop/doc/html/images/caution.png
new file mode 100644
index 00000000..5b7809ca
Binary files /dev/null and b/develop/doc/html/images/caution.png differ
diff --git a/develop/doc/html/images/caution.svg b/develop/doc/html/images/caution.svg
new file mode 100644
index 00000000..4bd586a0
--- /dev/null
+++ b/develop/doc/html/images/caution.svg
@@ -0,0 +1,68 @@
+
+
diff --git a/develop/doc/html/images/draft.png b/develop/doc/html/images/draft.png
new file mode 100644
index 00000000..0084708c
Binary files /dev/null and b/develop/doc/html/images/draft.png differ
diff --git a/develop/doc/html/images/home.png b/develop/doc/html/images/home.png
new file mode 100644
index 00000000..5584aacb
Binary files /dev/null and b/develop/doc/html/images/home.png differ
diff --git a/develop/doc/html/images/home.svg b/develop/doc/html/images/home.svg
new file mode 100644
index 00000000..e803a317
--- /dev/null
+++ b/develop/doc/html/images/home.svg
@@ -0,0 +1,26 @@
+
+
+
+
+
+
+
+
+]>
+
diff --git a/develop/doc/html/images/important.png b/develop/doc/html/images/important.png
new file mode 100644
index 00000000..12c90f60
Binary files /dev/null and b/develop/doc/html/images/important.png differ
diff --git a/develop/doc/html/images/important.svg b/develop/doc/html/images/important.svg
new file mode 100644
index 00000000..dd84f3fe
--- /dev/null
+++ b/develop/doc/html/images/important.svg
@@ -0,0 +1,25 @@
+
+
+
+
+
+
+
+
+]>
+
diff --git a/develop/doc/html/images/next.png b/develop/doc/html/images/next.png
new file mode 100644
index 00000000..59800b4e
Binary files /dev/null and b/develop/doc/html/images/next.png differ
diff --git a/develop/doc/html/images/next.svg b/develop/doc/html/images/next.svg
new file mode 100644
index 00000000..75fa83ed
--- /dev/null
+++ b/develop/doc/html/images/next.svg
@@ -0,0 +1,19 @@
+
+
+
+
+
+
+]>
+
diff --git a/develop/doc/html/images/next_disabled.png b/develop/doc/html/images/next_disabled.png
new file mode 100644
index 00000000..10a8c59d
Binary files /dev/null and b/develop/doc/html/images/next_disabled.png differ
diff --git a/develop/doc/html/images/note.png b/develop/doc/html/images/note.png
new file mode 100644
index 00000000..d0c3c645
Binary files /dev/null and b/develop/doc/html/images/note.png differ
diff --git a/develop/doc/html/images/note.svg b/develop/doc/html/images/note.svg
new file mode 100644
index 00000000..648299d2
--- /dev/null
+++ b/develop/doc/html/images/note.svg
@@ -0,0 +1,33 @@
+
+
+
+
+
+
+
+
+
+
+
+
+]>
+
diff --git a/develop/doc/html/images/prev.png b/develop/doc/html/images/prev.png
new file mode 100644
index 00000000..d88a40f9
Binary files /dev/null and b/develop/doc/html/images/prev.png differ
diff --git a/develop/doc/html/images/prev.svg b/develop/doc/html/images/prev.svg
new file mode 100644
index 00000000..6d88ffdd
--- /dev/null
+++ b/develop/doc/html/images/prev.svg
@@ -0,0 +1,19 @@
+
+
+
+
+
+
+]>
+
diff --git a/develop/doc/html/images/prev_disabled.png b/develop/doc/html/images/prev_disabled.png
new file mode 100644
index 00000000..ab3c17e0
Binary files /dev/null and b/develop/doc/html/images/prev_disabled.png differ
diff --git a/develop/doc/html/images/smiley.png b/develop/doc/html/images/smiley.png
new file mode 100644
index 00000000..30a77f71
Binary files /dev/null and b/develop/doc/html/images/smiley.png differ
diff --git a/develop/doc/html/images/tip.png b/develop/doc/html/images/tip.png
new file mode 100644
index 00000000..5c4aab3b
Binary files /dev/null and b/develop/doc/html/images/tip.png differ
diff --git a/develop/doc/html/images/tip.svg b/develop/doc/html/images/tip.svg
new file mode 100644
index 00000000..cd437a5e
--- /dev/null
+++ b/develop/doc/html/images/tip.svg
@@ -0,0 +1,84 @@
+
+
diff --git a/develop/doc/html/images/toc-blank.png b/develop/doc/html/images/toc-blank.png
new file mode 100644
index 00000000..6ffad17a
Binary files /dev/null and b/develop/doc/html/images/toc-blank.png differ
diff --git a/develop/doc/html/images/toc-minus.png b/develop/doc/html/images/toc-minus.png
new file mode 100644
index 00000000..abbb020c
Binary files /dev/null and b/develop/doc/html/images/toc-minus.png differ
diff --git a/develop/doc/html/images/toc-plus.png b/develop/doc/html/images/toc-plus.png
new file mode 100644
index 00000000..941312ce
Binary files /dev/null and b/develop/doc/html/images/toc-plus.png differ
diff --git a/develop/doc/html/images/up.png b/develop/doc/html/images/up.png
new file mode 100644
index 00000000..17d9c3ec
Binary files /dev/null and b/develop/doc/html/images/up.png differ
diff --git a/develop/doc/html/images/up.svg b/develop/doc/html/images/up.svg
new file mode 100644
index 00000000..d31aa9c8
--- /dev/null
+++ b/develop/doc/html/images/up.svg
@@ -0,0 +1,19 @@
+
+
+
+
+
+
+]>
+
diff --git a/develop/doc/html/images/up_disabled.png b/develop/doc/html/images/up_disabled.png
new file mode 100644
index 00000000..e22bc871
Binary files /dev/null and b/develop/doc/html/images/up_disabled.png differ
diff --git a/develop/doc/html/images/warning.png b/develop/doc/html/images/warning.png
new file mode 100644
index 00000000..1c33db8f
Binary files /dev/null and b/develop/doc/html/images/warning.png differ
diff --git a/develop/doc/html/images/warning.svg b/develop/doc/html/images/warning.svg
new file mode 100644
index 00000000..fc8d7484
--- /dev/null
+++ b/develop/doc/html/images/warning.svg
@@ -0,0 +1,23 @@
+
+
+
+
+
+
+
+
+]>
+
diff --git a/develop/doc/html/index.html b/develop/doc/html/index.html
new file mode 100644
index 00000000..1d5eac0a
--- /dev/null
+++ b/develop/doc/html/index.html
@@ -0,0 +1,129 @@
+
+
+
+Boost.Python
+
+
+
+
+
+
+
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+ Welcome to Boost.Python, a C++ library which enables seamless interoperability
+ between C++ and the Python programming language. The library includes support
+ for:
+
+ Models of the CallPolicies concept are used to specialize the behavior
+ of Python callable objects generated by Boost.Python to wrapped C++ objects
+ like function and member function pointers, providing three behaviors:
+
+
+
+ precall - Python argument
+ tuple management before the wrapped object is invoked
+
+
+ result_converter -
+ C++ return value handling
+
+
+ postcall - Python argument
+ tuple and result management after the wrapped object is invoked
+
+
+ extract_return_type
+ - metafunction for extracting the return type from a given signature
+ type sequence
+
+ In order to allow the use of multiple models of CallPolicies in the same
+ callable object, Boost.Python's CallPolicies class templates provide a
+ chaining interface which allows them to be recursively composed. This interface
+ takes the form of an optional template parameter, Base,
+ which defaults to default_call_policies.
+ By convention, the precall
+ function of the Base is
+ invoked after the precall
+ function supplied by the outer
+ template, and the postcall
+ function of the Base is
+ invoked before the postcall
+ function of the outer template.
+ If a result_converter is
+ supplied by the outer template,
+ it replaces any result_converter
+ supplied by the Base. For
+ an example, see return_internal_reference.
+
+ returns false and
+ PyErr_Occurred()!=
+ 0 upon failure, true otherwise.
+
+
+
+
+
+
+ P::result_converter
+
+
+
+
+ A model of ResultConverterGenerator.
+
+
+
+
+ An MPL unary Metafunction Class used produce the "preliminary"
+ result object.
+
+
+
+
+
+
+ x.postcall(a,
+ r)
+
+
+
+
+ convertible to PyObject*
+
+
+
+
+ 0 and PyErr_Occurred()
+ !=0
+ upon failure. Must "conserve references" even in the
+ event of an exception. In other words, if r
+ is not returned, its reference count must be decremented; if
+ another existing object is returned, its reference count must
+ be incremented.
+
+
+
+
+
+
+ P::extract_return_type
+
+
+
+
+ A model of Metafunction.
+
+
+
+
+ An MPL unary Metafunction used extract the return type from a
+ given signature. By default it is derived from mpl::front.
+
+ An Extractor is a class which Boost.Python can use to extract C++ objects
+ from Python objects, and is typically used by facilities that define from_python conversions for "traditional"
+ Python extension types.
+
+ Informally, an Extractor's execute member must be a non-overloaded static
+ function whose single argument is a Python object type. Acceptable Python
+ object types include those publicly (and unambiguously) derived from PyObject,
+ and POD types which are layout-compatible with PyObject.
+
+ A HolderGenerator is a unary metafunction class which returns types suitable
+ for holding instances of its argument in a wrapped C++ class instance.
+
+ This page defines two concepts used to describe classes which manage a
+ Python objects, and which are intended to support usage with a Python-like
+ syntax.
+
+ Models of the ObjectWrapper concept have object
+ as a publicly-accessible base class, and are used to supply special construction
+ behavior and/or additional convenient functionality through (often templated)
+ member functions. Except when the return type R is itself an TypeWrapper,
+ a member function invocation of the form
+
+ TypeWrapper is a refinement of ObjectWrapper
+ which is associated with a particular Python type X.
+ For a given TypeWrapper T,
+ a valid constructor expression
+
+
T(a1,a2,...an)
+
+ builds a new T object managing the result of invoking X with arguments
+ corresponding to
+
+
object(a1),object(a2),...object(an)
+
+ . When used as arguments to wrapped C++ functions, or as the template parameter
+ to extract<>,
+ only instances of the associated Python type will be considered a match.
+
+ The upshot of the special member function invocation rules when the return
+ type is a TypeWrapper is that it is possible for the returned object to
+ manage a Python object of an inappropriate type. This is not usually a
+ serious problem; the worst-case result is that errors will be detected
+ at runtime a little later than they might otherwise be. For an example
+ of how this can occur, note that the dict
+ member function items returns
+ an object of type list.
+ Now suppose the user defines this dict
+ subclass in Python:
+
+ Since an instance of mydict
+ is also an instance of dict,
+ when used as an argument to a wrapped C++ function, boost::python::dict
+ can accept objects of Python type mydict.
+ Invoking items()
+ on this object can result in an instance of boost::python::list
+ which actually holds a Python tuple.
+ Subsequent attempts to use list
+ methods (e.g. append, or
+ any other mutating operation) on this object will raise the same exception
+ that would occur if you tried to do it from Python.
+
+ A ResultConverter for a type T
+ is a type whose instances can be used to convert C++ return values of type
+ Tto_python.
+ A ResultConverterGenerator is an MPL unary metafunction class which, given
+ the return type of a C++ function, returns a ResultConverter for that type.
+ ResultConverters in Boost.Python generally inspect library's registry of
+ converters to find a suitable converter, but converters which don't use
+ the registry are also possible.
+
+ In the table below, C denotes
+ a ResultConverter type for a type R,
+ c denotes an object of
+ type C, and r denotes an object of type R.
+
+
+
+
+
+
+
+
+
+
+ Expression
+
+
+
+
+ Type
+
+
+
+
+ Semantics
+
+
+
+
+
+
+
+ Cc
+
+
+
+
+
+
+ Constructs a c
+ object.
+
+
+
+
+
+
+ c.convertible()
+
+
+
+
+ convertible to bool
+
+
+
+
+ false iff no conversion
+ from any R value
+ to a Python object is possible.
+
+
+
+
+
+
+ c(r)
+
+
+
+
+ convertible to PyObject*
+
+
+
+
+ A pointer to a Python object corresponding to r,
+ or 0 iff r could not be converted to_python, in which case PyErr_Occurred should return
+ non-zero.
+
+
+
+
+
+
+ c.get_pytype()
+
+
+
+
+ PyTypeObjectconst*
+
+
+
+
+ A pointer to a Python Type object corresponding to result of
+ the conversion, or 0.
+ Used for documentation generation. If 0
+ is returned the generated type in the documentation will be object.
+
+ A keyword-expression results in an object which holds a sequence of
+ ntbses, and whose type encodes the number
+ of keywords specified. The keyword-expression may contain default values
+ for some or all of the keywords it holds
+
+ The following C++ function applies a Python callable object to its two
+ arguments and returns the result. If a Python exception is raised or the
+ result can't be converted to a double, an exception is thrown.
+
+ <boost/python/call_method.hpp> defines the call_method family of
+ overloaded function templates, used to invoke callable attributes of Python
+ objects from C++.
+
+ R is a pointer type,
+ reference type, or a complete type with an accessible copy constructor
+
+
Effects
+
+ Invokes self.method(a1,a2,...an) in Python, where a1...an
+ are the arguments to call_method(), converted to Python objects. For
+ a complete semantic description, see this page.
+
+
Returns
+
+ The result of the Python call, converted to the C++ type R.
+
+
Rationale
+
+ call_method is critical
+ to implementing C++ virtual functions which are overridable in Python,
+ as shown by the example below.
+
+ The following C++ illustrates the use of call_method
+ in wrapping a class with a virtual function that can be overridden in Python:
+ C++ Module Definition
+
+ make_getter()
+ and make_setter()
+ are the functions used internally by class_<>::def_readonly and class_<>::def_readwrite to produce Python
+ callable objects which wrap C++ data members.
+
+ Creates a Python callable object which accepts a single argument
+ that can be converted from_python to C*, and returns the corresponding
+ member D member of the C object, converted to_python. If policies
+ is supplied, it will be applied to the function as described here.
+ Otherwise, the library attempts to determine whether D is a user-defined
+ class type, and if so uses return_internal_reference<> for
+ Policies. Note that this test may inappropriately choose return_internal_reference<>
+ in some cases when D is a smart pointer type. This is a known defect.
+
+
Returns
+
+ An instance of object which holds the new Python callable object.
+
+ Creates a Python callable object which accepts no arguments and returns
+ d or *p, converted to_python on demand. If policies is supplied,
+ it will be applied to the function as described here. Otherwise,
+ the library attempts to determine whether D is a user-defined class
+ type, and if so uses reference_existing_object for Policies.
+
+
Returns
+
+ An instance of object which holds the new Python callable object.
+
+ Creates a Python callable object which, when called from Python,
+ expects two arguments which can be converted from_python to C* and
+ D const&, respectively, and sets the corresponding D member of
+ the C object. If policies is supplied, it will be applied to the
+ function as described here.
+
+
Returns
+
+ An instance of object which holds the new Python callable object.
+
+ Creates a Python callable object which accepts one argument, which
+ is converted from Python to D const& and written into d or *p,
+ respectively. If policies is supplied, it will be applied to the
+ function as described here.
+
+
Returns
+
+ An instance of object which holds the new Python callable object.
+
+ make_function() and make_constructor() are the functions used internally
+ by def() and class_<>::def() to produce Python callable objects which
+ wrap C++ functions and member functions.
+
+ F is a function pointer or member function pointer type. If policies
+ are supplied, it must be a model of CallPolicies. If kewords are
+ supplied, it must be the result of a keyword-expression specifying
+ no more arguments than the arity of f.
+
+
Effects
+
+
+ Creates a Python callable object which, when called from Python,
+ converts its arguments to C++ and calls f. If F is a pointer-to-member-function
+ type, the target object of the function call (*this) will be taken
+ from the first Python argument, and subsequent Python arguments will
+ be used as the arguments to f.
+
+
+ * If policies are supplied, it will be applied to the function as
+ described here. * If keywords are supplied, the keywords will be
+ applied in order to the final arguments of the resulting function.
+ * If Signature is supplied, it should be an instance of an MPL front-extensible
+ sequence representing the function's return type followed by its
+ argument types. Pass a Signature when wrapping function object types
+ whose signatures can't be deduced, or when you wish to override the
+ types which will be passed to the wrapped function.
+
+
+
Returns
+
+ An instance of object which holds the new Python callable object.
+
+
Caveats
+
+ An argument of pointer type may be 0 if None is passed from Python.
+ An argument type which is a constant reference may refer to a temporary
+ which was created from the Python object for just the duration of
+ the call to the wrapped function, for example a std::vector conjured
+ up by the conversion process from a Python list. Use a non-const
+ reference argument when a persistent lvalue is required.
+
+ F is a function pointer type. If policies are supplied, it must be
+ a model of CallPolicies. If kewords are supplied, it must be the
+ result of a keyword-expression specifying no more arguments than
+ the arity of f.
+
+
Effects
+
+ Creates a Python callable object which, when called from Python,
+ converts its arguments to C++ and calls f.
+
+
Returns
+
+ An instance of object which holds the new Python callable object.
+
+ Defines facilities for generating families of overloaded Python functions
+ and extension class methods from C++ functions and member functions with
+ default arguments, or from similar families of C++ overloads
+
+ An overload-dispatch-expression is used to describe a family of overloaded
+ methods to be generated for an extension class. It has the following
+ properties:
+
+
+
+
+
docstring
+
+ An ntbs whose value will bound to the
+ methods' __doc__
+ attribute
+
+
keywords
+
+ A keyword-expression
+ which will be used to name (a trailing subsequence of) the arguments
+ to the generated methods.
+
+
call policies
+
+ An instance of some type which models CallPolicies.
+
+
minimum arity
+
+ The minimum number of arguments to be accepted by a generated method
+ overload.
+
+
maximum arity
+
+ The maximum number of arguments to be accepted by a generated method
+ overload.
+
+ An OverloadDispatcher X is a class which has a minimum arity and a maximum
+ arity, and for which the following following are valid overload-dispatch-expressions,
+ with the same minimum and maximum arity as the OverloadDispatcher.
+
+ * If policies are supplied, it must be an instance of a type which models
+ CallPolicies, and will be
+ used as the result's call policies. Otherwise the result's call policies
+ will be an instance of default_call_policies. * If docstring
+ is supplied it must be an ntbs, and will be
+ used as the result's docstring. Otherwise the result has an empty docstring.
+ * If keywords is supplied it must be the result of a keyword-expression
+ whose length is no greater than X's maximum arity, and will be used as
+ the result's keywords. Otherwise the result's keywords will be empty.
+
+ Expands to the definition of an OverloadDispatcher called name in the current
+ scope which can be used to generate the following function invocation:
+
+ Expands to the definition of an OverloadDispatcher called name in the current
+ scope which can be used to generate the following function invocation:
+
+
x.member_name(a1,a2,...ai);
+
+ for all min_args <= i <= max_args, where x is a reference to an object
+ of class type.
+
+ <boost/python/ptr.hpp> defines the ptr() function template, which
+ allows users to specify how to convert C++ pointer values to python in
+ the context of implementing overridable virtual functions, invoking Python
+ callable objects, or explicitly converting C++ objects to Python. Normally,
+ when passing pointers to Python callbacks, the pointee is copied to ensure
+ that the Python object never holds a dangling reference. To specify that
+ the new Python object should merely contain a copy of a pointer p, the
+ user can pass ptr(p) instead of passing p directly. This interface is meant
+ to mirror the use of boost::ref(), which can be similarly used to prevent
+ copying of referents.
+
+
+ ptr(p) returns an instance of pointer_wrapper<>,
+ which can be detected using the is_pointer_wrapper<>
+ metafunction; unwrap_pointer<>
+ is a metafunction which extracts the original pointer type from a pointer_wrapper<>.
+ These classes can be thought of as implementation details.
+
+ pointer_wrapper is intended to be a stand-in for the actual pointer
+ type, but sometimes it's better to have an explicit way to retrieve
+ the pointer.
+
+ This example illustrates the use of ptr() to prevent an object from being
+ copied:
+
+
#include<boost/python/call.hpp>
+#include<boost/python/ptr.hpp>
+
+classexpensive_to_copy
+{
+ ...
+};
+
+voidpass_as_arg(expensive_to_copy*x,PyObject*f)
+{
+ // call the Python function f, passing a Python object built around
+ // which refers to *x by-pointer.
+ //
+ // *** Note: ensuring that *x outlives the argument to f() is ***
+ // *** up to the user! Failure to do so could result in a crash! ***
+
+ boost::python::call<void>(f,ptr(x));
+}
+...
+
+ raw_function(...)
+ is used to convert a function taking a tuple and a dict into a Python callable object
+ which accepts a variable number of arguments and arbitrary keyword arguments.
+
+ a callable object which requires at least min_args arguments. When
+ called, the actual non-keyword arguments will be passed in a tuple
+ as the first argument to f, and the keyword arguments will be passed
+ in a dict as the second argument to f.
+
+ Boost.Python supports docstrings with automatic appending of Pythonic
+ and C++ signatures. This feature is implemented by class function_doc_signature_generator. The
+ class uses all of the overloads, supplied arg names and default values,
+ as well as the user-defined docstrings, to generate documentation for
+ a given function.
+
+ To support Pythonic signatures the converters should supply a get_pytype function returning a pointer
+ to the associated PyTypeObject.
+ See for example ResultConverter or to_python_converter. The classes
+ in this header file are meant to be used when implmenting get_pytype. There are also _direct versions of the templates of
+ classT
+ which should be used with undecorated type parameter, expected to be
+ in the conversion registry when the module loads.
+
+ This template should be used with template parameters which are (possibly
+ decorated) types exported to python using class_. The generated a static
+ get_pytype member returns
+ the corresponding python type.
+
+ This template generates a static get_pytype
+ member which inspects the registered from_python
+ converters for the type T
+ and returns a matching python type.
+
+ This example presumes that someone has implemented the standard noddy
+ example module from the Python documentation, and placed the corresponding
+ declarations in "noddy.h". Because noddy_NoddyObject
+ is the ultimate trivial extension type, the example is a bit contrived:
+ it wraps a function for which all information is contained in the type
+ of its return value.
+
+
+ C++ module definition:
+
+
#include<boost/python/reference.hpp>
+#include<boost/python/module.hpp>
+#include"noddy.h"
+
+structtag{};
+tagmake_tag(){returntag();}
+
+usingnamespaceboost::python;
+
+structtag_to_noddy
+#ifdefinedBOOST_PYTHON_SUPPORTS_PY_SIGNATURES//unnecessary overhead if py signatures are not supported
+:wrap_pytype<&noddy_NoddyType>//inherits get_pytype from wrap_pytype
+#endif
+{
+ staticPyObject*convert(tagconst&x)
+ {
+ returnPyObject_New(noddy_NoddyObject,&noddy_NoddyType);
+ }
+};
+
+BOOST_PYTHON_MODULE(to_python_converter)
+{
+ def("make_tag",make_tag);
+ to_python_converter<tag,tag_to_noddy
+#ifdefinedBOOST_PYTHON_SUPPORTS_PY_SIGNATURES//invalid if py signatures are not supported
+ ,true
+#endif
+ >();//"true" because tag_to_noddy has member get_pytype
+}
+
+
+ The following example registers to and from python converters using the
+ templates expected_from_python_type and to_pyhton_target_type.
+
+
#include<boost/python/module.hpp>
+#include<boost/python/def.hpp>
+#include<boost/python/extract.hpp>
+#include<boost/python/to_python_converter.hpp>
+#include<boost/python/class.hpp>
+
+usingnamespaceboost::python;
+
+structA
+{
+};
+
+structB
+{
+ Aa;
+ B(constA&a_):a(a_){}
+};
+
+// Converter from A to python int
+structBToPython
+#ifdefinedBOOST_PYTHON_SUPPORTS_PY_SIGNATURES//unnecessary overhead if py signatures are not supported
+ :converter::to_python_target_type<A>//inherits get_pytype
+#endif
+{
+ staticPyObject*convert(constB&b)
+ {
+ returnincref(object(b.a).ptr());
+ }
+};
+
+// Conversion from python int to A
+structBFromPython
+{
+ BFromPython()
+ {
+ boost::python::converter::registry::push_back
+ (&convertible
+ ,&construct
+ ,type_id<B>()
+#ifdefinedBOOST_PYTHON_SUPPORTS_PY_SIGNATURES//invalid if py signatures are not supported
+ ,&converter::expected_from_python_type<A>::get_pytype//convertible to A can be converted to B
+#endif
+ );
+ }
+
+ staticvoid*convertible(PyObject*obj_ptr)
+ {
+ extract<constA&>ex(obj_ptr);
+ if(!ex.check())return0;
+ returnobj_ptr;
+ }
+
+ staticvoidconstruct(
+ PyObject*obj_ptr,
+ converter::rvalue_from_python_stage1_data*data)
+ {
+ void*storage=(
+ (converter::rvalue_from_python_storage<B>*)data)->storage.bytes;
+
+ extract<constA&>ex(obj_ptr);
+ new(storage)B(ex());
+ data->convertible=storage;
+ }
+};
+
+
+Bfunc(constB&b){returnb;}
+
+BOOST_PYTHON_MODULE(pytype_function_ext)
+{
+ to_python_converter<B,BToPython
+#ifdefinedBOOST_PYTHON_SUPPORTS_PY_SIGNATURES//invalid if py signatures are not supported
+ ,true
+#endif
+ >();//has get_pytype
+ BFromPython();
+
+ class_<A>("A");
+
+ def("func",&func);
+
+}
+
+
+
+>>>frompytype_function_extimport*
+>>>printfunc.__doc__
+func((A)arg1)->A:
+ C++signature:
+ structBfunc(structB)
+
+ default_call_policies
+ is a model of CallPolicies
+ with no precall or postcall behavior and a result_converter which handles by-value
+ returns. Wrapped C++ functions and member functions use
+ default_call_policies unless
+ otherwise specified. You may find it convenient to derive new models
+ of CallPolicies
+ from default_call_policies.
+
+ default_result_converter is a model of ResultConverterGenerator which
+ can be used to wrap C++ functions returning non-pointer types, charconst*, and PyObject*, by-value.
+
+ This example comes from the Boost.Python implementation itself. Because
+ the return_value_policy class template does not implement precall or
+ postcall behavior, its default base class is default_call_policies:
+
+ return_arg and return_self instantiations are models
+ of CallPolicies
+ which return the specified argument parameter (usually *this)
+ of a wrapped (member) function.
+
+ Used for policy composition. Any result_converter
+ it supplies will be overridden by return_arg,
+ but its precall
+ and postcall
+ policies are composed as described here CallPolicies.
+
+ return_internal_reference
+ instantiations are models of CallPolicies which allow pointers
+ and references to objects held internally by a free or member function
+ argument or from the target of a member function to be returned safely
+ without making a copy of the referent. The default for its first template
+ argument handles the common case where the containing object is the target
+ (*this)
+ of a wrapped member function.
+
+ A positive compile-time constant of type std::size_t.
+
+
+
+
+ The index of the parameter which contains the object to which
+ the reference or pointer is being returned. If used to wrap
+ a member function, parameter 1 is the target object (*this).
+ Note that if the target Python object type doesn't support
+ weak references, a Python TypeError exception will be raised
+ when the function being wrapped is called.
+
+ Used for policy composition. Any result_converter
+ it supplies will be overridden by return_internal_reference,
+ but its precall
+ and postcall
+ policies are composed as described here CallPolicies.
+
+ This header provides facilities for establishing a lifetime dependency
+ between two of a function's Python argument or result objects. The ward
+ object will not be destroyed until after the custodian as long as the
+ custodian object supports weak
+ references (Boost.Python extension classes all support weak references).
+ If the custodian object does not support weak references and is not
+ None, an appropriate
+ exception will be thrown. The two class templates with_custodian_and_ward
+ and with_custodian_and_ward_postcall
+ differ in the point at which they take effect.
+
+
+ In order to reduce the chance of inadvertently creating dangling pointers,
+ the default is to do lifetime binding before the underlying C++ object
+ is invoked. However, before invocation the result object is not available,
+ so with_custodian_and_ward_postcall
+ is provided to bind lifetimes after invocation. Also, if a C++ exception
+ is thrown after with_custodian_and_ward<>::precall
+ but before the underlying C++ object actually stores a pointer, the lifetime
+ of the custodian and ward objects will be artificially bound together,
+ so one might choose with_custodian_and_ward_postcall
+ instead, depending on the semantics of the function being wrapped.
+
+
+ Please note that this is not the appropriate tool to use when wrapping
+ functions which transfer ownership of a raw pointer across the function-call
+ boundary. Please see the FAQ if you want to do that.
+
+ A positive compile-time constant of type
+ std::size_t.
+
+
+
+
+ The 1-based index of the parameter which is the dependency
+ in the lifetime relationship to be established. If used to
+ wrap a member function, parameter 1 is the target object (*this).
+ Note that if the target Python object type doesn't support
+ weak references, a Python TypeError exception will be raised
+ when the C++ object being wrapped is called.
+
+
+
+
+
+
+
+
+ ward
+
+
+
+
+ A positive compile-time constant of type std::size_t.
+
+
+
+
+ The 1-based index of the parameter which is the dependent in
+ the lifetime relationship to be established. If used to wrap
+ a member function, parameter 1 is the target object (*this).
+
+ A positive compile-time constant of type std::size_t.
+
+
+
+
+ The index of the parameter which is the dependency in the lifetime
+ relationship to be established. Zero indicates the result object;
+ 1 indicates the first argument. If used to wrap a member function,
+ parameter 1 is the target object (*this). Note that if the target
+ Python object type doesn't support weak references, a Python
+ TypeError exception will be raised when the C++ object being
+ wrapped is called.
+
+
+
+
+
+
+
+
+ ward
+
+
+
+
+ A positive compile-time constant of type std::size_t.
+
+
+
+
+ The index of the parameter which is the dependent in the lifetime
+ relationship to be established. Zero indicates the result object;
+ 1 indicates the first argument. If used to wrap a member function,
+ parameter 1 is the target object (*this).
+
+ Class template to_python_indirect
+ converts objects of its first argument type to python as extension
+ class instances, using the ownership policy provided by its 2nd argument.
+
+
+
+
+
+
+
+
+
+
+ Parameter
+
+
+
+
+ Requirements
+
+
+
+
+ Description
+
+
+
+
+
+
+
+ T
+
+
+
+
+ Either Ucv&
+ (where cv is any optional cv-qualification) or a Dereferenceable
+ type such that *x is convertible to Uconst&, where U is a class type.
+
+
+
+
+ A type deferencing
+ a C++ class exposed to Python using class template class_.
+
+
+
+
+
+
+ MakeHolder
+
+
+
+
+ h=
+ MakeHolder::execute(p);
+
+
+
+
+ A class whose static execute() creates an instance_holder.
+
+
+
+
+
+
+ Instantiations of to_python_indirect are models of ResultConverter.
+
+ x refers to an
+ object (if it is a pointer type, it is non-null). convertible()
+ ==true.
+
+
Effects
+
+ Creates an appropriately-typed Boost.Python extension class instance,
+ uses MakeHolder to create an instance_holder from x, installs
+ the instance_holder in the new extension class instance, and
+ returns a pointer to it.
+
+ copy_const_reference
+ is a model of ResultConverterGenerator
+ which can be used to wrap C++ functions returning a reference-to-const
+ type such that the referenced value is copied into a new Python object.
+
+ copy_non_const_reference
+ is a model of ResultConverterGenerator
+ which can be used to wrap C++ functions returning a reference-to-non-const
+ type such that the referenced value is copied into a new Python object.
+
+ manage_new_object is
+ a model of ResultConverterGenerator
+ which can be used to wrap C++ functions which return a pointer to an
+ object allocated with a new-expression, and expect the caller to take
+ responsibility for deleting that object.
+
+ reference_existing_object
+ is a model of ResultConverterGenerator
+ which can be used to wrap C++ functions which return a reference or pointer
+ to a C++ object. When the wrapped function is called, the value referenced
+ by its return value is not copied. A new Python object is created which
+ contains a pointer to the referent, and no attempt is made to ensure
+ that the lifetime of the referent is at least as long as that of the
+ corresponding Python object. Thus, it can be highly
+ dangerous to use reference_existing_object
+ without additional lifetime management from such models of CallPolicies
+ as with_custodian_and_ward. This
+ class is used in the implementation of return_internal_reference.
+
+ typedefto_python_indirect<T,V>type;, where V is a class whose static
+ execute function constructs an instance holder containing an unowned
+ U*
+ pointing to the referent of the wrapped function's return value.
+
+ return_by_value is a
+ model of ResultConverterGenerator
+ which can be used to wrap C++ functions returning any reference or value
+ type such that the return value is copied into a new Python object.
+
+ return_opaque_pointer is a model of ResultConverterGenerator
+ which can be used to wrap C++ functions returning pointers to undefined
+ types such that the return value is copied into a new Python object.
+
+
+ In addition to specifying the return_opaque_pointer
+ policy the BOOST_PYTHON_OPAQUE_SPECIALIZED_TYPE_ID
+ macro must be used to define specializations for the type_id function on the type
+ pointed to by returned pointer.
+
+ The number of argumnts accepted by a function or member function. Unless
+ otherwise specified, the hidden this
+ argument to member functions is not counted when specifying arity.
+
+
ntbs
+
+ Null-Terminated Byte String, or 'C'-string. C++ string literals are
+ ntbses. An ntbs
+ must never be null.
+
+
raise
+
+ Exceptions in Python are "raised", not "thrown",
+ as they are in C++. When this documentation says that some Python exception
+ is "raised" in the context of C++ code, it means that the corresponding
+ Python exception is set via the Python/'C'
+ API, and throw_error_already_set() is called.
+
+
POD
+
+ A technical term from the C++ standard. Short for "Plain Ol'Data":
+ A POD-struct is an aggregate class that has no non-static data members
+ of type pointer to member, non-POD-struct, non-POD-union (or array of
+ such types) or reference, and has no user-defined copy assign- ment operator
+ and no user-defined destructor. Similarly, a POD-union is an aggregate
+ union that has no non-static data members of type pointer to member,
+ non-POD-struct, non-POD-union (or array of such types) or reference,
+ and has no user-defined copy assignment operator and no user-defined
+ destructor. A POD class is a class that is either a POD-struct or a POD-union.
+ An aggregate is an array or a class (clause 9) with no user-declared
+ constructors (12.1), no private or protected non-static data members
+ (clause 11), no base classes (clause 10), and no virtual functions (10.3).
+
+
ODR
+
+ The "One Definition Rule", which says that any entity in a
+ C++ program must have the same definition in all translation units (object
+ files) which make up a program.
+
+ <boost/python/class.hpp>
+ defines the interface through which users expose their C++ classes to Python.
+ It declares the class_
+ class template, which is parameterized on the class type being exposed.
+ It also exposes the init,
+ optional and bases utility class templates, which
+ are used in conjunction with class_.
+
+
+ <boost/python/class_fwd.hpp> contains a forward declaration of the
+ class_ class template.
+
+ Creates a Python class associated with the C++ type passed as its first
+ parameter. Although it has four template parameters, only the first one
+ is required. The three optional arguments can actually be supplied in any order; Boost.Python determines the role of
+ the argument from its type.
+
+
+
+
+
+
+
+
+
+
+
+ Template Parameter
+
+
+
+
+ Requirements
+
+
+
+
+ Semantics
+
+
+
+
+ Default
+
+
+
+
+
+
+
+ T
+
+
+
+
+ A class type.
+
+
+
+
+ The class being wrapped
+
+
+
+
+
+
+
+
+ Bases
+
+
+
+
+ A specialization of bases<...>
+ which specifies previously-exposed C++ base classes of T.
+
+
+
+
+ Registers from_python
+ conversions from wrapped T
+ instances to each of its exposed direct and indirect bases. For
+ each polymorphic base B,
+ registers conversions from indirectly-held wrapped B instances to T.
+
+ Must be T, a
+ class derived from T,
+ or a Dereferenceable
+ type for which pointee<HeldType>::type
+ is T or a class
+ derived from T.
+
+
+
+
+ Specifies the type that is actually embedded in a Python object
+ wrapping a T
+ instance when T's
+ constructor is called or when a T
+ or T*
+ is converted to Python without the use of ptr,
+ ref, or Call Policies such as
+ return_internal_reference.
+ More details below.
+
+
+
+
+ T
+
+
+
+
+
+
+ NonCopyable
+
+
+
+
+ If supplied, must be boost::noncopyable.
+
+
+
+
+ Suppresses automatic registration of to_python
+ conversions which copy T
+ instances. Required when T
+ has no publicly-accessible copy constructor.
+
+
+
+
+ An unspecified type other than boost::noncopyable.
+
+ If HeldType is derived from T,
+ its exposed constructor(s) must accept an initial PyObject* argument which refers back to the
+ Python object that contains the HeldType instance, as shown in this
+ example. This argument is not included in the init-expression
+ passed to def(init_expr),
+ below, nor is it passed explicitly by users when Python instances
+ of T are created.
+ This idiom allows C++ virtual functions which will be overridden
+ in Python to access the Python object so the Python method can be
+ invoked. Boost.Python automatically registers additional converters
+ which allow wrapped instances of T
+ to be passed to wrapped C++ functions expecting HeldType arguments.
+
+
+ Because Boost.Python will always allow wrapped instances of T to be passed in place of HeldType
+ arguments, specifying a smart pointer for HeldType allows users to
+ pass Python T instances
+ where a smart pointer-to-T is expected. Smart pointers such as std::auto_ptr<>
+ or boost::shared_ptr<>
+ which contain a nested type element_type
+ designating the referent type are automatically supported; additional
+ smart pointer types can be supported by specializing pointee<HeldType>.
+
+
+ As in case 1 above, when HeldType is a smart pointer to a class derived
+ from T, the initial
+ PyObject*
+ argument must be supplied by all of HeldType's exposed constructors.
+
+
+ Except in cases 1 and 3, users may optionally specify that T itself
+ gets initialized with a similar initial PyObject* argument by specializing has_back_reference<T>.
+
+ name is an ntbs which conforms to Python's
+ identifier
+ naming rules. If docstring is supplied, it must be an
+ ntbs. If init_spec
+ is supplied, it must be either the special enumeration constant
+ no_init or an
+ init-expression
+ compatible with T.
+
+
Effects
+
+
+ Constructs a class_
+ object holding a Boost.Python extension class named name. The named
+ attribute of the current
+ scope is bound to the new extension class.
+
+
+ * If supplied, the value of docstring is bound to the __doc__ attribute of the extension
+ class. * If init_spec
+ is no_init, a special
+ __init__ function
+ is generated which always raises a Python exception. Otherwise,
+ this->def(init_spec)
+ is called. * If init_spec
+ is not supplied, this->def(init<>()) is called.
+
+
+
Rationale
+
+ Allowing the user to specify constructor arguments in the class_<>
+ constructor helps her to avoid the common run-time errors which
+ result from invoking wrapped member functions without having exposed
+ an __init__ function
+ which creates the requisite T
+ instance. Types which are not default-constructible will cause
+ a compile-time error unless Init
+ is supplied. The user must always supply name as there is currently
+ no portable method to derive the text of the class name from its
+ type.
+
+ init_expr is the
+ result of an init-expression
+ compatible with T.
+
+
Effects
+
+ For each valid
+ prefixP
+ of Init, adds an
+ __init__(...)
+ function overload to the extension class accepting P as arguments.
+ Each overload generated constructs an object of HeldType according
+ to the semantics described above, using a copy of init_expr's call
+ policies. If the longest valid
+ prefix of Init contains N types and init_expr holds M keywords,
+ an initial sequence of the keywords are used for all but the first
+ N - M arguments of each overload.
+
+
Returns
+
+ *this
+
+
Rationale
+
+ Allows users to easily expose a class' constructor to Python.
+
+ Effects: For each prefix P of Fn's
+ sequence of argument types, beginning with the one whose length
+ is A1's minimum
+ arity, adds a name(...) method overload to the extension
+ class. Each overload generated invokes a1's call-expression with
+ P, using a copy
+ of a1's call policies. If the longest valid prefix of A1 contains N
+ types and a1 holds M
+ keywords, an initial sequence of the keywords are used for all
+ but the first N-M
+ arguments of each overload.
+
+
+ * Otherwise, a single method overload is built around fn, which
+ must not be null:
+
+
+ * If fn is a function pointer, its first argument must be of the
+ form U, U cv&, U cv*, or U cv* const&, where T* is convertible
+ to U*, and a1-a3, if supplied, may be selected in any order from
+ the table below. * Otherwise, if fn is a member function pointer,
+ its target must be T or one of its public base classes, and a1-a3,
+ if supplied, may be selected in any order from the table below.
+ * Otherwise, Fn must be [derived from] object,
+ and a1-a2, if supplied, may be selcted in any order from the first
+ two rows of the table below. To be useful, fn should be callable.
+
+ Value will be bound to the __doc__ attribute of the resulting
+ method overload. If an earlier overload supplied a docstring,
+ two newline characters and the new docstring are appended
+ to it.
+
+ A copy will be used as the call policies of the resulting
+ method overload.
+
+
+
+
+
+
+ keywords
+
+
+
+
+ The result of a keyword-expression
+ specifying no more arguments than the arity
+ of fn.
+
+
+
+
+ A copy will be used as the call policies of the resulting
+ method overload.
+
+
+
+
+
+
+
Returns
+
+ *this
+
+
+
+
class_&staticmethod(charconst*name);
+
+
+
+
Requires
+
+ name is an ntbs which conforms to Python's
+ identifier
+ naming rules, and corresponds to a method whose overloads
+ have all been defined.
+
+
Effects
+
+ Replaces the existing named attribute x
+ with the result of invoking staticmethod(x) in Python. Specifies that the
+ corresponding method is static and therefore no object instance
+ will be passed to it. This is equivalent to the Python statement:
+
+ Creates a new Python property
+ class instance, passing object(fget) (and object(fset) in the second form) with an (optional)
+ docstring doc to
+ its constructor, then adds that property to the Python class object
+ under construction with the given attribute name.
+
+
Returns
+
+ *this
+
+
Rationale
+
+ Allows users to easily expose functions that can be invoked from
+ Python with attribute access syntax.
+
+ Creates a Boost.Python.StaticProperty object, passing object(fget)
+ (and object(fset)
+ in the second form) to its constructor, then adds that property
+ to the Python class under construction with the given attribute
+ name. StaticProperty is a special subclass of Python's property
+ class which can be called without an initial self argument.
+
+
Returns
+
+ *this
+
+
Rationale
+
+ Allows users to easily expose functions that can be invoked from
+ Python with static attribute access syntax.
+
+ PickleSuite must be publically derived from pickle_suite.
+
+
Effects
+
+ Defines a legal combination of the special attributes and methods:
+ __getinitargs__, __getstate__, __setstate__, __getstate_manages_dict__,
+ __safe_for_unpickling__, __reduce__
+
+ * If Fn is [derived
+ from] object,
+ it will be added to the current
+ scope as a single overload. To be useful, fn
+ should be callable.
+ * If a1 is the result
+ of an overload-dispatch-expression,
+ only the second form is allowed and fn
+ must be a pointer to function or pointer to member function whose
+ arity is the same as A1's maximum
+ arity.
+
+
+ Effects: For each prefix P of Fn's
+ sequence of argument types, beginning with the one whose length is
+ A1's minimum
+ arity, adds a name(...) function overload to the current
+ scope. Each overload generated invokes a1's call-expression
+ with P, using a copy of a1's call policies. If the longest valid
+ prefix of A1 contains N types and a1 holds M keywords, an initial
+ sequence of the keywords are used for all but the first N - M arguments
+ of each overload.
+
+
+ * Otherwise, fn must be a non-null function or member function pointer,
+ and a single function overload built around fn is added to the current
+ scope. If any of a1-a3 are supplied, they may be selected in any
+ order from the table below.
+
+ <boost/python/def_visitor.hpp> provides a generic visitation interface
+ through which the class_
+ def member functionality can be extended non-intrusively to avoid cluttering
+ the class_
+ interface. It declares the def_visitor<T> class template, which is parameterized
+ on the derived type DerivedVisitor,
+ which provides the actual def
+ functionality through its visit
+ member functions.
+
+ The class def_visitor is
+ a base class paramaterized by its derived class. The def_visitor
+ class is a protocol class. Its derived class, DerivedVisitor, is expected
+ to have a member function visit.
+ The def_visitor class is
+ never instantiated directly. Instead, an instance of its subclass, DerivedVisitor,
+ is passed on as an argument to the class_
+ def member function.
+
+ The client supplied class DerivedVisitor template parameter is expected
+ to: * be privately derived from def_visitor * grant friend access
+ to class def_visitor_access * define either or both visit member
+ functions listed in the table below:
+
+
+
+
+
+
+
+
+
+
+
+ Expression
+
+
+
+
+ Return Type
+
+
+
+
+ Requirements
+
+
+
+
+ Effects
+
+
+
+
+
+
+
+ visitor.visit(cls)
+
+
+
+
+ void
+
+
+
+
+ cls is
+ an instance of a class_
+ being wrapped to Python. visitor
+ is a def_visitor
+ derived class.
+
+
+
+
+ A call to cls.def(visitor) forwards to this member
+ function.
+
+
+
+
+
+
+ visitor.visit(cls,name,options)
+
+
+
+
+ void
+
+
+
+
+ cls is
+ a class_
+ instance, name is a C string. visitor
+ is a def_visitor
+ derived class. options is a context specific optional argument.
+
+
+
+
+ A call to cls.def(name,visitor) or cls.def(name,visitor,options) forwards to this member
+ function.
+
+ Boost.Python supports user-defined docstrings with automatic appending
+ of C++ signatures. These features are enabled by default. The class docstring_options
+ is available to selectively suppress the user-defined docstrings, signatures,
+ or both.
+
+ Controls the appearance of docstrings of wrapped functions and member functions
+ for the life-time of the instance. The instances are noncopyable to eliminate
+ the possibility of surprising side effects.
+
+ Constructs a docstring_options object which controls the appearance
+ of function and member-function docstrings defined in the code that
+ follows. If show_all is true, both the user-defined docstrings and
+ the automatically generated Python and C++ signatures are shown.
+ If show_all is false the __doc__
+ attributes are None.
+
+ Constructs a docstring_options
+ object which controls the appearance of function and member-function
+ docstrings defined in the code that follows. Iff show_user_defined
+ is true, the user-defined
+ docstrings are shown. Iff show_signatures
+ is true, Python and
+ C++ signatures are automatically added. If both show_user_defined
+ and show_signatures
+ are false, the __doc__ attributes are None.
+
+ Constructs a docstring_options
+ object which controls the appearance of function and member-function
+ docstrings defined in the code that follows. Iff show_user_defined
+ is true, the user-defined
+ docstrings are shown. Iff show_py_signatures
+ is true, Python signatures
+ are automatically added. Iff show_cpp_signatures
+ is true, C++ signatures are automatically added. If all parameters
+ are false, the __doc__ attributes are None.
+
+ Restores the previous state of the docstring options. In particular,
+ if docstring_options
+ instances are in nested C++ scopes the settings effective in the
+ enclosing scope are restored. If the last docstring_options
+ instance goes out of scope the default "all on" settings
+ are restored.
+
+ These member functions dynamically change the appearance of docstrings
+ in the code that follows. The *_user_defined()
+ and *_signatures() member functions are provided for fine-grained
+ control. The *_all() member functions are convenient shortcuts
+ to manipulate all settings simultaneously.
+
+ <boost/python/enum.hpp> defines the interface through which users
+ expose their C++ enumeration types to Python. It declares the enum_ class template, which is parameterized
+ on the enumeration type being exposed.
+
+ Constructs an enum_
+ object holding a Python extension type derived from int which is named name.
+ The named attribute of the current
+ scope is bound to the new extension type.
+
+ <boost/python/errors.hpp> provides types and functions for managing
+ and translating between Python and C++ exceptions. This is relatively low-level
+ functionality that is mostly used internally by Boost.Python. Users should
+ seldom need it.
+
+ error_already_set is an exception type which can be thrown to indicate
+ that a Python error has occurred. If thrown, the precondition is that
+ PyErr_Occurred()
+ returns a value convertible to true.
+ Portable code shouldn't throw this exception type directly, but should
+ instead use throw_error_already_set(),
+ below.
+
+ The first form requires that the expression function0<void>(f)
+ is valid. The second form requires that a C++ exception is currently
+ being handled (see section 15.1 in the C++ standard).
+
+
Effects
+
+ The first form calls f() inside a try block which first attempts
+ to use all registered exception
+ translators. If none of those translates the exception, the
+ catch clauses then set an appropriate Python exception for the C++
+ exception caught, returning true if an exception was thrown, false
+ otherwise. The second form passes a function which rethrows the exception
+ currently being handled to the first form.
+
+
Postconditions
+
+ No exception is being handled
+
+
Throws
+
+ nothing
+
+
Rationale
+
+ At inter-language boundaries it is important to ensure that no C++
+ exceptions escape, since the calling language usually doesn't have
+ the equipment necessary to properly unwind the stack. Use handle_exception
+ to manage exception translation whenever your C++ code is called
+ directly from the Python API. This is done for you automatically
+ by the usual function wrapping facilities: make_function(),
+ make_constructor(),
+ def()
+ and class_::def().
+ The second form can be more convenient to use (see the example below),
+ but various compilers have problems when exceptions are rethrown
+ from within an enclosing try block.
+
+
+
+
template<classT>T*expect_non_null(T*x);
+
+
+
+
Returns
+
+ x
+
+
Throws
+
+ error_already_set() iff x == 0.
+
+
Rationale
+
+ Simplifies error-handling when calling functions in the Python/C
+ API which return 0 on error.
+
+
+
+
voidthrow_error_already_set();
+
+
+
+
Effects
+
+ throw error_already_set();
+
+
Rationale
+
+ Simplifies error-handling when calling functions in the Python/C
+ API which return 0 on error.
+
+
+
+
voidthrow_error_already_set();
+
+
+
+
Effects
+
+ throw error_already_set();
+
+
Rationale
+
+ Many platforms and compilers are not able to consistently catch exceptions
+ thrown across shared library boundaries. Using this function from
+ the Boost.Python library ensures that the appropriate catch block
+ in handle_exception() can catch the exception.
+
#include<string>
+#include<boost/python/errors.hpp>
+#include<boost/python/object.hpp>
+#include<boost/python/handle.hpp>
+
+// Returns a std::string which has the same value as obj's "__name__"
+// attribute.
+std::stringget_name(boost::python::objectobj)
+{
+ // throws if there's no __name__ attribute
+ PyObject*p=boost::python::expect_non_null(
+ PyObject_GetAttrString(obj.ptr(),"__name__"));
+
+ charconst*s=PyString_AsString(p);
+ if(s!=0)
+ Py_DECREF(p);
+
+ // throws if it's not a Python string
+ std::stringresult(
+ boost::python::expect_non_null(
+ PyString_AsString(p)));
+
+ Py_DECREF(p);// Done with p
+
+ returnresult;
+}
+
+//
+// Demonstrate form 1 of handle_exception
+//
+
+// Place into result a Python Int object whose value is 1 if a and b have
+// identical "__name__" attributes, 0 otherwise.
+voidsame_name_impl(PyObject*&result,boost::python::objecta,boost::python::objectb)
+{
+ result=PyInt_FromLong(
+ get_name(a)==get_name(a2));
+}
+
+objectborrowed_object(PyObject*p)
+{
+ returnboost::python::object(
+ boost::python::handle<>(
+ boost::python::borrowed(a1)));
+}
+
+// This is an example Python 'C' API interface function
+extern"C"PyObject*
+same_name(PyObject*args,PyObject*keywords)
+{
+ PyObject*a1;
+ PyObject*a2;
+ PyObject*result=0;
+
+ if(!PyArg_ParseTuple(args,const_cast<char*>("OO"),&a1,&a2))
+ return0;
+
+ // Use boost::bind to make an object compatible with
+ // boost::Function0<void>
+ if(boost::python::handle_exception(
+ boost::bind<void>(same_name_impl,boost::ref(result),borrowed_object(a1),borrowed_object(a2))))
+ {
+ // an exception was thrown; the Python error was set by
+ // handle_exception()
+ return0;
+ }
+
+ returnresult;
+}
+
+//
+// Demonstrate form 2 of handle_exception. Not well-supported by all
+// compilers.
+//
+extern"C"PyObject*
+same_name2(PyObject*args,PyObject*keywords)
+{
+ PyObject*a1;
+ PyObject*a2;
+ PyObject*result=0;
+
+ if(!PyArg_ParseTuple(args,const_cast<char*>("OO"),&a1,&a2))
+ return0;
+
+ try{
+ returnPyInt_FromLong(
+ get_name(borrowed_object(a1))==get_name(borrowed_object(a2)));
+ }
+ catch(...)
+ {
+ // If an exception was thrown, translate it to Python
+ boost::python::handle_exception();
+ return0;
+ }
+}
+
+ As described here,
+ it is important to make sure that exceptions thrown by C++ code do not
+ pass into the Python interpreter core. By default, Boost.Python translates
+ all C++ exceptions thrown by wrapped functions and module init functions
+ into Python, but the default translators are extremely limited: most C++
+ exceptions will appear in Python as a RuntimeError
+ exception whose representation is 'Unidentifiable C++ Exception'. To produce
+ better error messages, users can register additional exception translators
+ as described below.
+
+ Translate is CopyConstructible, and the following code must be well-formed:
+
+
voidf(ExceptionTypex){translate(x);}
+
+ . The expression translate(x) must either throw a C++ exception,
+ or a subsequent call to PyErr_Occurred() must return 1.
+
+
+
Effects
+
+ Adds a copy of translate to the sequence of exception translators
+ tried when Boost.Python catches an exception that is about to pass
+ into Python's core interpreter. The new translator will get "first
+ shot" at translating all exceptions matching the catch clause
+ shown above. Any subsequently-registered translators will be allowed
+ to translate the exception earlier. A translator which cannot translate
+ a given C++ exception can re-throw it, and it will be handled by
+ a translator which was registered earlier (or by the default translator).
+
+ An init-expression is used to describe a family of __init__
+ methods to be generated for an extension class, and the result has the
+ following properties:
+
+
+
+
+
docstring
+
+ An ntbs whose value will bound to the
+ method's __doc__
+ attribute
+
+
keywords
+
+ A keyword-expression
+ which will be used to name (a trailing subsequence of) the arguments
+ to the generated __init__
+ function(s).
+
+ An MPL sequence of C++ argument types which will be used to construct
+ the wrapped C++ object. An init expression has one or more valid
+ prefixes which are given by a sequence of prefixes of its argument
+ types.
+
+ A MPL sequence which can be used to specify a family of one or more __init__
+ functions. Only the last Ti supplied may be an instantiation of optional<...>.
+
+ If supplied, doc is an ntbs. If supplied,
+ kw is the result of a
+
+
Effects
+
+
+ The result is an init-expression whose docstring is doc and whose
+ keywords are a reference to kw. If the first form is used, the
+ resulting expression's keywords are empty. The expression's call
+ policies are an instance of default_call_policies.
+ If Tn is optional<U1,
+ U2,... Um>, the expression's valid prefixes are given
+ by:
+
+ Returns a new init-expression
+ with all the same properties as the init object except that its
+ call policies are replaced by a reference to policies.
+
+ <boost/python/iterator.hpp> provides types and functions for creating
+ Python
+ iterators from C++ Containers and Iterators. Note that if your
+ class_ supports random-access
+ iterators, implementing __getitem__
+ (also known as the Sequence Protocol) may serve you better than using this
+ facility: Python will automatically create an iterator type for you (see
+ iter()),
+ and each access can be range-checked, leaving no possiblity of accessing
+ through an invalidated C++ iterator.
+
+ Instances of iterator<C,P> hold a reference to a callable Python
+ object which, when invoked from Python, expects a single argument c convertible
+ to C and creates a Python iterator that traverses [c.begin(),c.end()). The optional CallPolicies
+ P can be used to control
+ how elements are returned during iteration.
+
+
+ In the table below, c is an instance of Container.
+
+
+
+
+
+
+
+
+
+
+
+ Template Parameter
+
+
+
+
+ Requirements
+
+
+
+
+ Semantics
+
+
+
+
+ Default
+
+
+
+
+
+
+
+ Container
+
+
+
+
+ [c.begin(),c.end()) is a valid Iterator range.
+
+
+
+
+ The result will convert its argument to c and call c.begin()
+ and c.end() to acquire iterators. To invoke Container's const
+ begin()
+ and end()
+ functions, make it const.
+
+
+
+
+
+
+
+
+ NextPolicies
+
+
+
+
+ A default-constructible model of CallPolicies.
+
+
+
+
+ Applied to the resulting iterators' next() method.
+
+
+
+
+ An unspecified model of CallPolicies
+ which always makes a copy of the result of deferencing the underlying
+ C++ iterator
+
+ A utility class template which provides a way to reliably call its argument's
+ begin()
+ and end()
+ member functions. Note that there is no portable way to take the address
+ of a member function of a C++ standard library container, so iterators<>
+ can be particularly helpful when wrapping them.
+
+
+ In the table below, x is an instance of C.
+
+
+
+
+
+
+
+
+
+ Required Valid Expression
+
+
+
+
+ Type
+
+
+
+
+
+
+
+ x.begin()
+
+
+
+
+ Convertible to C::const_iterator if C is a const type; convertible
+ to C::iterator otherwise.
+
+
+
+
+
+
+ x.end()
+
+
+
+
+ Convertible to C::const_iterator if C is a const type; convertible
+ to C::iterator otherwise.
+
+ NextPolicies is a default-constructible model of CallPolicies.
+
+
Effects
+
+
+ The first form creates a Python callable object which, when invoked,
+ converts its argument to a Target object x, and creates a Python
+ iterator which traverses [bind(start,_1)(x),bind(finish,_1)(x)),
+ applying NextPolicies to the iterator's next() function. The second form is identical
+ to the first, except that Target is deduced from Accessor1 as follows:
+
+
+ # If Accessor1 is a function type, Target is the type of its first
+ argument. # If Accessor1 is a data member pointer of the form R(T::*),
+ Target is identical to T.
+ # If Accessor1 is a member function pointer of the form R(T::*)(arguments...)
+ cv-opt, where cv-opt is an optional
+ cv-qualifier, Target is identical to T.
+
+
+ The third form is identical to the second, except that NextPolicies
+ is an unspecified model of CallPolicies
+ which always makes a copy of the result of deferencing the underlying
+ C++ iterator
+
+
+
Rationale
+
+ The use of boost::bind() allows C++ iterators to be accessed
+ through functions, member functions or data member pointers. Customization
+ of NextPolicies (e.g. using return_internal_reference)
+ is useful when it is expensive to copy sequence elements of a wrapped
+ class type. Customization of Target is useful when Accessor1 is a
+ function object, or when a base class of the intended target type
+ would otherwise be deduced.
+
+ BOOST_PYTHON_MODULE(name)
+ is used to declare Python module
+ initialization functions. The name argument must exactly match
+ the name of the module to be initialized, and must conform to Python's
+ identifier
+ naming rules. Where you would normally write
+
+
extern"C"voidinitname()
+{
+ ...
+}
+
+
+ Boost.Python modules should be initialized with
+
+
BOOST_PYTHON_MODULE(name)
+{
+ ...
+}
+
+
+ This macro generates two functions in the scope where it is used: extern"C"
+ voidinitname(), and void
+ init_module_name(),
+ whose body must follow the macro invocation. init_name
+ passes init_module_name
+ to handle_exception()
+ so that any C++ exceptions generated are safely processeed. During the
+ body of init_name, the
+ current scope
+ refers to the module being initialized.
+
+ <boost/python/operators.hpp> provides types and functions for automatically
+ generating Python special
+ methods from the corresponding C++ constructs. Most of these constructs
+ are operator expressions, hence the name. To use the facility, substitute
+ the self
+ object for an object of the class type being wrapped in the expression
+ to be exposed, and pass the result to class_<>::def().
+ Much of what is exposed in this header should be considered part of the
+ implementation, so is not documented in detail here.
+
+ self_ns::self_t is the actual type of the self
+ object. The library isolates self_t
+ in its own namespace, self_ns,
+ in order to prevent the generalized operator templates which operate on
+ it from being found by argument-dependent lookup in other contexts. This
+ should be considered an implementation detail, since users should never
+ have to mention self_t
+ directly.
+
+ The tables below describe the methods generated when the results of the
+ expressions described are passed as arguments to class_<>::def().
+ x is an object of the class
+ type being wrapped.
+
+ In the tables below, if r
+ is of type self_t,
+ y is an object of the
+ same type as x; if l or r
+ is an object of type other<T>,
+ y is an object of type
+ T; otherwise, y is an object of the same type as
+ l or r.
+ l is never of type self_t.
+
+
+ The column of Python Expressions illustrates the expressions that will
+ be supported in Python for objects convertible to the types of x and
+ y. The secondary operation arises due to Python's reflection
+ rules for rich comparison operators, and are only used when the
+ corresponding operation is not defined as a method of the y object.
+
+ The operations whose names begin with "__r" below will only
+ be called if the left-hand operand does not already support the given
+ operation, as described here.
+
+ Instances of other<T>
+ can be used in operator expressions with self;
+ the result is equivalent to the same expression with a T
+ object in place of other<T>. Use other<T> to prevent construction of a T object in case it is heavyweight, when
+ no constructor is available, or simply for clarity.
+
+ Instantiations of detail::operator_<> are used as the return type of
+ operator expressions involving self.
+ This should be considered an implementation detail and is only documented
+ here as a way of showing how the result of self-expressions match calls
+ to class_<>::def().
+
+ The scope class has an associated global Python object which controls the
+ Python namespace in which new extension classes and wrapped functions will
+ be defined as attributes. Default-constructing a new scope object binds
+ it to the associated global Python object. Constructing a scope object
+ with an argument changes the associated global Python object to the one
+ held by the argument, until the lifetime of the scope object ends, at which
+ time the associated global Python object reverts to what it was before
+ the scope object was constructed.
+
+ Stores a reference to the current associated scope object, and sets the
+ associated scope object to the one referred to by x.ptr(). The object base
+ class is initialized with x.
+
+
scope();
+
+ Stores a reference to the current associated scope object. The object base
+ class is initialized with the current associated scope object. Outside
+ any module initialization function, the current associated Python object
+ is None.
+
+
~scope()
+
+ Sets the current associated Python object to the stored object.
+
+ The following example shows how scope setting can be used to define nested
+ classes.
+
+
+ C++ Module definition:
+
+
#include<boost/python/module.hpp>
+#include<boost/python/class.hpp>
+#include<boost/python/scope.hpp>
+usingnamespaceboost::python;
+
+structX
+{
+ voidf(){}
+
+ structY{intg(){return42;}};
+};
+
+BOOST_PYTHON_MODULE(nested)
+{
+ // add some constants to the current (module) scope
+ scope().attr("yes")=1;
+ scope().attr("no")=0;
+
+ // Change the current scope
+ scopeouter
+ =class_<X>("X")
+ .def("f",&X::f)
+ ;
+
+ // Define a class Y in the current scope, X
+ class_<X::Y>("Y")
+ .def("g",&X::Y::g)
+ ;
+}
+
+ Instances of stl_input_iterator<T> hold a Python iterator and adapt it
+ for use with STL algorithms. stl_input_iterator<T> satisfies the requirements for an Input
+ Iterator.
+
+
+
+
+
+
+
+
+
+
+
+ Template Parameter
+
+
+
+
+ Requirements
+
+
+
+
+ Semantics
+
+
+
+
+ Default
+
+
+
+
+
+
+ ValueType
+
+
+
+
+ ValueType must be CopyConstructible.
+
+
+
+
+ Dereferencing an instance of stl_input_iterator<ValueType> will return an rvalue of
+ type ValueType.
+
+ Creates a past-the-end input iterator, useful for signifying the
+ end of a sequence.
+
+
Postconditions
+
+ this is past-the-end
+
+
Throws
+
+ Nothing.
+
+
+
+
stl_input_iterator(objectconst&ob)
+
+
+
+
Effects
+
+ Calls ob.attr("__iter__")() and stores the resulting Python
+ iterator object in this->it. Then, calls this->it.attr("next")()
+ and stores the result in this->ob. If the sequence is exhausted,
+ sets this->ob to object().
+
+ To wrap a class T such that its virtual functions can be "overridden
+ in Python"—so that the corresponding method of a Python derived
+ class will be called when the virtual function is invoked from C++—you
+ must create a C++ wrapper class derived from T
+ that overrides those virtual functions so that they call into Python. This
+ header contains classes that can be used to make that job easier.
+
+ If *this holds a callable Python object, it is invoked with the specified
+ arguments in the manner specified here. Otherwise, throws error_already_set.
+
+
Returns
+
+ An object of unspecified type that holds the Python result of the
+ invocation and, when converted to a C++ type R, attempts to convert
+ that result object to R. If that conversion fails, throws error_already_set.
+
+ If *this
+ is the C++ base class subobject of a Python derived class instance
+ that overrides the named function, returns an override object that
+ delegates to the Python override. Otherwise, returns an override
+ object that holds None.
+
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt
+
+ Exposes the mapping
+ protocol of Python's built-in dict
+ type. The semantics of the constructors and member functions defined below
+ can be fully understood by reading the TypeWrapper
+ concept definition. Since dict
+ is publicly derived from object, the public object interface applies to dict instances as well.
+
+ Exposes the mapping
+ protocol of Python's built-in list
+ type. The semantics of the constructors and member functions defined below
+ can be fully understood by reading the TypeWrapper
+ concept definition. Since list
+ is publicly derived from object, the public object interface applies to list instances as well.
+
+ Exposes the numeric
+ type protocol of Python's built-in long
+ type. The semantics of the constructors and member functions defined below
+ can be fully understood by reading the TypeWrapper
+ concept definition. Since long_
+ is publicly derived from object, the public object interface applies to long_ instances as well.
+
+ Provides access to the array types of Numerical
+ Python's Numeric
+ and NumArray
+ modules. With the exception of the functions documented below, the semantics
+ of the constructors and member functions defined below can be fully understood
+ by reading the TypeWrapper
+ concept definition. Since array is publicly derived from object, the public
+ object interface applies to array instances as well.
+
+
+ The default behavior is to use numarray.NDArray as the associated Python
+ type if the numarray module is installed in the default location. Otherwise
+ it falls back to use Numeric.ArrayType. If neither extension module is
+ installed, overloads of wrapped C++ functions with numeric::array parameters
+ will never be matched, and other attempted uses of numeric::array will
+ raise an appropriate Python exception. The associated Python type can be
+ set manually using the set_module_and_type(...) static function.
+
+ These functions map to the underlying array type's array() function family.
+ They are not called "array" because of the C++ limitation that
+ you can't define a member function with the same name as its enclosing
+ class.
+
+ package_path and type_name, if supplied, is an ntbs.
+
+
Effects
+
+ The first form sets the package path of the module that supplies
+ the type named by type_name to package_path. The second form restores
+ the default search behavior. The associated Python type will be searched
+ for only the first time it is needed, and thereafter the first time
+ it is needed after an invocation of set_module_and_type.
+
+
+
+
staticstd::stringget_module_name()
+
+
+
+
Effects
+
+ Returns the name of the module containing the class that will be
+ held by new numeric::array
+ instances.
+
#include<boost/python/numeric.hpp>
+#include<boost/python/tuple.hpp>
+
+// sets the first element in a 2d numeric array
+voidset_first_element(numeric::array&y,doublevalue)
+{
+ y[make_tuple(0,0)]=value;
+}
+
+ Exposes the generic Python object wrapper class object, and related classes.
+ In order to avoid some potenential problems with argument-dependent lookup
+ and the generalized operators defined on object, all these facilities are
+ defined in namespace boost::python::api, and object is imported into namespace
+ boost::python with a using-declaration.
+
+ This is the base class of object and its proxy template used to supply
+ common interface: member functions, and operators which must be defined
+ within the class body. Its template parameter U is expected to be a class
+ derived from object_operators<U>. In practice users should never
+ use this class directly, but it is documented here because it supplies
+ important interface to object and its proxies.
+
+ The intention is that object acts as much like a Python variable as possible.
+ Thus expressions you'd expect to work in Python should generally work in
+ the same way from C++. Most of object's interface is provided by its base
+ class object_operators<object>, and the free functions defined in
+ this header.
+
+ This template is instantiated with various Policies described in this document
+ in order to implement attribute, item, and slice access for object. It
+ stores an object of type Policies::key_type.
+
+ Exposes the extended slicing protocol by wrapping the built-in slice type.
+ The semantics of the constructors and member functions defined below can
+ be fully understood by reading the TypeWrapper
+ concept definition. Since slice
+ is publicly derived from object, the public object interface applies to slice instances as well.
+
+
namespaceboost{namespacepython
+{
+ classslice:publicobject
+ {
+ public:
+ slice();// create an empty slice, equivalent to [::]
+
+ template<typenameInt1,typenameInt2>
+ slice(Int1start,Int2stop);
+
+ template<typenameInt1,typenameInt2,typenameInt3>
+ slice(Int1start,Int2stop,Int3step);
+
+ // Access the parameters this slice was created with.
+ objectstart();
+ objectstop();
+ objectstep();
+
+ // The return type of slice::get_indices()
+ template<typenameRandomAccessIterator>
+ structrange
+ {
+ RandomAccessIteratorstart;
+ RandomAccessIteratorstop;
+ intstep;
+ };
+
+ template<typenameRandomAccessIterator>
+ range<RandomAccessIterator>
+ get_indices(
+ RandomAccessIteratorconst&begin,
+ RandomAccessIteratorconst&end);
+ };
+}}
+
+ start, stop, and step
+ are of type slice_nil
+ or convertible to type object.
+
+
Effects
+
+ constructs a new slice with default step value and the provided start
+ and stop values. Equivalent to the slice object created by the built-in
+ Python function slice(start,stop), or as part of the Python expression
+ base[start:stop].
+
+
Throws
+
+ error_already_set
+ and sets a Python TypeError exception if no conversion is possible
+ from the arguments to type object.
+
+ start, stop, and step
+ are slice_nil or
+ convertible to type object.
+
+
Effects
+
+ constructs a new slice with start stop and step values. Equivalent
+ to the slice object created by the built-in Python function slice(start,stop,step),
+ or as part of the Python expression base[start:stop:step].
+
+
Throws
+
+ error_already_set
+ and sets a Python TypeError exception if no conversion is possible
+ from the arguments to type object.
+
+ the parameter that the slice was created with. If the parameter was
+ omitted or slice_nil
+ was used when the slice was created, than that parameter will be
+ a reference to PyNone
+ and compare equal to a default-constructed object. In principal,
+ any object may be used when creating a slice object, but in practice
+ they are usually integers.
+
+ A pair of STL-conforming Random Access Iterators that form a half-open
+ range.
+
+
Effects
+
+ Create a RandomAccessIterator pair that defines a fully-closed range
+ within the [begin,end) range of its arguments. This function
+ translates this slice's indices while accounting for the effects
+ of any PyNone or negative indices, and non-singular step sizes.
+
+
Returns
+
+ a slice::range that has been initialized
+ with a non-zero value of step and a pair of RandomAccessIterators
+ that point within the range of this functions arguments and define
+ a closed interval.
+
+
Throws
+
+ Raises a Python TypeError exception if any of this slice's arguments
+ are neither references to PyNone nor convertible to int. Throws
+ std::invalid_argument if the resulting
+ range would be empty. You should always wrap calls to slice::get_indices()
+ within try{
+ ...;}
+ catch(std::invalid_argument)
+ {} to handle this case and
+ take appropriate action.
+
+
Rationale
+
+ closed-interval: If an open interval were used, then for step size
+ other than 1, the required state for the end iterator would point
+ beyond the one-past-the-end position or before the beginning of the
+ specified range. exceptions on empty slice: It is impossible to define
+ a closed interval over an empty range, so some other form of error
+ checking would have to be used to prevent undefined behavior. In
+ the case where the exception is not caught, it will simply be translated
+ to Python by the default exception handling mechanisms.
+
usingnamespaceboost::python;
+
+// Perform an extended slice of a Python list.
+// Warning: extended slicing was not supported for built-in types prior
+// to Python 2.3
+listodd_elements(listl)
+{
+ returnl[slice(_,_,2)];
+}
+
+// Perform a multidimensional extended slice of a Numeric.array
+numeric::arrayeven_columns(numeric::arrayarr)
+{
+ // select every other column, starting with the second, of a 2-D array.
+ // Equivalent to "return arr[:, 1::2]" in Python.
+ returnarr[make_tuple(slice(),slice(1,_,2))];
+}
+
+// Perform a summation over a slice of a std::vector.
+doublepartial_sum(std::vector<double>const&Foo,constsliceindex)
+{
+ slice::range<std::vector<double>::const_iterator>bounds;
+ try{
+ bounds=index.get_indices<>(Foo.begin(),Foo.end());
+ }
+ catch(std::invalid_argument){
+ return0.0;
+ }
+ doublesum=0.0;
+ while(bounds.start!=bounds.stop){
+ sum+=*bounds.start;
+ std::advance(bounds.start,bounds.step);
+ }
+ sum+=*bounds.start;
+ returnsum;
+}
+
+ Exposes the string
+ methods of Python's built-in str
+ type. The semantics of the constructors and member functions defined below,
+ except for the two-argument constructors which construct str objects from
+ a range of characters, can be fully understood by reading the TypeWrapper
+ concept definition. Since str is publicly derived from object, the public object interface applies to str instances as well.
+
+ Exposes the interface of Python's built-in tuple type. The semantics of
+ the constructors and member functions defined below can be fully understood
+ by reading the TypeWrapper
+ concept definition. Since tuple is publicly derived from object, the public object interface applies to tuple instances as well.
+
+ Exposes a mechanism for extracting C++ object values from generalized Python
+ objects. Note that extract<...> can also be used to "downcast"
+ an object to some specific ObjectWrapper. Because invoking
+ a mutable python type with an argument of the same type (e.g. list([1,2]) typically makes a copy of the argument
+ object, this may be the only way to access the ObjectWrapper's
+ interface on the original object.
+
+ extract<T>
+ can be used to extract a value of an arbitrary C++ type from an instance
+ of object.
+ Two usages are supported:
+
+
+
+ extract<T>(o)
+ is a temporary object which is implicitly convertible to T (explicit conversion is also available
+ through the object's function-call operator). However, if no conversion
+ is available which can convert o to an object of type T, a Python TypeError exception will
+ be raised.
+
+
+ extract<T>x(o);
+ constructs an extractor whose check() member function can be used to ask
+ whether a conversion is available without causing an exception to be
+ thrown.
+
+ Stores a pointer to the Python object managed by its constructor
+ argument. In particular, the reference count of the object is not
+ incremented. The onus is on the user to be sure it is not destroyed
+ before the extractor's conversion function is called.
+
+ Converts the stored pointer to result_type, which is either T or
+ T const&.
+
+
Returns
+
+ An object of result_type corresponding to the one referenced by the
+ stored pointer.
+
+
Throws
+
+ error_already_set and sets
+ a TypeError if no
+ such conversion is available. May also emit other unspecified exceptions
+ thrown by the converter which is actually used.
+
+
+
+
boolcheck()const;
+
+
+
+
Postconditions
+
+ None. In particular, note that a return value of true does not preclude
+ an exception being thrown from operator result_type() or operator()().
+
+
Returns
+
+ false only if no conversion from the stored pointer to T is available.
+
#include<cstdio>
+usingnamespaceboost::python;
+intPrint(strs)
+{
+ // extract a C string from the Python string object
+ charconst*c_str=extract<charconst*>(s);
+
+ // Print it using printf
+ std::printf("%s\n",c_str);
+
+ // Get the Python string's length and convert it to an int
+ returnextract<int>(s.attr("__len__")())
+}
+
+
+ The following example shows how extract can be used along with class_<...>
+ to create and access an instance of a wrapped C++ class.
+
+
structX
+{
+ X(intx):v(x){}
+ intvalue(){returnv;}
+ private:
+ intv;
+};
+
+BOOST_PYTHON_MODULE(extract_ext)
+{
+ objectx_class(
+ class_<X>("X",init<int>())
+ .def("value",&X::value))
+ ;
+
+ // Instantiate an X object through the Python interface.
+ // Its lifetime is now managed by x_obj.
+ objectx_obj=x_class(3);
+
+ // Get a reference to the C++ object out of the Python object
+ X&x=extract<X&>(x_obj);
+ assert(x.value()==3);
+}
+
+ implicitly_convertible
+ allows Boost.Python to implicitly take advantage of a C++ implicit or explicit
+ conversion when matching Python objects to C++ argument types.
+
+ The declaration Target
+ t(s);,
+ where s is of type Source, is valid.
+
+
Effects
+
+ registers an rvalue from_python
+ converter to Target which can succeed for any PyObject*p
+ iff there exists any registered converter which can produce Source
+ rvalues
+
+
Rationale
+
+ C++ users expect to be able to take advantage of the same sort of
+ interoperability in Python as they do in C++.
+
+ <boost/python/lvalue_from_pytype.hpp> supplies a facility for extracting
+ C++ objects from within Python instances of a given type. This is typically
+ useful for dealing with "traditional" Python extension types.
+
+ Class template lvalue_from_pytype will register from_python converters
+ which, given an object of the given Python type, can extract references
+ and pointers to a particular C++ type. Its template arguments are:
+
+ extract_identity is a model of Extractor which can be used in
+ the common case where the C++ type to be extracted is the same as the Python
+ object type.
+
+ extract_member is a model
+ of Extractor
+ which can be used in the common case in the common case where the C++ type
+ to be extracted is a member of the Python object.
+
+ This example presumes that someone has implemented the standard noddy example
+ module from the Python documentation, and we want to build a module which
+ manipulates Noddys. Since noddy_NoddyObject is so simple that it carries
+ no interesting information, the example is a bit contrived: it assumes
+ you want to keep track of one particular object for some reason. This module
+ would have to be dynamically linked to the module which defines noddy_NoddyType.
+
+ * Registers the instance as a lvalue_from_pytype converter
+ from Python objects into opaque pointers. The Python Objects created
+ are named after the type pointed to by the opaque pointer being wrapped.
+ * Registers the instance as a to_python_converter from
+ opaque pointers to Python objects.
+
+
+
+
+
+
+
Note
+
+
+ If there is already an instance registered by another module, this instance
+ doesn't try to register again in order to avoid warnings about multiple
+ registrations.
+
+ <boost/python/register_ptr_to_python.hpp> supplies register_ptr_to_python, a function template
+ which registers a conversion for smart pointers to Python. The resulting
+ Python object holds a copy of the converted smart pointer, but behaves
+ as though it were a wrapped copy of the pointee. If the pointee type has
+ virtual functions and the class representing its dynamic (most-derived)
+ type has been wrapped, the Python object will be an instance of the wrapper
+ for the most-derived type. More than one smart pointer type for a pointee's
+ class can be registered.
+
+
+ Note that in order to convert a Python X
+ object to a smart_ptr<X>&
+ (non-const reference), the embedded C++ object must be held by smart_ptr<X>,
+ and that when wrapped objects are created by calling the constructor from
+ Python, how they are held is determined by the HeldType parameter to class_<...>
+ instances.
+
+ to_python_converter adds
+ a wrapper around a static member function of its second template parameter,
+ handling low-level details such as insertion into the converter registry.
+
+
+ In the table below, x denotes an object of type T
+
+
+
+
+
+
+
+
+
+
+ Parameter
+
+
+
+
+ Requirements
+
+
+
+
+ Description
+
+
+
+
+
+
+
+ T
+
+
+
+
+
+
+ The C++ type of the source object in the conversion
+
+ Optional member - if Conversion has get_pytype
+ member supply true
+ for this parameters. If present get_pytype
+ is used to document the return type of functions using this conversion.
+ The get_pytype
+ may be implemented using the classes and functions from pytype_function.hpp
+ NOTE : For backward compatibility this parameter may be passed
+ after checking if BOOST_PYTHON_SUPPORTS_PY_SIGNATURES is defined
+ (see here).
+
+ This example presumes that someone has implemented the standard noddy example
+ module from the Python documentation, and placed the corresponding declarations
+ in "noddy.h". Because noddy_NoddyObject is the ultimate trivial
+ extension type, the example is a bit contrived: it wraps a function for
+ which all information is contained in the type of its return value.
+
+ The simplest way to call a Python function from C++, given an object instance f holding the
+ function, is simply to invoke its function call operator.
+
+
f("tea",4,2)// In Python: f('tea', 4, 2)
+
+ And of course, a method of an object instance x can be invoked by using the function-call
+ operator of the corresponding attribute:
+
+
x.attr("tea")(4,2);// In Python: x.tea(4, 2)
+
+ If you don't have an object instance, Boost.Python provides two families of function
+ templates, call and call_method, for invoking Python
+ functions and methods respectively on PyObject*s. The interface for calling a Python function
+ object (or any Python callable object) looks like:
+
+
call<ResultType>(callable_object,a1,a2...aN);
+
+ Calling a method of a Python object is similarly easy:
+
+ Arguments are converted to Python according to their type. By default,
+ the arguments a1...aN are copied into new Python objects,
+ but this behavior can be overridden by the use of ptr()
+ and ref():
+
+
classX:boost::noncopyable
+{
+ ...
+};
+
+voidapply(PyObject*callable,X&x)
+{
+ // Invoke callable, passing a Python object which holds a reference to x
+ boost::python::call<void>(callable,boost::ref(x));
+}
+
+
+ In the table below, x denotes the actual argument object and cv denotes
+ an optional cv-qualification: "const", "volatile",
+ or "const volatile".
+
+
+
+
+
+
+
+
+
+ Argument Type
+
+
+
+
+ Behavior
+
+
+
+
+
+
+
+ Tcv
+ &T
+ cv
+
+
+
+
+ The Python argument is created by the same means used for the
+ return value of a wrapped C++ function returning T. When T is
+ a class type, that normally means *x is copy-constructed into
+ the new Python object.
+
+
+
+
+
+
+ T*
+
+
+
+
+ If x == 0, the Python argument will be None. Otherwise, the Python
+ argument is created by the same means used for the return value
+ of a wrapped C++ function returning T. When T is a class type,
+ that normally means *x is copy-constructed into the new Python
+ object.
+
+
+
+
+
+
+ boost::reference_wrapper<T>
+
+
+
+
+ The Python argument contains a pointer to, rather than a copy
+ of, x.get(). Note: failure to ensure that no Python code holds
+ a reference to the resulting object beyond the lifetime of *x.get()
+ may result in a crash!
+
+
+
+
+
+
+ pointer_wrapper<T>
+
+
+
+
+ If x.get() == 0, the Python argument will be None. Otherwise,
+ the Python argument contains a pointer to, rather than a copy
+ of, *x.get(). Note: failure to ensure that no Python code holds
+ a reference to the resulting object beyond the lifetime of *x.get()
+ may result in a crash!
+
+ In general, call<ResultType>()
+ and call_method<ResultType>() return ResultType by exploiting all
+ lvalue and rvalue from_python converters registered for ResultType and
+ returning a copy of the result. However, when ResultType is a pointer or
+ reference type, Boost.Python searches only for lvalue converters. To prevent
+ dangling pointers and references, an exception will be thrown if the Python
+ result object has only a single reference count.
+
+ In general, to get Python arguments corresponding to a1...aN, a new Python
+ object must be created for each one; should the C++ object be copied into
+ that Python object, or should the Python object simply hold a reference/pointer
+ to the C++ object? In general, the latter approach is unsafe, since the
+ called function may store a reference to the Python object somewhere. If
+ the Python object is used after the C++ object is destroyed, we'll crash
+ Python.
+
+
+ In keeping with the philosophy that users on the Python side shouldn't
+ have to worry about crashing the interpreter, the default behavior is to
+ copy the C++ object, and to allow a non-copying behavior only if the user
+ writes boost::ref(a1) instead of a1 directly. At least this way, the user
+ doesn't get dangerous behavior "by accident". It's also worth
+ noting that the non-copying ("by-reference") behavior is in general
+ only available for class types, and will fail at runtime with a Python
+ exception if used otherwise[1].
+
+
+ However, pointer types present a problem: one approach is to refuse to
+ compile if any aN has pointer type: after all, a user can always pass *aN
+ to pass "by-value" or ref(*aN) to indicate a pass-by-reference
+ behavior. However, this creates a problem for the expected null pointer
+ to None conversion: it's illegal to dereference a null pointer value.
+
+
+ The compromise I've settled on is this:
+
+
+
+ The default behavior is pass-by-value. If you pass a non-null pointer,
+ the pointee is copied into a new Python object; otherwise the corresponding
+ Python argument will be None.
+
+
+ if you want by-reference behavior, use ptr(aN) if aN is a pointer and
+ ref(aN) otherwise. If a null pointer is passed to ptr(aN), the corresponding
+ Python argument will be None.
+
+
+
+ As for results, we have a similar problem: if ResultType is allowed to
+ be a pointer or reference type, the lifetime of the object it refers to
+ is probably being managed by a Python object. When that Python object is
+ destroyed, our pointer dangles. The problem is particularly bad when the
+ ResultType is char const* - the corresponding Python String object is typically
+ uniquely-referenced, meaning that the pointer dangles as soon as call<char
+ const*>(...) returns.
+
+
+ The old Boost.Python v1 deals with this issue by refusing to compile any
+ uses of call<char const*>(), but this goes both too far and not far
+ enough. It goes too far because there are cases where the owning Python
+ string object survives beyond the call (just for instance, when it's the
+ name of a Python class), and it goes not far enough because we might just
+ as well have the same problem with a returned pointer or reference of any
+ other type.
+
+
+ In Boost.Python this is dealt with by:
+
+
+
+ lifting the compile-time restriction on char
+ const*
+ callback returns
+
+
+ detecting the case when the reference count on the result Python object
+ is 1 and throwing an exception inside of call<U>(...) when U
+ is a pointer or reference type.
+
+
+
+ This should be acceptably safe because users have to explicitly specify
+ a pointer/reference for U
+ in call<U>,
+ and they will be protected against dangles at runtime, at least long enough
+ to get out of the call<U>(...) invocation.
+
+ Indexing is a BoostPython
+ facility for easy exportation of indexable C++ containers to Python. Indexable
+ containers are containers that allow random access through the operator[]
+ (e.g. std::vector).
+
+
+ While BoostPython
+ has all the facilities needed to expose indexable C++ containers such as
+ the ubiquitous std::vector to Python, the procedure is not as straightforward
+ as we'd like it to be. Python containers do not map easily to C++ containers.
+ Emulating Python containers in C++ (see Python Reference Manual, Emulating
+ container types) using Boost.Python
+ is non trivial. There are a lot of issues to consider before we can map
+ a C++ container to Python. These involve implementing wrapper functions
+ for the methods __len__,
+ __getitem__, __setitem__, __delitem__,
+ __iter__ and __contains__.
+
+
+ The goals:
+
+
+
+ Make indexable C++ containers behave exactly as one would expect a
+ Python container to behave.
+
+
+ Provide default reference semantics for container element indexing
+ (__getitem__) such
+ that c[i] can be mutable. Require:
+
val=c[i]
+c[i].m()
+val==c[i]
+
+
+ where m is a non-const (mutating) member function (method).
+
+
+
+ Return safe references from __getitem__
+ such that subsequent adds and deletes to and from the container will
+ not result in dangling references (will not crash Python).
+
+ The indexing_suite class
+ is the base class for the management of C++ containers intended to be integrated
+ to Python. The objective is make a C++ container look and feel and behave
+ exactly as we'd expect a Python container. The class automatically wraps
+ these special Python methods (taken from the Python reference: Emulating
+ container types):
+
+
+
+
+
__len__(self)
+
+ Called to implement the built-in function len(). Should return the length of the
+ object, an integer >=0. Also, an object that doesn't define
+ a __nonzero__()
+ method and whose __len__() method returns zero is considered
+ to be false in a Boolean context.
+
+
__getitem__(self, key)
+
+ Called to implement evaluation of self[key]. For sequence types, the accepted
+ keys should be integers and slice objects. Note that the special
+ interpretation of negative indexes (if the class wishes to emulate
+ a sequence type) is up to the __getitem__() method. If key is of an inappropriate
+ type, TypeError may
+ be raised; if of a value outside the set of indexes for the sequence
+ (after any special interpretation of negative values), IndexError
+ should be raised. [Note: for loops expect that an IndexError will
+ be raised for illegal indexes to allow proper detection of the end
+ of the sequence.]
+
+
__setitem__(self, key, value)
+
+ Called to implement assignment to self[key]. Same note as for __getitem__().
+ This should only be implemented for mappings if the objects support
+ changes to the values for keys, or if new keys can be added, or for
+ sequences if elements can be replaced. The same exceptions should
+ be raised for improper key values as for the __getitem__() method.
+
+
__delitem__(self, key)
+
+ Called to implement deletion of self[key]. Same note as for __getitem__().
+ This should only be implemented for mappings if the objects support
+ removal of keys, or for sequences if elements can be removed from
+ the sequence. The same exceptions should be raised for improper key
+ values as for the __getitem__() method.
+
+
__iter__(self)
+
+
+ This method is called when an iterator is required for a container.
+ This method should return a new iterator object that can iterate
+ over all the objects in the container. For mappings, it should iterate
+ over the keys of the container, and should also be made available
+ as the method iterkeys().
+
+
+ Iterator objects also need to implement this method; they are required
+ to return themselves. For more information on iterator objects, see
+ Iterator
+ Types in the Python
+ Library Reference.
+
+
+
__contains__(self, item)
+
+ Called to implement membership test operators. Should return true
+ if item is in self, false otherwise. For mapping objects, this should
+ consider the keys of the mapping rather than the values or the key-item
+ pairs.
+
+ The indexing_suite is not
+ meant to be used as is. A couple of policy functions must be supplied by
+ subclasses of indexing_suite.
+ However, a set of indexing_suite subclasses for the standard indexable
+ STL containers will be provided, In most cases, we can simply use the available
+ predefined suites. In some cases, we can refine the predefined suites to
+ suit our needs.
+
+ The vector_indexing_suite
+ class is a predefined indexing_suite
+ derived class designed to wrap std::vector
+ (and std::vector-like [i.e. a class with std::vector interface]) classes. It provides
+ all the policies required by the indexing_suite.
+
+ The map_indexing_suite
+ class is a predefined indexing_suite
+ derived class designed to wrap std::map
+ (and std::map-like [i.e. a class with std::map interface]) classes. It provides
+ all the policies required by the indexing_suite.
+
+ By default indexed elements are returned by proxy. This can be disabled
+ by supplying true in the
+ NoProxy template parameter.
+ XMap is now a full-fledged Python container (see the example in full,
+ along with its python test).
+
+ Derived classes provide the policy hooks. See DerivedPolicies
+ below.
+
+
+
+
+
+
+
+
+ NoProxy
+
+
+
+
+ A boolean
+
+
+
+
+ By default indexed elements have Python reference semantics and
+ are returned by proxy. This can be disabled by supplying true
+ in the NoProxy template parameter.
+
+ Most of these policies are self explanatory. However, convert_index and
+ adjust_index deserve some explanation.
+
+
+ convert_index converts a Python index into a C++ index that the container
+ can handle. For instance, negative indexes in Python, by convention,
+ start counting from the right(e.g. C1
+ indexes the rightmost element in C). convert_index should handle the
+ necessary conversion for the C++ container (e.g. convert -1 to C.size()-1).
+ convert_index should also be able to convert the type of the index (A
+ dynamic Python type) to the actual type that the C++ container expects.
+
+
+ When a container expands or contracts, held indexes to its elements must
+ be adjusted to follow the movement of data. For instance, if we erase
+ 3 elements, starting from index 0 from a 5 element vector, what used
+ to be at index 4 will now be at index 1:
+
+
[a][b][c][d][e]--->[d][e]
+ ^^
+ 41
+
+
+ adjust_index takes care of the adjustment. Given a current index, the
+ function should return the adjusted index when data in the container
+ at index from..to is replaced by len elements.
+
+ By default indexed elements have Python reference semantics and
+ are returned by proxy. This can be disabled by supplying true
+ in the NoProxy template parameter.
+
+
+
+
+ false
+
+
+
+
+
+
+ DerivedPolicies
+
+
+
+
+ A subclass of indexing_suite
+
+
+
+
+ The vector_indexing_suite may still be derived to further tweak
+ any of the predefined policies. Static polymorphism through CRTP
+ (James Coplien. "Curiously Recurring Template Pattern".
+ C++ Report, Feb. 1995) enables the base indexing_suite class
+ to call policy function of the most derived class
+
+ By default indexed elements have Python reference semantics and
+ are returned by proxy. This can be disabled by supplying true
+ in the NoProxy template parameter.
+
+
+
+
+ false
+
+
+
+
+
+
+ DerivedPolicies
+
+
+
+
+ A subclass of indexing_suite
+
+
+
+
+ The vector_indexing_suite may still be derived to further tweak
+ any of the predefined policies. Static polymorphism through CRTP
+ (James Coplien. "Curiously Recurring Template Pattern".
+ C++ Report, Feb. 1995) enables the base indexing_suite class
+ to call policy function of the most derived class
+
+ 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 through the interface
+ as described in detail in the Python
+ Library Reference for pickle. This interface involves the special
+ methods __getinitargs__,
+ __getstate__ and __setstate__ as described in the following.
+ Note that Boost.Python is also fully compatible with
+ Python's cPickle module.
+
+ 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, pickle.load
+ will call the constructor (__init__)
+ without arguments; i.e., the object must be default-constructible.
+
+
+
__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.
+
+
__setstate__
+
+ When an instance of a Boost.Python
+ extension class is restored by the unpickler (pickle.load),
+ 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.
+
+
+
+
+ The three special methods described above may be .def()'ed
+ individually by the user. However, Boost.Python
+ provides an easy to use high-level interface via the boost::python::pickle_suite
+ class that also enforces consistency: __getstate__
+ and __setstate__ must be
+ defined as pairs. Use of this interface is demonstrated by the following
+ examples.
+
+ 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__.
+ This is done in the following way: Definition of the C++ pickle function:
+
+ 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 guard described below 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 a little more code but is unavoidable if the object's __dict__ is not always empty.
+
+ The pickle protocol described above has an important pitfall that the end
+ user of a Boost.Python extension module might not be aware of:
+
+
+ __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:
+
+ 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 either at the C++ or the Python level.
+ Finally, the safety guard should intentionally be overridden. E.g. in C++
+ (from pickle3.cpp):
+
+ 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.
+
+
+ Avoid using __getstate__
+ if the instance can also be reconstructed by way of __getinitargs__.
+ This automatically avoids the pitfall described above.
+
+
+ If __getstate__ is
+ required, include the instance's __dict__
+ in the Python object that is returned.
+
+ The pickle4.cpp example demonstrates an alternative technique for implementing
+ pickle support. First we direct Boost.Python via the class_::enable_pickling()
+ member function to define only the basic attributes required for pickling:
+
+ This enables the standard Python pickle interface as described in the Python
+ documentation. By "injecting" a __getinitargs__
+ method into the definition of the wrapped class we make all instances pickleable:
+
+ <boost/python/has_back_reference.hpp> defines the predicate metafunction
+ has_back_reference<>,
+ which can be specialized by the user to indicate that a wrapped class instance
+ holds a PyObject*
+ corresponding to a Python object.
+
+ A metafunction that is inspected by Boost.Python to determine how wrapped
+ classes can be constructed.
+
+
+ type::value is an integral constant convertible
+ to bool of unspecified type. Specializations may substitute a true-valued
+ integral constant wrapper for type iff for each invocation of class_<WrappedClass>::def(init<type-sequence...>())
+ and the implicitly wrapped copy constructor (unless it is noncopyable),
+ there exists a corresponding constructor WrappedClass::WrappedClass(PyObject*,type-sequence...). If such a specialization exists, the
+ WrappedClass constructors will be called with a "back reference"
+ pointer to the corresponding Python object whenever they are invoked from
+ Python. The easiest way to provide this nested type is to derive the specialization
+ from mpl::true_.
+
+ The following Python session illustrates that x.self() returns the same
+ Python object on which it is invoked, while y.self() must create a new
+ Python object which refers to the same Y instance.
+
+ handle is a smart pointer
+ to a Python object type; it holds a pointer of type T*, where T
+ is its template parameter. T must be either a type derived from PyObject or a POD
+ type whose initial sizeof(PyObject) bytes are layout-compatible with PyObject. Use handle<> at the boundary between the Python/'C'
+ API and high-level code; prefer object for a generalized interface to Python
+ objects.
+
+
+ In this document, the term "upcast" refers to an operation which
+ converts a pointer Y*
+ to a base class pointerT* via
+ static_cast<T*>
+ if Y is derived from T, or via C-style cast (T*) if
+ it is not. However, in the latter case the "upcast" is ill-formed
+ if the initial sizeof(PyObject)
+ bytes of Y are not layout-compatible
+ with PyObject.
+
+ instance_holder is an abstract
+ base class whose concrete derived classes hold C++ class instances within
+ their Python object wrappers. To allow multiple inheritance in Python from
+ C++ class wrappers, each such Python object contains a chain of instance_holders.
+ When an __init__ function
+ for a wrapped C++ class is invoked, a new instance_holder
+ instance is created and installed in the Python object using its install()
+ function. Each concrete class derived from instance_holder
+ must provide a holds()
+ implementation which allows Boost.Python to query it for the type(s) it
+ is holding. In order to support the held type's wrapped constructor(s),
+ the class must also provide constructors that can accept an initial PyObject*
+ argument referring to the owning Python object, and which forward the rest
+ of their arguments to the constructor of the held type. The initial argument
+ is needed to enable virtual function overriding in Python, and may be ignored,
+ depending on the specific instance_holder
+ subclass.
+
+ <boost/python/pointee.hpp> introduces a traits metafunction templatepointee<T> that can be used to extract the "pointed-to"
+ type from the type of a pointer or smart pointer.
+
+ pointee<T>
+ is used by the class_<...>
+ template to deduce the type being held when a pointer or smart pointer
+ type is used as its HeldType argument.
+
+ Given a 3rd-party smart pointer type smart_pointer<T>, one might partially specialize pointee<smart_pointer<T>> so that it can be used as the HeldType
+ for a class wrapper:
+
+ Python 2.5 introduces a new Py_ssize_t
+ typedef and two related macros (PEP
+ 353). The <boost/python/ssize_t.hpp> header imports these
+ definitions into the boost::python
+ namespace as ssize_t,
+ ssize_t_max, and ssize_t_min. Appropriate definitions
+ are provided for backward compatibility with previous Python versions.
+
+ Imports PY_SSIZE_T_MAX
+ and PY_SSIZE_T_MIN as constants
+ into the boost::python namespace if available, or provides
+ appropriate constants for backward compatibility:
+
+ <boost/python/type_id.hpp> provides types and functions for runtime
+ type identification like those of of <typeinfo>.
+ It exists mostly to work around certain compiler bugs and platform-dependent
+ interactions with shared libraries.
+
+ type_info instances identify
+ a type. As std::type_info is specified to (but unlike
+ its implementation in some compilers), boost::python::type_info
+ never represents top-level references or cv-qualification (see section
+ 5.2.8 in the C++ standard). Unlike std::type_info,
+ boost::python::type_info instances are copyable, and
+ comparisons always work reliably across shared library boundaries.
+
+ constructs a type_info
+ object which identifies the same type as its argument.
+
+
Rationale
+
+ Since it is occasionally necessary to make an array of type_info objects a benign default
+ argument is supplied. Note: this constructor does not correct for
+ non-conformance of compiler typeid() implementations. See type_id, below.
+
+ Writes a description of the type described by to x
+ into s.
+
+
Rationale
+
+ Not every C++ implementation provides a truly human-readable type_info::name()
+ string, but for some we may be able to decode the string and produce
+ a reasonable representation.
+
+
Note
+
+ On some non-conforming C++ implementations, the code is not actually
+ as simple as described above; the semantics are adjusted to work
+ as-if the C++ implementation were conforming.
+
+
+
+
template<classT>type_infotype_id()
+
+
+
+
+
Returns
+
+ type_info(typeid(T))
+
+
Note
+
+ On some non-conforming C++ implementations, the code is not actually
+ as simple as described above; the semantics are adjusted to work
+ as-if the C++ implementation were conforming.
+
+ This is a list of available resources for support with Boost.Python problems
+ and feature requests. Please try to resist emailing the Boost.Python developers
+ directly for support. Use the following resources instead; the developers are
+ listening!
+
+ The Boost.Python
+ mailing list is a forum for discussing Python/C++ interoperability,
+ and Boost.Python in particular. Post your Boost.Python questions here.
+
+ In the past we used Trac, which still hosts a considerable number of
+ open
+ issues. We hope to be able to either close them or migrate
+ them to the new issue tracker.
+
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt
+
+ The Boost Python Library is a framework for interfacing Python and C++. It
+ allows you to quickly and seamlessly expose C++ classes functions and objects
+ to Python, and vice-versa, using no special tools -- just your C++ compiler.
+ It is designed to wrap C++ interfaces non-intrusively, so that you should not
+ have to change the C++ code at all in order to wrap it, making Boost.Python
+ ideal for exposing 3rd-party libraries to Python. The library's use of advanced
+ metaprogramming techniques simplifies its syntax for users, so that wrapping
+ code takes on the look of a kind of declarative interface definition language
+ (IDL).
+
+ By now you should know how to use Boost.Python to call your C++ code from Python.
+ However, sometimes you may need to do the reverse: call Python code from the
+ C++-side. This requires you to embed the Python interpreter
+ into your C++ program.
+
+
+ Currently, Boost.Python does not directly support everything you'll need when
+ embedding. Therefore you'll need to use the Python/C
+ API to fill in the gaps. However, Boost.Python already makes embedding
+ a lot easier and, in a future version, it may become unnecessary to touch the
+ Python/C API at all. So stay tuned...
+
+ To be able to embed python into your programs, you have to link to both Boost.Python's
+ as well as Python's own runtime library.
+
+
+ Boost.Python's library comes in two variants. Both are located in Boost's
+ /libs/python/build/bin-stage subdirectory. On Windows, the
+ variants are called boost_python.lib (for release builds)
+ and boost_python_debug.lib (for debugging). If you can't
+ find the libraries, you probably haven't built Boost.Python yet. See Building and Testing on how to do this.
+
+
+ Python's library can be found in the /libs subdirectory
+ of your Python directory. On Windows it is called pythonXY.lib where X.Y is
+ your major Python version number.
+
+
+ Additionally, Python's /include subdirectory has to be added
+ to your include path.
+
+
+ In a Jamfile, all the above boils down to:
+
+
projectroot c:\projects\embedded_program ; # location of the program
+
+# bring in the rules for python
+SEARCH on python.jam = $(BOOST_BUILD_PATH) ;
+include python.jam ;
+
+exe embedded_program # name of the executable
+ : #sources
+ embedded_program.cpp
+ : # requirements
+ <find-library>boost_python <library-path>c:\boost\libs\python
+ $(PYTHON_PROPERTIES)
+ <library-path>$(PYTHON_LIB_PATH)
+ <find-library>$(PYTHON_EMBEDDED_LIBRARY) ;
+
+ Being able to build is nice, but there is nothing to build yet. Embedding the
+ Python interpreter into one of your C++ programs requires these 4 steps:
+
+
+
+ #include <boost/python.hpp>
+
+
+ Call Py_Initialize()
+ to start the interpreter and create the __main__ module.
+
+
+ Call other Python C API routines to use the interpreter.
+
+
+
+
+
+
Note
+
+
+ Note that at this time you must not call Py_Finalize()
+ to stop the interpreter. This may be fixed in a future version of boost.python.
+
+
+
+ (Of course, there can be other C++ code between all of these steps.)
+
+
+ Now that we can embed the interpreter in
+ our programs, lets see how to put it to use...
+
+ As you probably already know, objects in Python are reference-counted. Naturally,
+ the PyObjects of the Python C API are also reference-counted.
+ There is a difference however. While the reference-counting is fully automatic
+ in Python, the Python C API requires you to do it by
+ hand. This is messy and especially hard to get right in the presence
+ of C++ exceptions. Fortunately Boost.Python provides the handle
+ and object
+ class templates to automate the process.
+
+ eval evaluates the given expression and returns the resulting value. exec
+ executes the given code (typically a set of statements) returning the result,
+ and exec_file executes the code contained in the given file.
+
+
+ The globals and locals parameters are
+ Python dictionaries containing the globals and locals of the context in which
+ to run the code. For most intents and purposes you can use the namespace
+ dictionary of the __main__ module for both parameters.
+
+
+ Boost.python provides a function to import a module:
+
+
objectimport(strname)
+
+
+ import imports a python module (potentially loading it into the running process
+ first), and returns it.
+
+
+ Let's import the __main__ module and run some Python code
+ in its namespace:
+
+ Often we'd like to have a class to manipulate Python objects. But we have
+ already seen such a class above, and in the previous
+ section: the aptly named object class and its derivatives.
+ We've already seen that they can be constructed from a handle.
+ The following examples should further illustrate this fact:
+
+ Here we create a dictionary object for the __main__ module's
+ namespace. Then we assign 5 squared to the result variable and read this
+ variable from the dictionary. Another way to achieve the same result is to
+ use eval instead, which returns the result directly:
+
+ If an exception occurs in the evaluation of the python expression, error_already_set
+ is thrown:
+
+
try
+{
+ objectresult=eval("5/0");
+ // execution will never get here:
+ intfive_divided_by_zero=extract<int>(result);
+}
+catch(error_already_setconst&)
+{
+ // handle the exception in some way
+}
+
+
+ The error_already_set exception class doesn't carry any
+ information in itself. To find out more about the Python exception that occurred,
+ you need to use the exception
+ handling functions of the Python C API in your catch-statement. This
+ can be as simple as calling PyErr_Print()
+ to print the exception's traceback to the console, or comparing the type
+ of the exception with those of the standard
+ exceptions:
+
+ All C++ exceptions must be caught at the boundary with Python code. This boundary
+ is the point where C++ meets Python. Boost.Python provides a default exception
+ handler that translates selected standard exceptions, then gives up:
+
+
raiseRuntimeError,'unidentifiable C++ Exception'
+
+
+ Users may provide custom translation. Here's an example:
+
+ Here, we wrote a C++ class wrapper that exposes the member functions greet
+ and set. Now, after building our module as a shared library,
+ we may use our class World in Python. Here's a sample Python
+ session:
+
+ Our previous example didn't have any explicit constructors. Since World
+ is declared as a plain struct, it has an implicit default constructor. Boost.Python
+ exposes the default constructor by default, which is why we were able to
+ write
+
+
>>>planet=hello.World()
+
+
+ We may wish to wrap a class with a non-default constructor. Let us build
+ on our previous example:
+
+ This time World has no default constructor; our previous
+ wrapping code would fail to compile when the library tried to expose it.
+ We have to tell class_<World> about the constructor
+ we want to expose instead.
+
+ init<std::string>() exposes the constructor taking
+ in a std::string (in Python, constructors are spelled
+ ""__init__"").
+
+
+ We can expose additional constructors by passing more init<...>s
+ to the def() member function. Say for example we have
+ another World constructor taking in two doubles:
+
+ Data members may also be exposed to Python so that they can be accessed as
+ attributes of the corresponding Python class. Each data member that we wish
+ to be exposed may be regarded as read-only
+ or read-write. Consider this class Var:
+
+ In C++, classes with public data members are usually frowned upon. Well designed
+ classes that take advantage of encapsulation hide the class' data members.
+ The only way to access the class' data is through access (getter/setter)
+ functions. Access functions expose class properties. Here's an example:
+
+ However, in Python attribute access is fine; it doesn't neccessarily break
+ encapsulation to let users handle attributes directly, because the attributes
+ can just be a different syntax for a method call. Wrapping our Num
+ class using Boost.Python:
+
+ In the previous examples, we dealt with classes that are not polymorphic.
+ This is not often the case. Much of the time, we will be wrapping polymorphic
+ classes and class hierarchies related by inheritance. We will often have
+ to write Boost.Python wrappers for classes that are derived from abstract
+ base classes.
+
+ Derived automatically inherits all of Base's Python methods (wrapped
+ C++ member functions)
+
+
+ If Base is polymorphic, Derived
+ objects which have been passed to Python via a pointer or reference to
+ Base can be passed where a pointer or reference to
+ Derived is expected.
+
+
+
+ Now, we will expose the C++ free functions b and d
+ and factory:
+
+ Note that free function factory is being used to generate
+ new instances of class Derived. In such cases, we use
+ return_value_policy<manage_new_object> to instruct
+ Python to adopt the pointer to Base and hold the instance
+ in a new Python Base object until the the Python object
+ is destroyed. We will see more of Boost.Python call
+ policies later.
+
+
// Tell Python to take ownership of factory's result
+def("factory",factory,
+ return_value_policy<manage_new_object>());
+
+ In this section, we will learn how to make functions behave polymorphically
+ through virtual functions. Continuing our example, let us add a virtual function
+ to our Base class:
+
+ One of the goals of Boost.Python is to be minimally intrusive on an existing
+ C++ design. In principle, it should be possible to expose the interface for
+ a 3rd party library without changing it. It is not ideal to add anything
+ to our class Base. Yet, when
+ you have a virtual function that's going to be overridden in Python and called
+ polymorphically from C++, we'll need to
+ add some scaffoldings to make things work properly. What we'll do is write
+ a class wrapper that derives from Base
+ that will unintrusively hook into the virtual functions so that a Python
+ override may be called:
+
+ Notice too that in addition to inheriting from Base,
+ we also multiply- inherited wrapper<Base> (See Wrapper).
+ The wrapper template makes
+ the job of wrapping classes that are meant to overridden in Python, easier.
+
+
+
+
+
+ MSVC6/7 Workaround
+
+
+ If you are using Microsoft Visual C++ 6 or 7, you have to write f as:
+
+ We've seen in the previous section how classes with pure virtual functions
+ are wrapped using Boost.Python's class
+ wrapper facilities. If we wish to wrap non-pure-virtual
+ functions instead, the mechanism is a bit different.
+
+
+ Recall that in the previous
+ section, we wrapped a class with a pure virtual function that we then
+ implemented in C++, or Python classes derived from it. Our base class:
+
+
structBase
+{
+ virtualintf()=0;
+};
+
+
+ had a pure virtual function f. If, however, its member
+ function f was not declared as pure virtual:
+
+ Take note that we expose both &Base::f and &BaseWrap::default_f. Boost.Python needs to keep track
+ of 1) the dispatch function f and 2) the forwarding function
+ to its default implementation default_f. There's a special
+ def function for this purpose.
+
+ C is well known for the abundance of operators. C++ extends this to the extremes
+ by allowing operator overloading. Boost.Python takes advantage of this and
+ makes it easy to wrap C++ operator-powered classes.
+
+
+ Consider a file position class FilePos and a set of operators
+ that take on FilePos instances:
+
+ The code snippet above is very clear and needs almost no explanation at all.
+ It is virtually the same as the operators' signatures. Just take note that
+ self refers to FilePos object. Also, not every class
+ T that you might need to interact with in an operator
+ expression is (cheaply) default-constructible. You can use other<T>()
+ in place of an actual T instance when writing "self
+ expressions".
+
+ Python has a few more Special Methods. Boost.Python
+ supports all of the standard special method names supported by real Python
+ class instances. A similar set of intuitive interfaces can also be used to
+ wrap C++ functions that correspond to these Python special functions.
+ Example:
+
+ What is the business of operator<<? Well, the method str requires the operator<< to do its work (i.e. operator<<
+ is used by the method defined by def(str(self)).
+
+ In this chapter, we'll look at Boost.Python powered functions in closer detail.
+ We will see some facilities to make exposing C++ functions to Python safe from
+ potential pifalls such as dangling pointers and references. We will also see
+ facilities that will make it even easier for us to expose C++ functions that
+ take advantage of C++ features such as overloading and default arguments.
+
+
+ Read on...
+
+
+ But before you do, you might want to fire up Python 2.2 or later and type
+ >>> import this.
+
+
>>> import this
+The Zen of Python, by Tim Peters
+Beautiful is better than ugly.
+Explicit is better than implicit.
+Simple is better than complex.
+Complex is better than complicated.
+Flat is better than nested.
+Sparse is better than dense.
+Readability counts.
+Special cases aren't special enough to break the rules.
+Although practicality beats purity.
+Errors should never pass silently.
+Unless explicitly silenced.
+In the face of ambiguity, refuse the temptation to guess.
+There should be one-- and preferably only one --obvious way to do it
+Although that way may not be obvious at first unless you're Dutch.
+Now is better than never.
+Although never is often better than right now.
+If the implementation is hard to explain, it's a bad idea.
+If the implementation is easy to explain, it may be a good idea.
+Namespaces are one honking great idea -- let's do more of those!
+
+ In C++, we often deal with arguments and return types such as pointers and
+ references. Such primitive types are rather, ummmm, low level and they really
+ don't tell us much. At the very least, we don't know the owner of the pointer
+ or the referenced object. No wonder languages such as Java and Python never
+ deal with such low level entities. In C++, it's usually considered a good
+ practice to use smart pointers which exactly describe ownership semantics.
+ Still, even good C++ interfaces use raw references and pointers sometimes,
+ so Boost.Python must deal with them. To do this, it may need your help. Consider
+ the following C++ function:
+
+
X&f(Y&y,Z*z);
+
+
+ How should the library wrap this function? A naive approach builds a Python
+ X object around result reference. This strategy might or might not work out.
+ Here's an example where it didn't
+
+ Well, what if f() was implemented as shown below:
+
+
X&f(Y&y,Z*z)
+{
+ y.z=z;
+ returny.x;
+}
+
+
+ The problem is that the lifetime of result X& is tied to the lifetime
+ of y, because the f() returns a reference to a member of the y object. This
+ idiom is is not uncommon and perfectly acceptable in the context of C++.
+ However, Python users should not be able to crash the system just by using
+ our C++ interface. In this case deleting y will invalidate the reference
+ to X. We have a dangling reference.
+
+
+ Here's what's happening:
+
+
+
+ f is called passing in a reference to y
+ and a pointer to z
+
+
+ A reference to y.x is returned
+
+
+ y is deleted. x is a dangling reference
+
+
+ x.some_method() is called
+
+
+ BOOM!
+
+
+
+ We could copy result into a new object:
+
+
>>>f(y,z).set(42)# Result disappears
+>>>y.x.get()# No crash, but still bad
+3.14
+
+
+ This is not really our intent of our C++ interface. We've broken our promise
+ that the Python interface should reflect the C++ interface as closely as
+ possible.
+
+
+ Our problems do not end there. Suppose Y is implemented as follows:
+
+ Call Policies may be used in situations such as the example detailed above.
+ In our example, return_internal_reference and with_custodian_and_ward
+ are our friends:
+
+ Informs Boost.Python that the first argument, in our case Y&
+ y, is the owner of the returned reference: X&.
+ The "1" simply specifies the first argument.
+ In short: "return an internal reference X& owned
+ by the 1st argument Y& y".
+
+
with_custodian_and_ward<1,2>
+
+
+ Informs Boost.Python that the lifetime of the argument indicated by ward
+ (i.e. the 2nd argument: Z* z) is dependent on the lifetime
+ of the argument indicated by custodian (i.e. the 1st argument: Y&
+ y).
+
+
+ It is also important to note that we have defined two policies above. Two
+ or more policies can be composed by chaining. Here's the general syntax:
+
+ The following illustrates a scheme for manually wrapping an overloaded member
+ functions. Of course, the same technique can be applied to wrapping overloaded
+ non-member functions.
+
+ Boost.Python wraps (member) function pointers. Unfortunately, C++ function
+ pointers carry no default argument info. Take a function f
+ with default arguments:
+
+
intf(int,double=3.14,charconst*="hello");
+
+
+ But the type of a pointer to the function f has no information
+ about its default arguments:
+
+ will automatically create the thin wrappers for us. This macro will create
+ a class foo_overloads that can be passed on to def(...).
+ The third and fourth macro argument are the minimum arguments and maximum
+ arguments, respectively. In our foo function the minimum
+ number of arguments is 1 and the maximum number of arguments is 4. The def(...)
+ function will automatically add all the foo variants for us:
+
+ Objects here, objects there, objects here there everywhere. More frequently
+ than anything else, we need to expose member functions of our classes to
+ Python. Then again, we have the same inconveniences as before when default
+ arguments or overloads with a common sequence of initial arguments come into
+ play. Another macro is provided to make this a breeze.
+
+
+ Like BOOST_PYTHON_FUNCTION_OVERLOADS, BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS
+ may be used to automatically create the thin wrappers for wrapping member
+ functions. Let's have an example:
+
+ will generate a set of thin wrappers for george's wack_em
+ member function accepting a minimum of 1 and a maximum of 3 arguments (i.e.
+ the third and fourth macro argument). The thin wrappers are all enclosed
+ in a class named george_overloads that can then be used
+ as an argument to def(...):
+
+ A similar facility is provided for class constructors, again, with default
+ arguments or a sequence of overloads. Remember init<...>?
+ For example, given a class X with a constructor:
+
+ It was mentioned in passing in the previous section that BOOST_PYTHON_FUNCTION_OVERLOADS
+ and BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS can also be
+ used for overloaded functions and member functions with a common sequence
+ of initial arguments. Here is an example:
+
+ It is important to emphasize however that the overloaded
+ functions must have a common sequence of initial arguments. Otherwise,
+ our scheme above will not work. If this is not the case, we have to wrap
+ our functions manually.
+
+
+ Actually, we can mix and match manual wrapping of overloaded functions and
+ automatic wrapping through BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS
+ and its sister, BOOST_PYTHON_FUNCTION_OVERLOADS. Following
+ up on our example presented in the section on
+ overloading, since the first 4 overload functins have a common sequence
+ of initial arguments, we can use BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS
+ to automatically wrap the first three of the defs and
+ manually wrap just the last. Here's how we'll do this:
+
+ Now the first thing you'd want to do is to build the Hello World module and
+ try it for yourself in Python. In this section, we will outline the steps necessary
+ to achieve that. We will use the build tool that comes bundled with every boost
+ distribution: bjam.
+
+
+
+
+
Note
+
+
+
+ Building without bjam
+
+
+ Besides bjam, there are of course other ways to get your module built. What's
+ written here should not be taken as "the one and only way". There
+ are of course other build tools apart from bjam.
+
+
+ Take note however that the preferred build tool for Boost.Python is bjam.
+ There are so many ways to set up the build incorrectly. Experience shows
+ that 90% of the "I can't build Boost.Python" problems come from
+ people who had to use a different tool.
+
+
+
+
+ We will skip over the details. Our objective will be to simply create the hello
+ world module and run it in Python. For a complete reference to building Boost.Python,
+ check out: building.html. After
+ this brief bjam tutorial, we should have built the DLLs
+ and run a python program using the extension.
+
+
+ The tutorial example can be found in the directory: libs/python/example/tutorial.
+ There, you can find:
+
+
+
+ hello.cpp
+
+
+ hello.py
+
+
+ Jamroot
+
+
+
+ The hello.cpp file is our C++ hello world example. The
+ Jamroot is a minimalist bjam script
+ that builds the DLLs for us. Finally, hello.py is our Python
+ program that uses the extension in hello.cpp.
+
+
+ Before anything else, you should have the bjam executable in your boost directory
+ or somewhere in your path such that bjam can be executed
+ in the command line. Pre-built Boost.Jam executables are available for most
+ platforms. The complete list of Bjam executables can be found here.
+
+ bjam is run using your operating system's command line
+ interpreter.
+
+
+ Start it up.
+
+
+ A file called user-config.jam in your home directory is used to configure your
+ tools. In Windows, your home directory can be found by typing:
+
+
ECHO %HOMEDRIVE%%HOMEPATH%
+
+
+ into a command prompt window. Your file should at least have the rules for
+ your compiler and your python installation. A specific example of this on Windows
+ would be:
+
+ The first rule tells Bjam to use the MSVC 8.0 compiler and associated tools.
+ The second rule provides information on Python, its version and where it is
+ located. The above assumes that the Python installation is in C:dev/tools\/Python.
+ If you have one fairly "standard" python installation for your platform,
+ you might not need to do this.
+
+
+ Now we are ready... Be sure to cd to libs/python/example/tutorial
+ where the tutorial "hello.cpp" and the "Jamroot"
+ is situated.
+
+ In C++, and STL in particular, we see iterators everywhere. Python also has
+ iterators, but these are two very different beasts.
+
+
+ C++ iterators:
+
+
+
+ C++ has 5 type categories (random-access, bidirectional, forward, input,
+ output)
+
+
+ There are 2 Operation categories: reposition, access
+
+
+ A pair of iterators is needed to represent a (first/last) range.
+
+
+
+ Python Iterators:
+
+
+
+ 1 category (forward)
+
+
+ 1 operation category (next())
+
+
+ Raises StopIteration exception at end
+
+
+
+ The typical Python iteration protocol: for y
+ in x... is as follows:
+
+
iter=x.__iter__()# get iterator
+try:
+ while1:
+ y=iter.next()# get each item
+ ...# process y
+exceptStopIteration:pass# iterator exhausted
+
+
+ Boost.Python provides some mechanisms to make C++ iterators play along nicely
+ as Python iterators. What we need to do is to produce appropriate __iter__ function from C++ iterators that
+ is compatible with the Python iteration protocol. For example:
+
+ So far, we have seen how to expose C++ iterators and ranges to Python. Sometimes
+ we wish to go the other way, though: we'd like to pass a Python sequence to
+ an STL algorithm or use it to initialize an STL container. We need to make
+ a Python iterator look like an STL iterator. For that, we use stl_input_iterator<>.
+ Consider how we might implement a function that exposes std::list<int>::assign() to Python:
+
+
template<typenameT>
+voidlist_assign(std::list<T>&l,objecto){
+ // Turn a Python sequence into an STL input range
+ stl_input_iterator<T>begin(o),end;
+ l.assign(begin,end);
+}
+
+// Part of the wrapper for list<int>
+class_<std::list<int>>("list_int")
+ .def("assign",&list_assign<int>)
+ // ...
+ ;
+
+
+ Now in Python, we can assign any integer sequence to list_int
+ objects:
+
+ Python is dynamically typed, unlike C++ which is statically typed. Python variables
+ may hold an integer, a float, list, dict, tuple, str, long etc., among other
+ things. In the viewpoint of Boost.Python and C++, these Pythonic variables
+ are just instances of class object. We will see in this
+ chapter how to deal with Python objects.
+
+
+ As mentioned, one of the goals of Boost.Python is to provide a bidirectional
+ mapping between C++ and Python while maintaining the Python feel. Boost.Python
+ C++ objects are as close as possible to Python. This should
+ minimize the learning curve significantly.
+
+ Class object wraps PyObject*. All the
+ intricacies of dealing with PyObjects such as managing
+ reference counting are handled by the object class. C++
+ object interoperability is seamless. Boost.Python C++ objects
+ can in fact be explicitly constructed from any C++ object.
+
+ Apart from cosmetic differences due to the fact that we are writing the code
+ in C++, the look and feel should be immediately apparent to the Python coder.
+
+ Boost.Python comes with a set of derived object types
+ corresponding to that of Python's:
+
+
+
+ list
+
+
+ dict
+
+
+ tuple
+
+
+ str
+
+
+ long_
+
+
+ enum
+
+
+
+ These derived object types act like real Python types.
+ For instance:
+
+
str(1)==>"1"
+
+
+ Wherever appropriate, a particular derived object has
+ corresponding Python type's methods. For instance, dict
+ has a keys() method:
+
+
d.keys()
+
+
+ make_tuple is provided for declaring tuple literals.
+ Example:
+
+
make_tuple(123,'D',"Hello, World",0.0);
+
+
+ In C++, when Boost.Python objects are used as arguments
+ to functions, subtype matching is required. For example, when a function
+ f, as declared below, is wrapped, it will only accept
+ instances of Python's str type and subtypes.
+
+
voidf(strname)
+{
+ objectn2=name.attr("upper")();// NAME = name.upper()
+ strNAME=name.upper();// better
+ objectmsg="%s is bigger than %s"%make_tuple(NAME,name);
+}
+
+
+ In finer detail:
+
+
strNAME=name.upper();
+
+
+ Illustrates that we provide versions of the str type's methods as C++ member
+ functions.
+
+
objectmsg="%s is bigger than %s"%make_tuple(NAME,name);
+
+
+ Demonstrates that you can write the C++ equivalent of "format"
+ % x,y,z in Python, which is useful since there's no easy way to
+ do that in std C++.
+
+
+
+
+
+ Beware the common pitfall of forgetting
+ that the constructors of most of Python's mutable types make copies, just
+ as in Python.
+
+
+
+ Python:
+
+
>>>d=dict(x.__dict__)# copies x.__dict__
+>>>d['whatever']=3# modifies the copy
+
+
+ C++:
+
+
dictd(x.attr("__dict__"));// copies x.__dict__
+d['whatever']=3;// modifies the copy
+
+ Due to the dynamic nature of Boost.Python objects, any class_<T>
+ may also be one of these types! The following code snippet wraps the class
+ (type) object.
+
+
+ We can use this to create wrapped instances. Example:
+
+ At some point, we will need to get C++ values out of object instances. This
+ can be achieved with the extract<T> function. Consider
+ the following:
+
+
doublex=o.attr("length");// compile error
+
+
+ In the code above, we got a compiler error because Boost.Python object
+ can't be implicitly converted to doubles. Instead, what
+ we wanted to do above can be achieved by writing:
+
+ The first line attempts to extract the "length" attribute of the
+ Boost.Python object. The second line attempts to extract
+ the Vec2 object from held by the Boost.Python object.
+
+
+ Take note that we said "attempt to" above. What if the Boost.Python
+ object does not really hold a Vec2
+ type? This is certainly a possibility considering the dynamic nature of Python
+ objects. To be on the safe side, if the C++ type can't
+ be extracted, an appropriate exception is thrown. To avoid an exception,
+ we need to test for extractibility:
+
+ Boost.Python has a nifty facility to capture and wrap C++ enums. While Python
+ has no enum type, we'll often want to expose our C++ enums
+ to Python as an int. Boost.Python's enum facility makes
+ this easy while taking care of the proper conversions from Python's dynamic
+ typing to C++'s strong static typing (in C++, ints cannot be implicitly converted
+ to enums). To illustrate, given a C++ enum:
+
+ can be used to expose to Python. The new enum type is created in the current
+ scope(), which is usually the current module. The snippet
+ above creates a Python class derived from Python's int
+ type which is associated with the C++ type passed as its first parameter.
+
+
+
+
+
Note
+
+
+
+ what is a scope?
+
+
+ The scope is a class that has an associated global Python object which
+ controls the Python namespace in which new extension classes and wrapped
+ functions will be defined as attributes. Details can be found here.
+
+
+
+
+ You can access those values in Python as
+
+
>>>my_module.choice.red
+my_module.choice.red
+
+
+ where my_module is the module where the enum is declared. You can also create
+ a new scope around a class:
+
+ A Python package is a collection of modules that provide to the user a certain
+ functionality. If you're not familiar on how to create packages, a good introduction
+ to them is provided in the Python
+ Tutorial.
+
+
+ But we are wrapping C++ code, using Boost.Python. How can we provide a nice
+ package interface to our users? To better explain some concepts, let's work
+ with an example.
+
+
+ We have a C++ library that works with sounds: reading and writing various
+ formats, applying filters to the sound data, etc. It is named (conveniently)
+ sounds. Our library already has a neat C++ namespace hierarchy,
+ like so:
+
+
sounds::core
+sounds::io
+sounds::filters
+
+
+ We would like to present this same hierarchy to the Python user, allowing
+ him to write code like this:
+
+
importsounds.filters
+sounds.filters.echo(...)# echo is a C++ function
+
+
+ The first step is to write the wrapping code. We have to export each module
+ separately with Boost.Python, like this:
+
+ Compiling these files will generate the following Python extensions: core.pyd,
+ io.pyd and filters.pyd.
+
+
+
+
+
Note
+
+
+ The extension .pyd is used for python extension modules,
+ which are just shared libraries. Using the default for your system, like
+ .so for Unix and .dll for Windows,
+ works just as well.
+
+
+
+ Now, we create this directory structure for our Python package:
+
+ The file __init__.py is what tells Python that the directory
+ sounds/ is actually a Python package. It can be a empty
+ file, but can also perform some magic, that will be shown later.
+
+
+ Now our package is ready. All the user has to do is put sounds
+ into his PYTHONPATH
+ and fire up the interpreter:
+
+ This is the simplest way to create hierarchies of packages, but it is not
+ very flexible. What if we want to add a pure Python
+ function to the filters package, for instance, one that applies 3 filters
+ in a sound object at once? Sure, you can do this in C++ and export it, but
+ why not do so in Python? You don't have to recompile the extension modules,
+ plus it will be easier to write it.
+
+
+ If we want this flexibility, we will have to complicate our package hierarchy
+ a little. First, we will have to change the name of the extension modules:
+
+
/* file core.cpp */
+BOOST_PYTHON_MODULE(_core)
+{
+ ...
+ /* export everything in the sounds::core namespace */
+}
+
+
+ Note that we added an underscore to the module name. The filename will have
+ to be changed to _core.pyd as well, and we do the same
+ to the other extension modules. Now, we change our package hierarchy like
+ so:
+
+ Note that we created a directory for each extension module, and added a __init__.py
+ to each one. But if we leave it that way, the user will have to access the
+ functions in the core module with this syntax:
+
+ which is not what we want. But here enters the __init__.py
+ magic: everything that is brought to the __init__.py namespace
+ can be accessed directly by the user. So, all we have to do is bring the
+ entire namespace from _core.pyd to core/__init__.py.
+ So add this line of code to sounds/core/__init__.py:
+
+
from_coreimport*
+
+
+ We do the same for the other packages. Now the user accesses the functions
+ and classes in the extension modules like before:
+
+ with the additional benefit that we can easily add pure Python functions
+ to any module, in a way that the user can't tell the difference between a
+ C++ function and a Python function. Let's add a pure
+ Python function, echo_noise, to the filters
+ package. This function applies both the echo and noise
+ filters in sequence in the given sound object. We create
+ a file named sounds/filters/echo_noise.py and code our
+ function:
+
+ Thanks to Python's flexibility, you can easily add new methods to a class,
+ even after it was already created:
+
+
>>>classC(object):pass
+>>>
+>>># a regular function
+>>>defC_str(self):return'A C instance!'
+>>>
+>>># now we turn it in a member function
+>>>C.__str__=C_str
+>>>
+>>>c=C()
+>>>printc
+ACinstance!
+>>>C_str(c)
+ACinstance!
+
+
+ Yes, Python rox.
+
+
+ We can do the same with classes that were wrapped with Boost.Python. Suppose
+ we have a class point in C++:
+
+ If we are using the technique from the previous session, Creating
+ Packages, we can code directly into geom/__init__.py:
+
+
from_geomimport*
+
+# a regular function
+defpoint_str(self):
+ returnstr((self.x,self.y))
+
+# now we turn it into a member function
+point.__str__=point_str
+
+
+ All point instances created from C++ will
+ also have this member function! This technique has several advantages:
+
+
+
+ Cut down compile times to zero for these additional functions
+
+
+ Reduce the memory footprint to virtually zero
+
+
+ Minimize the need to recompile
+
+
+ Rapid prototyping (you can move the code to C++ if required without changing
+ the interface)
+
+
+
+ You can even add a little syntactic sugar with the use of metaclasses. Let's
+ create a special metaclass that "injects" methods in other classes.
+
+
# The one Boost.Python uses for all wrapped classes.
+# You can use here any class exported by Boost instead of "point"
+BoostPythonMetaclass=point.__class__
+
+classinjector(object):
+ class__metaclass__(BoostPythonMetaclass):
+ def__init__(self,name,bases,dict):
+ forbinbases:
+ iftype(b)notin(self,type):
+ fork,vindict.items():
+ setattr(b,k,v)
+ returntype.__init__(self,name,bases,dict)
+
+# inject some methods in the point foo
+classmore_point(injector,point):
+ def__repr__(self):
+ return'Point(x=%s, y=%s)'%(self.x,self.y)
+ deffoo(self):
+ print'foo!'
+
+ In this simple case there is not much gained, but for constructurs with many
+ overloads and/or arguments this is often a great simplification, again with
+ virtually zero memory footprint and zero compile-time overhead for the keyword
+ support.
+
+ If you have ever exported a lot of classes, you know that it takes quite
+ a good time to compile the Boost.Python wrappers. Plus the memory consumption
+ can easily become too high. If this is causing you problems, you can split
+ the class_ definitions in multiple files:
+
+ This method is recommended too if you are developing the C++ library and
+ exporting it to Python at the same time: changes in a class will only demand
+ the compilation of a single cpp, instead of the entire wrapper code.
+
+
+
+
+
Note
+
+
+ This method is useful too if you are getting the error message "fatal
+ error C1204:Compiler limit:internal structure overflow"
+ when compiling a large source file, as explained in the FAQ.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/develop/doc/index.html b/develop/doc/index.html
new file mode 100644
index 00000000..d5225757
--- /dev/null
+++ b/develop/doc/index.html
@@ -0,0 +1,13 @@
+
+
+
+
+
+
+ Automatic redirection failed, click this
+ link
+
+
![[Note]](../images/note.png)
![[Note]](../../images/note.png)
![[Note]](images/note.png)
