boost/python
2
0
Fork 0
mirror of https://github.com/boostorg/python.git synced 2026-01-19 16:32:16 +00:00
Code Issues Projects Releases Wiki Activity

This commit was manufactured by cvs2svn to create tag

Browse Source 
'RC_1_29_0_last_merge'.

[SVN r16498]
This commit is contained in:
nobody
2002-12-03 21:38:20 +00:00
parent dae2e27a32
commit e59a0aef06
23 changed files with 6579 additions and 377 deletions
Download Patch File Download Diff File Expand all files Collapse all files

231
doc/comparisons.html Normal file
View File

@@ -0,0 +1,231 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN"
"http://www.w3.org/TR/REC-html40/strict.dtd">
<title>
Comparisons with Other Systems
</title>
<div>
<h1>
<img width="277" height="86" id="_x0000_i1025" align="center"
src="../../../c++boost.gif" alt= "c++boost.gif (8819 bytes)"><br>
Comparisons with
Other Systems
</h1>
<h2>CXX</h2>
<p>
Like Boost.Python, <a href="http://cxx.sourceforge.net/">CXX</a> attempts to
provide a C++-oriented interface to Python. In most cases, as with the
boost library, it relieves the user from worrying about
reference-counts. Both libraries automatically convert thrown C++
exceptions into Python exceptions. As far as I can tell, CXX has no
support for subclassing C++ extension types in Python. An even
more significant difference is that a user's C++ code is still basically
``dealing with Python objects'', though they are wrapped in
C++ classes. This means such jobs as argument parsing and conversion are
still left to be done explicitly by the user.
<p>
CXX claims to interoperate well with the C++ Standard Library
(a.k.a. STL) by providing iterators into Python Lists and Dictionaries,
but the claim is unfortunately unsupportable. The problem is that in
general, access to Python sequence and mapping elements through
iterators requires the use of proxy objects as the return value of
iterator dereference operations. This usage conflicts with the basic
ForwardIterator requirements in <a
href="http://anubis.dkuug.dk/jtc1/sc22/open/n2356/lib-iterators.html#lib.forward.iterators">
section 24.1.3 of the standard</a> (dereferencing must produce a
reference). Although you may be able to use these iterators with some
operations in some standard library implementations, it is neither
guaranteed to work nor portable.
<p>
As far as I can tell, CXX enables one to write what is essentially
idiomatic Python code in C++, manipulating Python objects through the
same fully-generic interfaces we use in Python. While you're hardly
programming directly to the ``bare metal'' with CXX, it basically
presents a ``C++-ized'' version of the Python 'C' API. Some fraction of
that capability is available in Boost.Python through <tt><a
href="../../../boost/python/objects.hpp">boost/python/objects.hpp</a></tt>,
which provides C++ objects corresponding to Python lists, tuples,
strings, and dictionaries, and through <tt><a
href="../../../boost/python/callback.hpp">boost/python/callback.hpp</a></tt>,
which allows you to call back into python with C++ arguments.
<p>
<a href="mailto:dubois1@llnl.gov">Paul F. Dubois</a>, the original
author of CXX, has told me that what I've described is only half of the
picture with CXX, but I never understood his explanation well-enough to
fill in the other half. Here is his response to the commentary above:
<blockquote>
``My intention with CXX was not to do what you are doing. It was to enable a
person to write an extension directly in C++ rather than C. I figured others had
the wrapping business covered. I thought maybe CXX would provide an easier
target language for those making wrappers, but I never explored
that.''<br><i>-<a href="mailto:dubois1@llnl.gov">Paul Dubois</a></i>
</blockquote>
<h2>SWIG</h2>
<p>
<a href= "http://www.swig.org/">SWIG</a> is an impressively mature tool
for exporting an existing ANSI 'C' interface into various scripting
languages. Swig relies on a parser to read your source code and produce
additional source code files which can be compiled into a Python (or
Perl or Tcl) extension module. It has been successfully used to create
many Python extension modules. Like Boost.Python, SWIG is trying to allow an
existing interface to be wrapped with little or no change to the
existing code. The documentation says ``SWIG parses a form of ANSI C
syntax that has been extended with a number of special directives. As a
result, interfaces are usually built by grabbing a header file and
tweaking it a little bit.'' For C++ interfaces, the tweaking has often
proven to amount to more than just a little bit. One user
writes:
<blockquote> ``The problem with swig (when I used it) is that it
couldnt handle templates, didnt do func overloading properly etc. For
ANSI C libraries this was fine. But for usual C++ code this was a
problem. Simple things work. But for anything very complicated (or
realistic), one had to write code by hand. I believe Boost.Python doesn't have
this problem[<a href="#sic">sic</a>]... IMHO overloaded functions are very important to
wrap correctly.''<br><i>-Prabhu Ramachandran</i>
</blockquote>
<p>
By contrast, Boost.Python doesn't attempt to parse C++ - the problem is simply
too complex to do correctly. <a name="sic">Technically</a>, one does
write code by hand to use Boost.Python. The goal, however, has been to make
that code nearly as simple as listing the names of the classes and
member functions you want to expose in Python.
<h2>SIP</h2>
<p>
<a
href="http://www.thekompany.com/projects/pykde/background.php3?dhtml_ok=1">SIP</a>
is a system similar to SWIG, though seemingly more
C++-oriented. The author says that like Boost.Python, SIP supports overriding
extension class member functions in Python subclasses. It appears to
have been designed specifically to directly support some features of
PyQt/PyKDE, which is its primary client. Documentation is almost
entirely missing at the time of this writing, so a detailed comparison
is difficult.
<h2>ILU</h2>
<p>
<a
href="ftp://ftp.parc.xerox.com/pub/ilu/ilu.html">ILU</a>
is a very ambitious project which tries to describe a module's interface
(types and functions) in terms of an <a
href="ftp://ftp.parc.xerox.com/pub/ilu/2.0b1/manual-html/manual_2.html">Interface
Specification Language</a> (ISL) so that it can be uniformly interfaced
to a wide range of computer languages, including Common Lisp, C++, C,
Modula-3, and Python. ILU can parse the ISL to generate a C++ language
header file describing the interface, of which the user is expected to
provide an implementation. Unlike Boost.Python, this means that the system
imposes implementation details on your C++ code at the deepest level. It
is worth noting that some of the C++ names generated by ILU are supposed
to be reserved to the C++ implementation. It is unclear from the
documentation whether ILU supports overriding C++ virtual functions in Python.
<h2>GRAD</h2>
<p>
<a
href="http://www.python.org/workshops/1996-11/papers/GRAD/html/GRADcover.html">GRAD</a>
is another very ambitious project aimed at generating Python wrappers for
interfaces written in ``legacy languages'', among which C++ is the first one
implemented. Like SWIG, it aims to parse source code and automatically
generate wrappers, though it appears to take a more sophisticated approach
to parsing in general and C++ in particular, so it should do a much better
job with C++. It appears to support function overloading. The
documentation is missing a lot of information I'd like to see, so it is
difficult to give an accurate and fair assessment. I am left with the
following questions:
<ul>
<li>Does it support overriding of virtual functions?
<li>What about overriding private or protected virtual functions (the documentation indicates
that only public interfaces are supported)?
<li>Which C++ language constructs are supportd?
<li>Does it support implicit conversions between wrapped C++ classes that have
an inheritance relationship?
<li>Does it support smart pointers?
</ul>
<p>
Anyone in the possession of the answers to these questions will earn my
gratitude for a write-up <code>;-)</code>
<h2>Zope ExtensionClasses</h2>
<p>
<a href="http:http://www.digicool.com/releases/ExtensionClass">
ExtensionClasses in Zope</a> use the same underlying mechanism as Boost.Python
to support subclassing of extension types in Python, including
multiple-inheritance. Both systems support pickling/unpickling of
extension class instances in very similar ways. Both systems rely on the
same ``<a
href="http://www.python.org/workshops/1994-11/BuiltInClasses/Welcome.html">Don
Beaudry Hack</a>'' that also inspired Don's MESS System.
<p>
The major differences are:
<ul>
<li>Zope is entirely 'C' language-based. It doesn't require a C++
compiler, so it's much more portable than Boost.Python, which stresses
the limits of even some modern C++ implementations.
<li>
Boost.Python lifts the burden on the user to parse and convert function
argument types. Zope provides no such facility.
<li>
Boost.Python lifts the burden on the user to maintain Python
reference-counts.
<li>
Boost.Python supports function overloading; Zope does not.
<li>
Boost.Python supplies a simple mechanism for exposing read-only and
read/write access to data members of the wrapped C++ type as Python
attributes.
<li>
Writing a Zope ExtensionClass is significantly more complex than
exposing a C++ class to python using Boost.Python (mostly a summary of the
previous 4 items). <a href=
"http://www.digicool.com/releases/ExtensionClass/MultiMapping.html">A
Zope Example</a> illustrates the differences.
<li>
Zope's ExtensionClasses are specifically motivated by ``the need for a
C-based persistence mechanism''. Boost.Python's are motivated by the desire
to simply reflect a C++ API into Python with as little modification as
possible.
<li>
The following Zope restriction does not apply to Boost.Python: ``At most one
base extension direct or indirect super class may define C data
members. If an extension subclass inherits from multiple base
extension classes, then all but one must be mix-in classes that
provide extension methods but no data.''
<li>
Zope requires use of the somewhat funky inheritedAttribute (search for
``inheritedAttribute'' on <a
href="http://www.digicool.com/releases/ExtensionClass">this page</a>)
method to access base class methods. In Boost.Python, base class methods can
be accessed in the usual way by writing
``<code>BaseClass.method</code>''.
<li>
Zope supplies some creative but esoteric idioms such as <a href=
"http://www.digicool.com/releases/ExtensionClass/Acquisition.html">
Acquisition</a>. No specific support for this is built into Boost.Python.
<li>
Zope's ComputedAttribute support is designed to be used from Python.
<a href="special.html#getter_setter">The analogous feature of
Boost.Python</a> can be used from C++ or Python. The feature is arguably
easier to use in Boost.Python.
</ul>
<p>
Next: <a href="example1.html">A Simple Example Using Boost.Python</a>
Previous: <a href="extending.html">A Brief Introduction to writing Python Extension Modules</a>
Up: <a href="index.html">Top</a>
<p>
&copy; Copyright David Abrahams 2000. Permission to copy, use, modify,
sell and distribute this document is granted provided this copyright
notice appears in all copies. This document is provided ``as is'' without
express or implied warranty, and with no claim as to its suitability
for any purpose.
<p>
Updated: Mar 6, 2001
</div>

336
doc/cross_module.html Normal file
View File

@@ -0,0 +1,336 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN"
"http://www.w3.org/TR/REC-html40/strict.dtd">
<title>Cross-extension-module dependencies</title>
<div>
<img src="../../../c++boost.gif"
alt="c++boost.gif (8819 bytes)"
align="center"
width="277" height="86">
<hr>
<h1>Cross-extension-module dependencies</h1>
It is good programming practice to organize large projects as modules
that interact with each other via well defined interfaces. With
Boost.Python it is possible to reflect this organization at the C++
level at the Python level. This is, each logical C++ module can be
organized as a separate Python extension module.
<p>
At first sight this might seem natural and straightforward. However, it
is a fairly complex problem to establish cross-extension-module
dependencies while maintaining the same ease of use Boost.Python
provides for classes that are wrapped in the same extension module. To
a large extent this complexity can be hidden from the author of a
Boost.Python extension module, but not entirely.
<hr>
<h2>The recipe</h2>
Suppose there is an extension module that exposes certain instances of
the C++ <tt>std::vector</tt> template library such that it can be used
from Python in the following manner:
<pre>
import std_vector
v = std_vector.double([1, 2, 3, 4])
v.push_back(5)
v.size()
</pre>
Suppose the <tt>std_vector</tt> module is done well and reflects all
C++ functions that are useful at the Python level, for all C++ built-in
data types (<tt>std_vector.int</tt>, <tt>std_vector.long</tt>, etc.).
<p>
Suppose further that there is statistic module with a C++ class that
has constructors or member functions that use or return a
<tt>std::vector</tt>. For example:
<pre>
class xy {
public:
xy(const std::vector&lt;double&gt;&amp; x, const std::vector&lt;double&gt;&amp; y) : m_x(x), m_y(y) {}
const std::vector&lt;double&gt;&amp; x() const { return m_x; }
const std::vector&lt;double&gt;&amp; y() const { return m_y; }
double correlation();
private:
std::vector&lt;double&gt; m_x;
std::vector&lt;double&gt; m_y;
}
</pre>
What is more natural than reusing the <tt>std_vector</tt> extension
module to expose these constructors or functions to Python?
<p>
Unfortunately, what seems natural needs a little work in both the
<tt>std_vector</tt> and the <tt>statistics</tt> module.
<p>
In the <tt>std_vector</tt> extension module,
<tt>std::vector&lt;double&gt;</tt> is exposed to Python in the usual
way with the <tt>class_builder&lt;&gt;</tt> template. To also enable the
automatic conversion of <tt>std::vector&lt;double&gt;</tt> function
arguments or return values in other Boost.Python C++ modules, the
converters that convert a <tt>std::vector&lt;double&gt;</tt> C++ object
to a Python object and vice versa (i.e. the <tt>to_python()</tt> and
<tt>from_python()</tt> template functions) have to be exported. For
example:
<pre>
#include &lt;boost/python/cross_module.hpp&gt;
//...
class_builder&lt;std::vector&lt;double&gt; &gt; v_double(std_vector_module, &quot;double&quot;);
export_converters(v_double);
</pre>
In the extension module that wraps <tt>class xy</tt> we can now import
these converters with the <tt>import_converters&lt;&gt;</tt> template.
For example:
<pre>
#include &lt;boost/python/cross_module.hpp&gt;
//...
import_converters&lt;std::vector&lt;double&gt; &gt; v_double_converters(&quot;std_vector&quot;, &quot;double&quot;);
</pre>
That is all. All the attributes that are defined for
<tt>std_vector.double</tt> in the <tt>std_vector</tt> Boost.Python
module will be available for the returned objects of <tt>xy.x()</tt>
and <tt>xy.y()</tt>. Similarly, the constructor for <tt>xy</tt> will
accept objects that were created by the <tt>std_vector</tt>module.
<hr>
<h2>Placement of <tt>import_converters&lt;&gt;</tt> template instantiations</h2>
<tt>import_converts&lt;&gt;</tt> can be viewed as a drop-in replacement
for <tt>class_wrapper&lt;&gt;</tt>, and the recommendations for the
placement of <tt>class_wrapper&lt;&gt;</tt> template instantiations
also apply to to <tt>import_converts&lt;&gt;</tt>. In particular, it is
important that an instantiation of <tt>class_wrapper&lt;&gt;</tt> is
visible to any code which wraps a C++ function with a <tt>T</tt>,
<tt>T*</tt>, const <tt>T&amp;</tt>, etc. parameter or return value.
Therefore you may want to group all <tt>class_wrapper&lt;&gt;</tt> and
<tt>import_converts&lt;&gt;</tt> instantiations at the top of your
module's init function, then <tt>def()</tt> the member functions later
to avoid problems with inter-class dependencies.
<hr>
<h2>Non-copyable types</h2>
<tt>export_converters()</tt> instantiates C++ template functions that
invoke the copy constructor of the wrapped type. For a type that is
non-copyable this will result in compile-time error messages. In such a
case, <tt>export_converters_noncopyable()</tt> can be used to export
the converters that do not involve the copy constructor of the wrapped
type. For example:
<pre>
class_builder&lt;store&gt; py_store(your_module, &quot;store&quot;);
export_converters_noncopyable(py_store);
</pre>
The corresponding <tt>import_converters&lt;&gt;</tt> statement does not
need any special attention:
<pre>
import_converters&lt;store&gt; py_store(&quot;noncopyable_export&quot;, &quot;store&quot;);
</pre>
<hr>
<h2>Python module search path</h2>
The <tt>std_vector</tt> and <tt>statistics</tt> modules can now be used
in the following way:
<pre>
import std_vector
import statistics
x = std_vector.double([1, 2, 3, 4])
y = std_vector.double([2, 4, 6, 8])
xy = statistics.xy(x, y)
xy.correlation()
</pre>
In this example it is clear that Python has to be able to find both the
<tt>std_vector</tt> and the <tt>statistics</tt> extension module. In
other words, both extension modules need to be in the Python module
search path (<tt>sys.path</tt>).
<p>
The situation is not always this obvious. Suppose the
<tt>statistics</tt> module has a <tt>random()</tt> function that
returns a vector of random numbers with a given length:
<pre>
import statistics
x = statistics.random(5)
y = statistics.random(5)
xy = statistics.xy(x, y)
xy.correlation()
</pre>
A naive user will not easily anticipate that the <tt>std_vector</tt>
module is used to pass the <tt>x</tt> and <tt>y</tt> vectors around. If
the <tt>std_vector</tt> module is in the Python module search path,
this form of ignorance is of no harm. On the contrary, we are glad
that we do not have to bother the user with details like this.
<p>
If the <tt>std_vector</tt> module is not in the Python module search
path, a Python exception will be raised:
<pre>
Traceback (innermost last):
File &quot;foo.py&quot;, line 2, in ?
x = statistics.random(5)
ImportError: No module named std_vector
</pre>
As is the case with any system of a non-trivial complexity, it is
important that the setup is consistent and complete.
<hr>
<h2>Two-way module dependencies</h2>
Boost.Python supports two-way module dependencies. This is best
illustrated by a simple example.
<p>
Suppose there is a module <tt>ivect</tt> that implements vectors of
integers, and a similar module <tt>dvect</tt> that implements vectors
of doubles. We want to be able do convert an integer vector to a double
vector and vice versa. For example:
<pre>
import ivect
iv = ivect.ivect((1,2,3,4,5))
dv = iv.as_dvect()
</pre>
The last expression will implicitly import the <tt>dvect</tt> module in
order to enable the conversion of the C++ representation of
<tt>dvect</tt> to a Python object. The analogous is possible for a
<tt>dvect</tt>:
<pre>
import dvect
dv = dvect.dvect((1,2,3,4,5))
iv = dv.as_ivect()
</pre>
Now the <tt>ivect</tt> module is imported implicitly.
<p>
Note that the two-way dependencies are possible because the
dependencies are resolved only when needed. This is, the initialization
of the <tt>ivect</tt> module does not rely on the <tt>dvect</tt>
module, and vice versa. Only if <tt>as_dvect()</tt> or
<tt>as_ivect()</tt> is actually invoked will the corresponding module
be implicitly imported. This also means that, for example, the
<tt>dvect</tt> module does not have to be available at all if
<tt>as_dvect()</tt> is never used.
<hr>
<h2>Clarification of compile-time and link-time dependencies</h2>
Boost.Python's support for resolving cross-module dependencies at
runtime does not imply that compile-time dependencies are eliminated.
For example, the statistics extension module in the example above will
need to <tt>#include &lt;vector&gt;</tt>. This is immediately obvious
from the definition of <tt>class xy</tt>.
<p>
If a library is wrapped that consists of both header files and compiled
components (e.g. <tt>libdvect.a</tt>, <tt>dvect.lib</tt>, etc.), both
the Boost.Python extension module with the
<tt>export_converters()</tt> statement and the module with the
<tt>import_converters&lt;&gt;</tt> statement need to be linked against
the object library. Ideally one would build a shared library (e.g.
<tt>libdvect.so</tt>, <tt>dvect.dll</tt>, etc.). However, this
introduces the issue of having to configure the search path for the
dynamic loading correctly. For small libraries it is therefore often
more convenient to ignore the fact that the object files are loaded
into memory more than once.
<hr>
<h2>Summary of motivation for cross-module support</h2>
The main purpose of Boost.Python's cross-module support is to allow for
a modular system layout. With this support it is straightforward to
reflect C++ code organization at the Python level. Without the
cross-module support, a multi-purpose module like <tt>std_vector</tt>
would be impractical because the entire wrapper code would somehow have
to be duplicated in all extension modules that use it, making them
harder to maintain and harder to build.
<p>
Another motivation for the cross-module support is that two extension
modules that wrap the same class cannot both be imported into Python.
For example, if there are two modules <tt>A</tt> and <tt>B</tt> that
both wrap a given <tt>class X</tt>, this will work:
<pre>
import A
x = A.X()
</pre>
This will also work:
<pre>
import B
x = B.X()
</pre>
However, this will fail:
<pre>
import A
import B
python: /net/cci/rwgk/boost/boost/python/detail/extension_class.hpp:866:
static void boost::python::detail::class_registry&lt;X&gt;::register_class(boost::python::detail::extension_class_base *):
Assertion `static_class_object == 0' failed.
Abort
</pre>
A good solution is to wrap <tt>class X</tt> only once. Depending on the
situation, this could be done by module <tt>A</tt> or <tt>B</tt>, or an
additional small extension module that only wraps and exports
<tt>class X</tt>.
<p>
Finally, there can be important psychological or political reasons for
using the cross-module support. If a group of classes is lumped
together with many others in a huge module, the authors will have
difficulties in being identified with their work. The situation is
much more transparent if the work is represented by a module with a
recognizable name. This is not just a question of strong egos, but also
of getting credit and funding.
<hr>
<h2>Why not use <tt>export_converters()</tt> universally?</h2>
There is some overhead associated with the Boost.Python cross-module
support. Depending on the platform, the size of the code generated by
<tt>export_converters()</tt> is roughly 10%-20% of that generated
by <tt>class_builder&lt;&gt;</tt>. For a large extension module with
many wrapped classes, this could mean a significant difference.
Therefore the general recommendation is to use
<tt>export_converters()</tt> only for classes that are likely to
be used as function arguments or return values in other modules.
<hr>
&copy; Copyright Ralf W. Grosse-Kunstleve 2001. Permission to copy,
use, modify, sell and distribute this document is granted provided this
copyright notice appears in all copies. This document is provided "as
is" without express or implied warranty, and with no claim as to its
suitability for any purpose.
<p>
Updated: April 2001
</div>

192
doc/data_structures.txt Normal file
View File

@@ -0,0 +1,192 @@
Given a real Python class 'A', a wrapped C++ class 'B', and this definition:
class C(A, B):
def __init__(self):
B.__init__(self)
self.x = 1
...
c = C()
this diagram describes the internal structure of an instance of 'C', including
its inheritance relationships. Note that ExtensionClass<B> is derived from
Class<ExtensionInstance>, and is in fact identical for all intents and purposes.
MetaClass<ExtensionInstance>
+---------+ +---------+
types.ClassType: | | | |
| | | |
| | | |
+---------+ +---------+
^ ^ ^
PyClassObject | ExtensionClass<B> | |
A: +------------+ | B: +------------+ | |
| ob_type -+-+ | ob_type -+-----+ |
| | ()<--+- __bases__ | |
| | | __dict__ -+->{...} |
| | 'B'<-+- __name__ | |
+------------+ +------------+ |
^ ^ |
| | |
+-----+ +-------------+ |
| | |
| | Class<ExtensionInstance> |
| | C: +------------+ |
| | | ob_type -+------------+
tuple:(*, *)<--+- __bases__ |
| __dict__ -+->{__module__, <methods, etc.>}
'C' <-+- __name__ |
+------------+
^ (in case of inheritance from more than one
| extension class, this vector would contain
+---------------+ a pointer to an instance holder for the data
| of each corresponding C++ class)
| ExtensionInstance
| c: +---------------------+ std::vector<InstanceHolderBase>
+----+- __class__ | +---+--
| m_wrapped_objects -+->| * | ...
{'x': 1}<-+- __dict__ | +-|-+--
+---------------------+ | InstanceValueHolder<B>
| +--------------------------------+
+-->| (contains a C++ instance of B) |
+--------------------------------+
In our inheritance test cases in extclass_demo.cpp/test_extclass.py, we have the
following C++ inheritance hierarchy:
+-----+ +----+
| A1 | | A2 |
+-----+ +----+
^ ^ ^ ^ ^
| | | | |
+-----+ | +---------+-----+
| | | |
| +---+----------+
.......!...... | |
: A_callback : +-+--+ +-+--+
:............: | B1 | | B2 |
+----+ +----+
^
|
+-------+---------+
| |
+-+-+ ......!.......
| C | : B_callback :
+---+ :............:
A_callback and B_callback are used as part of the wrapping mechanism but not
represented in Python. C is also not represented in Python but is delivered
there polymorphically through a smart pointer.
This is the data structure in Python.
ExtensionClass<A1>
A1: +------------+
()<--+- __bases__ |
| __dict__ -+->{...}
+------------+
^
| ExtensionInstance
| a1: +---------------------+ vec InstanceValueHolder<A1,A_callback>
+---------+- __class__ | +---+ +---------------------+
| | m_wrapped_objects -+->| *-+-->| contains A_callback |
| +---------------------+ +---+ +---------------------+
|
| ExtensionInstance
| pa1_a1: +---------------------+ vec InstancePtrHolder<auto_ptr<A1>,A1>
+---------+- __class__ | +---+ +---+
| | m_wrapped_objects -+->| *-+-->| *-+-+ A1
| +---------------------+ +---+ +---+ | +---+
| +->| |
| ExtensionInstance +---+
| pb1_a1: +---------------------+ vec InstancePtrHolder<auto_ptr<A1>,A1>
+---------+- __class__ | +---+ +---+
| | m_wrapped_objects -+->| *-+-->| *-+-+ B1
| +---------------------+ +---+ +---+ | +---+
| +->| |
| ExtensionInstance +---+
| pb2_a1: +---------------------+ vec InstancePtrHolder<auto_ptr<A1>,A1>
+---------+- __class__ | +---+ +---+
| | m_wrapped_objects -+->| *-+-->| *-+-+ B2
| +---------------------+ +---+ +---+ | +---+
| +->| |
| +---+
| ExtensionClass<A1>
| A2: +------------+
| ()<--+- __bases__ |
| | __dict__ -+->{...}
| +------------+
| ^
| | ExtensionInstance
| a2: | +---------------------+ vec InstanceValueHolder<A2>
| +-+- __class__ | +---+ +-------------+
| | | m_wrapped_objects -+->| *-+-->| contains A2 |
| | +---------------------+ +---+ +-------------+
| |
| | ExtensionInstance
| pa2_a2: | +---------------------+ vec InstancePtrHolder<auto_ptr<A2>,A2>
| +-+- __class__ | +---+ +---+
| | | m_wrapped_objects -+->| *-+-->| *-+-+ A2
| | +---------------------+ +---+ +---+ | +---+
| | +->| |
| | ExtensionInstance +---+
| pb1_a2: | +---------------------+ vec InstancePtrHolder<auto_ptr<A2>,A2>
| +-+- __class__ | +---+ +---+
| | | m_wrapped_objects -+->| *-+-->| *-+-+ B1
| | +---------------------+ +---+ +---+ | +---+
| | +->| |
| | +---+
| |
| +---------------+------------------------------+
| | |
+------+-------------------------+-|----------------------------+ |
| | | | |
| Class<ExtensionInstance> | | ExtensionClass<B1> | | ExtensionClass<B1>
| DA1: +------------+ | | B1: +------------+ | | B2: +------------+
(*,)<---+- __bases__ | (*,*)<---+- __bases__ | (*,*)<---+- __bases__ |
| __dict__ -+->{...} | __dict__ -+->{...} | __dict__ -+->{...}
+------------+ +------------+ +------------+
^ ^ ^
| ExtensionInstance | |
| da1: +---------------------+ | vec InstanceValueHolder<A1,A_callback>
+-------+- __class__ | | +---+ +---------------------+ |
| m_wrapped_objects -+--|-->| *-+-->| contains A_callback | |
+---------------------+ | +---+ +---------------------+ |
+--------------------------------------+ |
| ExtensionInstance |
b1: | +---------------------+ vec InstanceValueHolder<B1,B_callback> |
+-+- __class__ | +---+ +---------------------+ |
| | m_wrapped_objects -+->| *-+-->| contains B_callback | |
| +---------------------+ +---+ +---------------------+ |
| |
| ExtensionInstance |
pb1_b1: | +---------------------+ vec InstancePtrHolder<auto_ptr<B1>,B1> |
+-+- __class__ | +---+ +---+ |
| | m_wrapped_objects -+->| *-+-->| *-+-+ B1 |
| +---------------------+ +---+ +---+ | +---+ |
| +->| | |
| ExtensionInstance +---+ |
pc_b1: | +---------------------+ vec InstancePtrHolder<auto_ptr<B1>,B1> |
+-+- __class__ | +---+ +---+ |
| | m_wrapped_objects -+->| *-+-->| *-+-+ C |
| +---------------------+ +---+ +---+ | +---+ |
| +->| | |
| +---+ |
| |
| Class<ExtensionInstance> +---------------------------------------+
| DB1: +------------+ | ExtensionInstance
(*,)<---+- __bases__ | a2: | +---------------------+ vec InstanceValueHolder<A2>
| __dict__ -+->{...} +-+- __class__ | +---+ +-------------+
+------------+ | m_wrapped_objects -+->| *-+-->| contains A2 |
^ +---------------------+ +---+ +-------------+
| ExtensionInstance
db1: | +---------------------+ vec InstanceValueHolder<B1,B_callback>
+-+- __class__ | +---+ +----------------------+
| m_wrapped_objects -+-->| *-+-->| contains B1_callback |
+---------------------+ +---+ +----------------------+

120
doc/enums.html Normal file
View File

@@ -0,0 +1,120 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN"
"http://www.w3.org/TR/REC-html40/strict.dtd">
<title>
Wrapping enums
</title>
<div>
<h1>
<img width="277" height="86" id="_x0000_i1025" align="center"
src="../../../c++boost.gif" alt= "c++boost.gif (8819 bytes)"><br>
Wrapping enums
</h1>
<p>Because there is in general no way to deduce that a value of arbitrary type T
is an enumeration constant, the Boost Python Library cannot automatically
convert enum values to and from Python. To handle this case, you need to decide
how you want the enum to show up in Python (since Python doesn't have
enums). Once you have done that, you can write some simple
<code>from_python()</code> and <code>to_python()</code> functions.
<p>If you are satisfied with a Python int as a way to represent your enum
values, we provide a shorthand for these functions. You just need to cause
<code>boost::python::enum_as_int_converters&lt;EnumType&gt;</code> to be
instantiated, where
<code>EnumType</code> is your enumerated type. There are two convenient ways to do this:
<ol>
<li>Explicit instantiation:
<blockquote><pre>
template class boost::python::enum_as_int_converters&lt;my_enum&gt;;
</blockquote></pre>
Some buggy C++ implementations require a class to be instantiated in the same
namespace in which it is defined. In that case, the simple incantation above becomes:
<blockquote>
<pre>
...
} // close my_namespace
// drop into namespace python and explicitly instantiate
namespace boost { namespace python {
template class enum_as_int_converters&lt;my_enum_type&gt;;
}} // namespace boost::python
namespace my_namespace { // re-open my_namespace
...
</pre>
</blockquote>
<li>If you have such an implementation, you may find this technique more convenient
<blockquote><pre>
// instantiate as base class in any namespace
struct EnumTypeConverters
: boost::python::enum_as_int_converters&lt;EnumType&gt;
{
};
</blockquote></pre>
</ol>
<p>Either of the above is equivalent to the following declarations:
<blockquote><pre>
BOOST_PYTHON_BEGIN_CONVERSION_NAMESPACE // this is a gcc 2.95.2 bug workaround
MyEnumType from_python(PyObject* x, boost::python::type&lt;MyEnumType&gt;)
{
return static_cast&lt;MyEnum&gt;(
from_python(x, boost::python::type&lt;long&gt;()));
}
MyEnumType from_python(PyObject* x, boost::python::type&lt;const MyEnumType&amp;&gt;)
{
return static_cast&lt;MyEnum&gt;(
from_python(x, boost::python::type&lt;long&gt;()));
}
PyObject* to_python(MyEnumType x)
{
return to_python(static_cast&lt;long&gt;(x));
}
BOOST_PYTHON_END_CONVERSION_NAMESPACE
</pre></blockquote>
<p>This technique defines the conversions of
<code>MyEnumType</code> in terms of the conversions for the built-in
<code>long</code> type.
You may also want to add a bunch of lines like this to your module
initialization. These bind the corresponding enum values to the appropriate
names so they can be used from Python:
<blockquote><pre>
mymodule.add(boost::python::make_ref(enum_value_1), "enum_value_1");
mymodule.add(boost::python::make_ref(enum_value_2), "enum_value_2");
...
</pre></blockquote>
You can also add these to an extension class definition, if your enum happens to
be local to a class and you want the analogous interface in Python:
<blockquote><pre>
my_class_builder.add(boost::python::to_python(enum_value_1), "enum_value_1");
my_class_builder.add(boost::python::to_python(enum_value_2), "enum_value_2");
...
</pre></blockquote>
<p>
Next: <a href="pointers.html">Pointers and Smart Pointers</a>
Previous: <a href="building.html">Building an Extension Module</a>
Up: <a href="index.html">Top</a>
<p>
&copy; Copyright David Abrahams 2000. Permission to copy, use, modify,
sell and distribute this document is granted provided this copyright
notice appears in all copies. This document is provided ``as
is'' without express or implied warranty, and with no claim as to
its suitability for any purpose.
<p>
Updated: Mar 6, 2001
</div>

75
doc/example1.html Normal file
View File

@@ -0,0 +1,75 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN"
"http://www.w3.org/TR/REC-html40/strict.dtd">
<title>
A Simple Example
</title>
<div>
<h1>
<img width="277" height="86" id="_x0000_i1025" src="../../../c++boost.gif" alt=
"c++boost.gif (8819 bytes)">
</h1>
<h1>
A Simple Example
</h1>
<p>
Suppose we have the following C++ API which we want to expose in
Python:
<blockquote>
<pre>
#include &lt;string&gt;
namespace { // Avoid cluttering the global namespace.
// A couple of simple C++ functions that we want to expose to Python.
std::string greet() { return "hello, world"; }
int square(int number) { return number * number; }
}
</pre>
</blockquote>
<p>
Here is the C++ code for a python module called <tt>getting_started1</tt>
which exposes the API.
<blockquote>
<pre>
#include &lt;boost/python/class_builder.hpp&gt;
namespace python = boost::python;
BOOST_PYTHON_MODULE_INIT(getting_started1)
{
// Create an object representing this extension module.
python::module_builder this_module("getting_started1");
// Add regular functions to the module.
this_module.def(greet, "greet");
this_module.def(square, "square");
}
</pre>
</blockquote>
<p>
That's it! If we build this shared library and put it on our <code>
PYTHONPATH</code> we can now access our C++ functions from
Python.
<blockquote>
<pre>
&gt;&gt;&gt; import getting_started1
&gt;&gt;&gt; print getting_started1.greet()
hello, world
&gt;&gt;&gt; number = 11
&gt;&gt;&gt; print number, '*', number, '=', getting_started1.square(number)
11 * 11 = 121
</pre>
<p>
Next: <a href="exporting_classes.html">Exporting Classes</a>
Previous: <a href="comparisons.html">Comparisons with other systems</a> Up:
<a href="index.html">Top</a>
<p>
&copy; Copyright David Abrahams 2000. Permission to copy, use, modify,
sell and distribute this document is granted provided this copyright
notice appears in all copies. This document is provided "as is" without
express or implied warranty, and with no claim as to its suitability
for any purpose.
<p>
Updated: Mar 6, 2000
</div>

143
doc/exporting_classes.html Normal file
View File

@@ -0,0 +1,143 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN"
"http://www.w3.org/TR/REC-html40/strict.dtd">
<title>
Exporting Classes
</title>
<div>
<h1>
<img width="277" height="86" id="_x0000_i1025" src="../../../c++boost.gif" alt=
"c++boost.gif (8819 bytes)">
</h1>
<h1>
Exporting Classes
</h1>
<p>
Now let's expose a C++ class to Python:
<blockquote><pre>
#include &lt;iostream&gt;
#include &lt;string&gt;
namespace { // Avoid cluttering the global namespace.
// A friendly class.
class hello
{
public:
hello(const std::string&amp; country) { this-&gt;country = country; }
std::string greet() const { return "Hello from " + country; }
private:
std::string country;
};
// A function taking a hello object as an argument.
std::string invite(const hello&amp; w) {
return w.greet() + "! Please come soon!";
}
}
</blockquote></pre> <p>
To expose the class, we use a <tt>class_builder</tt> in addition to the
<tt>module_builder</tt> from the previous example. Class member functions
are exposed by using the <tt>def()</tt> member function on the
<tt>class_builder</tt>:
<blockquote><pre>
#include &lt;boost/python/class_builder.hpp&gt;
namespace python = boost::python;
BOOST_PYTHON_MODULE_INIT(getting_started2)
{
// Create an object representing this extension module.
python::module_builder this_module("getting_started2");
// Create the Python type object for our extension class.
python::class_builder&lt;hello&gt; hello_class(this_module, "hello");
// Add the __init__ function.
hello_class.def(python::constructor&lt;std::string&gt;());
// Add a regular member function.
hello_class.def(&amp;hello::greet, "greet");
// Add invite() as a regular function to the module.
this_module.def(invite, "invite");
// Even better, invite() can also be made a member of hello_class!!!
hello_class.def(invite, "invite");
}
</blockquote></pre>
<p>
Now we can use the class normally from Python:
<blockquote><pre>
&gt;&gt;&gt; from getting_started2 import *
&gt;&gt;&gt; hi = hello('California')
&gt;&gt;&gt; hi.greet()
'Hello from California'
&gt;&gt;&gt; invite(hi)
'Hello from California! Please come soon!'
&gt;&gt;&gt; hi.invite()
'Hello from California! Please come soon!'
</blockquote></pre>
Notes:<ul>
<li> We expose the class' constructor by calling <tt>def()</tt> on the
<tt>class_builder</tt> with an argument whose type is
<tt>constructor&lt;</tt><i>params</i><tt>&gt;</tt>, where <i>params</i>
matches the list of constructor argument types:
<li>Regular member functions are defined by calling <tt>def()</tt> with a
member function pointer and its Python name:
<li>Any function added to a class whose initial argument matches the class (or
any base) will act like a member function in Python.
<li>To define a nested class, just pass the enclosing
<tt>class_builder</tt> (instead of a <tt>module_builder</tt>) as the
first argument to the nested <tt>class_builder</tt>'s constructor.
</ul>
<p>
We can even make a subclass of <code>hello.world</code>:
<blockquote><pre>
&gt;&gt;&gt; class wordy(hello):
... def greet(self):
... return hello.greet(self) + ', where the weather is fine'
...
&gt;&gt;&gt; hi2 = wordy('Florida')
&gt;&gt;&gt; hi2.greet()
'Hello from Florida, where the weather is fine'
&gt;&gt;&gt; invite(hi2)
'Hello from Florida! Please come soon!'
</blockquote></pre>
<p>
Pretty cool! You can't do that with an ordinary Python extension type!
Of course, you may now have a slightly empty feeling in the pit of
your little pythonic stomach. Perhaps you wanted to see the following
<tt>wordy</tt> invitation:
<blockquote><pre>
'Hello from Florida, where the weather is fine! Please come soon!'
</blockquote></pre>
After all, <tt>invite</tt> calls <tt>hello::greet()</tt>, and you
reimplemented that in your Python subclass, <tt>wordy</tt>. If so, <a
href= "overriding.html">read on</a>...
<p>
Next: <a href="overriding.html">Overridable virtual functions</a>
Previous: <a href="example1.html">A Simple Example</a> Up:
<a href="index.html">Top</a>
<p>
&copy; Copyright David Abrahams 2000. Permission to copy, use, modify,
sell and distribute this document is granted provided this copyright
notice appears in all copies. This document is provided "as is" without
express or implied warranty, and with no claim as to its suitability
for any purpose.
<p>
Updated: Mar 6, 2001
</div>

73
doc/extending.html Normal file
View File

@@ -0,0 +1,73 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<title>
A Brief Introduction to writing Python extension modules
</title>
<h1>
<img src="../../../c++boost.gif" alt="c++boost.gif (8819 bytes)" align="center"
width="277" height="86">
</h1>
<h1>
A Brief Introduction to writing Python extension modules
</h1>
<p>
Interfacing any language to Python involves building a module which can
be loaded by the Python interpreter, but which isn't written in Python.
This is known as an <em>extension module</em>. Many of the <a href=
"http://www.python.org/doc/current/lib/lib.html">built-in Python
libraries</a> are constructed in 'C' this way; Python even supplies its
<a href="http://www.python.org/doc/current/lib/types.html">fundamental
types</a> using the same mechanism. An extension module can be statically
linked with the Python interpreter, but it more commonly resides in a
shared library or DLL.
<p>
As you can see from <a href=
"http://www.python.org/doc/current/ext/ext.html"> The Python Extending
and Embedding Tutorial</a>, writing an extension module normally means
worrying about
<ul>
<li>
<a href="http://www.python.org/doc/current/ext/refcounts.html">
maintaining reference counts</a>
<li>
<a href="http://www.python.org/doc/current/ext/callingPython.html"> how
to call back into Python</a>
<li>
<a href="http://www.python.org/doc/current/ext/parseTuple.html">
function argument parsing and typechecking</a>
</ul>
This last item typically occupies a great deal of code in an extension
module. Remember that Python is a completely dynamic language. A callable
object receives its arguments in a tuple; it is up to that object to extract
those arguments from the tuple, check their types, and raise appropriate
exceptions. There are numerous other tedious details that need to be
managed; too many to mention here. The Boost Python Library is designed to
lift most of that burden.<br>
<br>
<p>
Another obstacle that most people run into eventually when extending
Python is that there's no way to make a true Python class in an extension
module. The typical solution is to create a new Python type in the
extension module, and then write an additional module in 100% Python. The
Python module defines a Python class which dispatches to an instance of
the extension type, which it contains. This allows users to write
subclasses of the class in the Python module, almost as though they were
sublcassing the extension type. Aside from being tedious, it's not really
the same as having a true class, because there's no way for the user to
override a method of the extension type which is called from the
extension module. Boost.Python solves this problem by taking advantage of <a
href="http://www.python.org/doc/essays/metaclasses/">Python's metaclass
feature</a> to provide objects which look, walk, and hiss almost exactly
like regular Python classes. Boost.Python classes are actually cleaner than
Python classes in some subtle ways; a more detailed discussion will
follow (someday).</p>
<p>Next: <a href="comparisons.html">Comparisons with Other Systems</a> Up: <a
href="index.html">Top</a> </p>
<p>
&copy; Copyright David Abrahams 2000. Permission to copy, use, modify,
sell and distribute this document is granted provided this copyright
notice appears in all copies. This document is provided "as is" without
express or implied warranty, and with no claim as to its suitability for
any purpose.</p>

166
doc/inheritance.html Normal file
View File

@@ -0,0 +1,166 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN"
"http://www.w3.org/TR/REC-html40/strict.dtd">
<title>
Inheritance
</title>
<div>
<h1>
<img width="277" height="86" id="_x0000_i1025" align="center"
src="../../../c++boost.gif" alt= "c++boost.gif (8819 bytes)">Inheritance
</h1>
<h2>Inheritance in Python</h2>
<p>
Boost.Python extension classes support single and multiple-inheritance in
Python, just like regular Python classes. You can arbitrarily mix
built-in Python classes with extension classes in a derived class'
tuple of bases. Whenever a Boost.Python extension class is among the bases for a
new class in Python, the result is an extension class:
<blockquote>
<pre>
&gt;&gt;&gt; class MyPythonClass:
... def f(): return 'MyPythonClass.f()'
...
&gt;&gt;&gt; import my_extension_module
&gt;&gt;&gt; class Derived(my_extension_module.MyExtensionClass, MyPythonClass):
... '''This is an extension class'''
... pass
...
&gt;&gt;&gt; x = Derived()
&gt;&gt;&gt; x.f()
'MyPythonClass.f()'
&gt;&gt;&gt; x.g()
'MyExtensionClass.g()'
</pre>
</blockquote>
<h2><a name="implicit_conversion">Reflecting C++ Inheritance Relationships</a></h2>
<p>
Boost.Python also allows us to represent C++ inheritance relationships so that
wrapped derived classes may be passed where values, pointers, or
references to a base class are expected as arguments. The
<code>declare_base</code> member function of
<code>class_builder&lt;&gt;</code> is used to establish the relationship
between base and derived classes:
<blockquote>
<pre>
#include &lt;memory&gt; // for std::auto_ptr&lt;&gt;
struct Base {
virtual ~Base() {}
virtual const char* name() const { return "Base"; }
};
struct Derived : Base {
Derived() : x(-1) {}
virtual const char* name() const { return "Derived"; }
int x;
};
std::auto_ptr&lt;Base&gt; derived_as_base() {
return std::auto_ptr&lt;Base&gt;(new Derived);
}
const char* get_name(const Base& b) {
return b.name();
}
int get_derived_x(const Derived& d) {
return d.x;
}
<hr>
#include &lt;boost/python/class_builder.hpp&gt;
// namespace alias for code brevity
namespace python = boost::python;
BOOST_PYTHON_MODULE_INIT(my_module)
{
    python::module_builder my_module("my_module");
    python::class_builder&lt;Base&gt; base_class(my_module, "Base");
    base_class.def(python::constructor&lt;&gt;());
    python::class_builder&lt;Derived&gt; derived_class(my_module, "Derived");
    derived_class.def(python::constructor&lt;&gt;());
<b>// Establish the inheritance relationship between Base and Derived
derived_class.declare_base(base_class);</b>
my_module.def(derived_as_base, "derived_as_base");
my_module.def(get_name, "get_name");
my_module.def(get_derived_x, "get_derived_x");
}
</pre>
</blockquote>
<p>
Then, in Python:
<blockquote>
<pre>
&gt;&gt;&gt; from my_module import *
&gt;&gt;&gt; base = Base()
&gt;&gt;&gt; derived = Derived()
&gt;&gt;&gt; get_name(base)
'Base'
</pre>
</blockquote>
<i>objects of wrapped class Derived may be passed where Base is expected</i>
<blockquote>
<pre>
&gt;&gt;&gt; get_name(derived)
'Derived'
</pre>
</blockquote>
<i>objects of wrapped class Derived can be passed where Derived is
expected but where type information has been lost.</i>
<blockquote>
<pre>
&gt;&gt;&gt; get_derived_x(derived_as_base())
-1
</pre>
</blockquote>
<h2>Inheritance Without Virtual Functions</h2>
<p>
If for some reason your base class has no virtual functions but you still want
to represent the inheritance relationship between base and derived classes,
pass the special symbol <code>boost::python::without_downcast</code> as the 2nd parameter
to <code>declare_base</code>:
<blockquote>
<pre>
struct Base2 {};
struct Derived2 { int f(); };
<hr>
...
   python::class_builder&lt;Base&gt; base2_class(my_module, "Base2");
   base2_class.def(python::constructor&lt;&gt;());
   python::class_builder&lt;Derived2&gt; derived2_class(my_module, "Derived2");
   derived2_class.def(python::constructor&lt;&gt;());
derived_class.declare_base(base_class, <b>python::without_downcast</b>);
</pre>
</blockquote>
<p>This approach will allow <code>Derived2</code> objects to be passed where
<code>Base2</code> is expected, but does not attempt to implicitly convert (downcast)
smart-pointers to <code>Base2</code> into <code>Derived2</code> pointers,
references, or values.
<p>
Next: <a href="special.html">Special Method and Operator Support</a>
Previous: <a href="overloading.html">Function Overloading</a>
Up: <a href="index.html">Top</a>
<p>
&copy; Copyright David Abrahams 2000. Permission to copy, use, modify,
sell and distribute this document is granted provided this copyright
notice appears in all copies. This document is provided "as is" without
express or implied warranty, and with no claim as to its suitability
for any purpose.
<p>
Updated: Nov 26, 2000
</div>

155
doc/overloading.html Normal file
View File

@@ -0,0 +1,155 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN"
"http://www.w3.org/TR/REC-html40/strict.dtd">
<title>
Function Overloading
</title>
<div>
<h1>
<img width="277" height="86" id="_x0000_i1025" align="center"
src="../../../c++boost.gif" alt= "c++boost.gif (8819 bytes)">Function Overloading
</h1>
<h2>An Example</h2>
<p>
To expose overloaded functions in Python, simply <code>def()</code> each
one with the same Python name:
<blockquote>
<pre>
inline int f1() { return 3; }
inline int f2(int x) { return x + 1; }
class X {
public:
X() : m_value(0) {}
X(int n) : m_value(n) {}
int value() const { return m_value; }
void value(int v) { m_value = v; }
private:
int m_value;
};
...
BOOST_PYTHON_MODULE_INIT(overload_demo)
{
    try
    {
boost::python::module_builder overload_demo("overload_demo");
// Overloaded functions at module scope
overload_demo.def(f1, "f");
overload_demo.def(f2, "f");
boost::python::class_builder&lt;X&gt; x_class(overload_demo, "X");
// Overloaded constructors
x_class.def(boost::python::constructor&lt;&gt;());
x_class.def(boost::python::constructor&lt;int&gt;());
// Overloaded member functions
x_class.def((int (X::*)() const)&amp;X::value, "value");
x_class.def((void (X::*)(int))&amp;X::value, "value");
...
</pre>
</blockquote>
<p>
Now in Python:
<blockquote>
<pre>
>>> from overload_demo import *
>>> x0 = X()
>>> x1 = X(1)
>>> x0.value()
0
>>> x1.value()
1
>>> x0.value(3)
>>> x0.value()
3
>>> X('hello')
TypeError: No overloaded functions match (X, string). Candidates are:
void (*)()
void (*)(int)
>>> f()
3
>>> f(4)
5
</pre>
</blockquote>
<h2>Discussion</h2>
<p>
Notice that overloading in the Python module was produced three ways:<ol>
<li>by combining the non-overloaded C++ functions <code>int f1()</code>
and <code>int f2(int)</code> and exposing them as <code>f</code> in Python.
<li>by exposing the overloaded constructors of <code>class X</code>
<li>by exposing the overloaded member functions <code>X::value</code>.
</ol>
<p>
Techniques 1. and 3. above are really alternatives. In case 3, you need
to form a pointer to each of the overloaded functions. The casting
syntax shown above is one way to do that in C++. Case 1 does not require
complicated-looking casts, but may not be viable if you can't change
your C++ interface. N.B. There's really nothing unsafe about casting an
overloaded (member) function address this way: the compiler won't let
you write it at all unless you get it right.
<h2>An Alternative to Casting</h2>
<p>
This approach is not neccessarily better, but may be preferable for some
people who have trouble writing out the types of (member) function
pointers or simply prefer to avoid all casts as a matter of principle:
<blockquote>
<pre>
// Forwarding functions for X::value
inline void set_x_value(X&amp; self, int v) { self.value(v); }
inline int get_x_value(X&amp; self) { return self.value(); }
...
// Overloaded member functions
x_class.def(set_x_value, "value");
x_class.def(get_x_value, "value");
</pre>
</blockquote>
<p>Here we are taking advantage of the ability to expose C++ functions at
namespace scope as Python member functions.
<h2>Overload Resolution</h2>
<p>
The function overload resolution mechanism works as follows:
<ul>
<li>Attribute lookup for extension classes proceeds in <a
href="http://www.python.org/doc/current/tut/node11.html#SECTION0011510000000000000000">the
usual Python way</a> using a depth-first, left-to-right search. When a
class is found which has a matching attribute, only functions overloaded
in the context of that class are candidates for overload resolution. In
this sense, overload resolution mirrors the C++ mechanism, where a name
in a derived class ``hides'' all functions with the same name from a base
class.
<p>
<li>Within a name-space context (extension class or module), overloaded
functions are tried in the same order they were
<code>def()</code>ed. The first function whose signature can be made to
match each argument passed is the one which is ultimately called.
This means in particular that you cannot overload the same function on
both ``<code>int</code>'' and ``<code>float</code>'' because Python
automatically converts either of the two types into the other one.
If the ``<code>float</code>'' overload is found first, it is used
also used for arguments of type ``<code>int</code>'' as well, and the
``<code>int</code>'' version of the function is never invoked.
</ul>
<p>
Next: <a href="inheritance.html">Inheritance</a>
Previous: <a href="overriding.html">Overridable Virtual Functions</a>
Up: <a href="index.html">Top</a>
<p>
&copy; Copyright David Abrahams 2001. Permission to copy, use, modify,
sell and distribute this document is granted provided this copyright
notice appears in all copies. This document is provided ``as
is'' without express or implied warranty, and with no claim as to
its suitability for any purpose.
<p>
Updated: Mar 6, 2001
</div>

208
doc/overriding.html Normal file
View File

@@ -0,0 +1,208 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<title>Overridable Virtual Functions</title>
<img src="../../../c++boost.gif" alt="c++boost.gif (8819 bytes)" align="center"
width="277" height="86">
<h1>Overridable Virtual Functions</h1>
<p>
In the <a href="exporting_classes.html">previous example</a> we exposed a simple
C++ class in Python and showed that we could write a subclass. We even
redefined one of the functions in our derived class. Now we will learn
how to make the function behave virtually <em>when called from C++</em>.
<h2><a name="overriding_example">Example</a></h2>
<p>In this example, it is assumed that <code>hello::greet()</code> is a virtual
member function:
<blockquote><pre>
class hello
{
public:
hello(const std::string&amp; country) { this-&gt;country = country; }
<b>virtual</b> std::string greet() const { return "Hello from " + country; }
    virtual ~hello(); // Good practice
...
};
</pre></blockquote>
<p>
We'll need a derived class<a href="#why_derived">*</a> to help us
dispatch the call to Python. In our derived class, we need the following
elements:
<ol>
<li><a name="derived_1">A</a> <code>PyObject*</code> data member (usually
called <tt>self</tt>) that holds a pointer to the Python object corresponding
to our C++ <tt>hello</tt> instance.
<li><a name="derived_2">For</a> each exposed constructor of the
base class <tt>T</tt>, a constructor which takes the same parameters preceded by an initial
<code>PyObject*</code> argument. The initial argument should be stored in the <tt>self</tt> data
member described above.
<li><a name="derived_3">If</a> the class being wrapped is ever returned <i>by
value</i> from a wrapped function, be sure you do the same for the
<tt>T</tt>'s copy constructor: you'll need a constructor taking arguments
<tt>(PyObject*,&nbsp;const&nbsp;T&amp;)</tt>.
<li><a name="derived_4">An</a> implementation of each virtual function you may
wish to override in Python which uses
<tt>callback&lt</tt><i>return-type</i><tt>&gt;::call_method(self,&nbsp;&quot;</tt><i>name</i><tt>&quot;,&nbsp;</tt><i>args...</i><tt>)</tt> to call
the Python override.
<li><a name="derived_5">For</a> each non-pure virtual function meant to be
overridable from Python, a static member function (or a free function) taking
a reference or pointer to the <tt>T</tt> as the first parameter and which
forwards any additional parameters neccessary to the <i>default</i>
implementation of the virtual function. See also <a href="#private">this
note</a> if the base class virtual function is private.
</ol>
<blockquote><pre>
struct hello_callback : hello
{
// hello constructor storing initial self_ parameter
hello_callback(PyObject* self_, const std::string&amp; x) // <a href="#derived_2">2</a>
: hello(x), self(self_) {}
// In case hello is returned by-value from a wrapped function
hello_callback(PyObject* self_, const hello&amp; x) // <a href="#derived_3">3</a>
: hello(x), self(self_) {}
// Override greet to call back into Python
std::string greet() const // <a href="#derived_4">4</a>
{ return boost::python::callback&lt;std::string&gt;::call_method(self, "greet"); }
// Supplies the default implementation of greet
static std::string <a name= "default_implementation">default_greet</a>(const hello& self_) const // <a href="#derived_5">5</a>
{ return self_.hello::greet(); }
private:
PyObject* self; // <a href="#derived_1">1</a>
};
</pre></blockquote>
<p>
Finally, we add <tt>hello_callback</tt> to the <tt>
class_builder&lt;&gt;</tt> declaration in our module initialization
function, and when we define the function, we must tell Boost.Python about the default
implementation:
<blockquote><pre>
// Create the <a name=
"hello_class">Python type object</a> for our extension class
boost::python::class_builder&lt;hello<strong>,hello_callback&gt;</strong> hello_class(hello, "hello");
// Add a virtual member function
hello_class.def(&amp;hello::greet, "greet", &amp;<b>hello_callback::default_greet</b>);
</pre></blockquote>
<p>
Now our Python subclass of <tt>hello</tt> behaves as expected:
<blockquote><pre>
&gt;&gt;&gt; class wordy(hello):
... def greet(self):
... return hello.greet(self) + ', where the weather is fine'
...
&gt;&gt;&gt; hi2 = wordy('Florida')
&gt;&gt;&gt; hi2.greet()
'Hello from Florida, where the weather is fine'
&gt;&gt;&gt; invite(hi2)
'Hello from Florida, where the weather is fine! Please come soon!'
</pre></blockquote>
<p>
<a name="why_derived">*</a>You may ask, "Why do we need this derived
class? This could have been designed so that everything gets done right
inside of <tt>hello</tt>." One of the goals of Boost.Python is to be
minimally intrusive on an existing C++ design. In principle, it should be
possible to expose the interface for a 3rd party library without changing
it. To unintrusively hook into the virtual functions so that a Python
override may be called, we must use a derived class.
<h2>Pure Virtual Functions</h2>
<p>
A pure virtual function with no implementation is actually a lot easier to
deal with than a virtual function with a default implementation. First of
all, you obviously don't need to <a href="#default_implementation"> supply
a default implementation</a>. Secondly, you don't need to call
<tt>def()</tt> on the <tt>extension_class&lt;&gt;</tt> instance
for the virtual function. In fact, you wouldn't <em>want</em> to: if the
corresponding attribute on the Python class stays undefined, you'll get an
<tt>AttributeError</tt> in Python when you try to call the function,
indicating that it should have been implemented. For example:
<blockquote>
<pre>
struct baz {
<strong>virtual</strong> int pure(int) = 0;
int calls_pure(int x) { return pure(x) + 1000; }
};
struct baz_callback {
int pure(int x) { boost::python::callback&lt;int&gt;::call_method(m_self, "pure", x); }
};
BOOST_PYTHON_MODULE_INIT(foobar)
{
boost::python::module_builder foobar("foobar");
boost::python::class_builder&lt;baz,baz_callback&gt; baz_class("baz");
baz_class.def(&amp;baz::calls_pure, "calls_pure");
}
</pre>
</blockquote>
<p>
Now in Python:
<blockquote>
<pre>
&gt;&gt;&gt; from foobar import baz
&gt;&gt;&gt; x = baz()
&gt;&gt;&gt; x.pure(1)
Traceback (innermost last):
File "&lt;stdin&gt;", line 1, in ?
AttributeError: pure
&gt;&gt;&gt; x.calls_pure(1)
Traceback (innermost last):
File "&lt;stdin&gt;", line 1, in ?
AttributeError: pure
&gt;&gt;&gt; class mumble(baz):
... def pure(self, x): return x + 1
...
&gt;&gt;&gt; y = mumble()
&gt;&gt;&gt; y.pure(99)
100
&gt;&gt;&gt; y.calls_pure(99)
1100
</pre></blockquote>
<a name="private"><h2>Private Non-Pure Virtual Functions</h2></a>
<p>This is one area where some minor intrusiveness on the wrapped library is
required. Once it has been overridden, the only way to call the base class
implementation of a private virtual function is to make the derived class a
friend of the base class. You didn't hear it from me, but most C++
implementations will allow you to change the declaration of the base class in
this limited way without breaking binary compatibility (though it will certainly
break the <a
href="http://cs.calvin.edu/c++/C++Standard-Nov97/basic.html#basic.def.odr">ODR</a>).
<hr>
<p>
Next: <a href="overloading.html">Function Overloading</a>
Previous: <a href="exporting_classes.html">Exporting Classes</a>
Up: <a href="index.html">Top</a>
<p>
&copy; Copyright David Abrahams 2001. Permission to copy, use, modify,
sell and distribute this document is granted provided this copyright
notice appears in all copies. This document is provided "as is" without
express or implied warranty, and with no claim as to its suitability for
any purpose.
<p>
Updated: Mar 21, 2001

272
doc/pickle.html Normal file
View File

@@ -0,0 +1,272 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN"
"http://www.w3.org/TR/REC-html40/strict.dtd">
<title>Boost.Python Pickle Support</title>
<div>
<img src="../../../c++boost.gif"
alt="c++boost.gif (8819 bytes)"
align="center"
width="277" height="86">
<hr>
<h1>Boost.Python Pickle Support</h1>
Pickle is a Python module for object serialization, also known
as persistence, marshalling, or flattening.
<p>
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.
<p>
The Boost Python Library supports the pickle module by emulating the
interface implemented by Jim Fulton's ExtensionClass module that is
included in the
<a href="http://www.zope.org/"
>ZOPE</a>
distribution.
This interface is similar to that for regular Python classes as
described in detail in the
<a href="http://www.python.org/doc/current/lib/module-pickle.html"
>Python Library Reference for pickle.</a>
<hr>
<h2>The Boost.Python Pickle Interface</h2>
At the user level, the Boost.Python pickle interface involves three special
methods:
<dl>
<dt>
<strong><tt>__getinitargs__</tt></strong>
<dd>
When an instance of a Boost.Python extension class is pickled, the
pickler tests if the instance has a <tt>__getinitargs__</tt> 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.
<p>
If <tt>__getinitargs__</tt> is not defined, the class constructor
will be called without arguments.
<p>
<dt>
<strong><tt>__getstate__</tt></strong>
<dd>
When an instance of a Boost.Python extension class is pickled, the
pickler tests if the instance has a <tt>__getstate__</tt> method.
This method should return a Python object representing the state of
the instance.
<p>
If <tt>__getstate__</tt> is not defined, the instance's
<tt>__dict__</tt> is pickled (if it is not empty).
<p>
<dt>
<strong><tt>__setstate__</tt></strong>
<dd>
When an instance of a Boost.Python extension class is restored by the
unpickler, it is first constructed using the result of
<tt>__getinitargs__</tt> as arguments (see above). Subsequently the
unpickler tests if the new instance has a <tt>__setstate__</tt>
method. If so, this method is called with the result of
<tt>__getstate__</tt> (a Python object) as the argument.
<p>
If <tt>__setstate__</tt> is not defined, the result of
<tt>__getstate__</tt> must be a Python dictionary. The items of this
dictionary are added to the instance's <tt>__dict__</tt>.
</dl>
If both <tt>__getstate__</tt> and <tt>__setstate__</tt> are defined,
the Python object returned by <tt>__getstate__</tt> need not be a
dictionary. The <tt>__getstate__</tt> and <tt>__setstate__</tt> methods
can do what they want.
<hr>
<h2>Pitfalls and Safety Guards</h2>
In Boost.Python extension modules with many extension classes,
providing complete pickle support for all classes would be a
significant overhead. In general complete pickle support should only be
implemented for extension classes that will eventually be pickled.
However, the author of a Boost.Python extension module might not
anticipate correctly which classes need support for pickle.
Unfortunately, the pickle protocol described above has two important
pitfalls that the end user of a Boost.Python extension module might not
be aware of:
<dl>
<dt>
<strong>Pitfall 1:</strong>
Both <tt>__getinitargs__</tt> and <tt>__getstate__</tt> are not defined.
<dd>
In this situation the unpickler calls the class constructor without
arguments and then adds the <tt>__dict__</tt> that was pickled by
default to that of the new instance.
<p>
However, most C++ classes wrapped with Boost.Python will have member
data that are not restored correctly by this procedure. To alert the
user to this problem, a safety guard is provided. If both
<tt>__getinitargs__</tt> and <tt>__getstate__</tt> are not defined,
Boost.Python tests if the class has an attribute
<tt>__dict_defines_state__</tt>. An exception is raised if this
attribute is not defined:
<pre>
RuntimeError: Incomplete pickle support (__dict_defines_state__ not set)
</pre>
In the rare cases where this is not the desired behavior, the safety
guard can deliberately be disabled. The corresponding C++ code for
this is, e.g.:
<pre>
class_builder&lt;your_class&gt; py_your_class(your_module, "your_class");
py_your_class.dict_defines_state();
</pre>
It is also possible to override the safety guard at the Python level.
E.g.:
<pre>
import your_bpl_module
class your_class(your_bpl_module.your_class):
__dict_defines_state__ = 1
</pre>
<p>
<dt>
<strong>Pitfall 2:</strong>
<tt>__getstate__</tt> is defined and the instance's <tt>__dict__</tt> is not empty.
<dd>
The author of a Boost.Python extension class might provide a
<tt>__getstate__</tt> method without considering the possibilities
that:
<p>
<ul>
<li>
his class is used in Python as a base class. Most likely the
<tt>__dict__</tt> of instances of the derived class needs to be
pickled in order to restore the instances correctly.
<p>
<li>
the user adds items to the instance's <tt>__dict__</tt> directly.
Again, the <tt>__dict__</tt> of the instance then needs to be
pickled.
</ul>
<p>
To alert the user to this highly unobvious problem, a safety guard is
provided. If <tt>__getstate__</tt> is defined and the instance's
<tt>__dict__</tt> is not empty, Boost.Python tests if the class has
an attribute <tt>__getstate_manages_dict__</tt>. An exception is
raised if this attribute is not defined:
<pre>
RuntimeError: Incomplete pickle support (__getstate_manages_dict__ not set)
</pre>
To resolve this problem, it should first be established that the
<tt>__getstate__</tt> and <tt>__setstate__</tt> methods manage the
instances's <tt>__dict__</tt> correctly. Note that this can be done
both at the C++ and the Python level. Finally, the safety guard
should intentionally be overridden. E.g. in C++:
<pre>
class_builder&lt;your_class&gt; py_your_class(your_module, "your_class");
py_your_class.getstate_manages_dict();
</pre>
In Python:
<pre>
import your_bpl_module
class your_class(your_bpl_module.your_class):
__getstate_manages_dict__ = 1
def __getstate__(self):
# your code here
def __setstate__(self, state):
# your code here
</pre>
</dl>
<hr>
<h2>Practical Advice</h2>
<ul>
<li>
Avoid using <tt>__getstate__</tt> if the instance can also be
reconstructed by way of <tt>__getinitargs__</tt>. This automatically
avoids Pitfall 2.
<p>
<li>
If <tt>__getstate__</tt> is required, include the instance's
<tt>__dict__</tt> in the Python object that is returned.
</ul>
<hr>
<h2>Examples</h2>
There are three files in <tt>boost/libs/python/example</tt> that
show how so provide pickle support.
<h3><a href="../example/pickle1.cpp"><tt>pickle1.cpp</tt></a></h3>
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 <tt>__getinitargs__</tt>.
<h3><a href="../example/pickle2.cpp"><tt>pickle2.cpp</tt></a></h3>
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 <tt>__getstate__</tt>/<tt>__setstate__</tt> pair of
pickle interface methods.
<p>
For simplicity, the <tt>__dict__</tt> is not included in the result
of <tt>__getstate__</tt>. This is not generally recommended, but a
valid approach if it is anticipated that the object's
<tt>__dict__</tt> will always be empty. Note that the safety guards
will catch the cases where this assumption is violated.
<h3><a href="../example/pickle3.cpp"><tt>pickle3.cpp</tt></a></h3>
This example is similar to <a
href="../example/pickle2.cpp"><tt>pickle2.cpp</tt></a>. However, the
object's <tt>__dict__</tt> is included in the result of
<tt>__getstate__</tt>. This requires more code but is unavoidable
if the object's <tt>__dict__</tt> is not always empty.
<hr>
&copy; Copyright Ralf W. Grosse-Kunstleve 2001. Permission to copy,
use, modify, sell and distribute this document is granted provided this
copyright notice appears in all copies. This document is provided "as
is" without express or implied warranty, and with no claim as to its
suitability for any purpose.
<p>
Updated: March 21, 2001
</div>

148
doc/pointers.html Normal file
View File

@@ -0,0 +1,148 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN"
"http://www.w3.org/TR/REC-html40/strict.dtd">
<title>
Pointers
</title>
<div>
<h1>
<img width="277" height="86" id="_x0000_i1025" align="center"
src="../../../c++boost.gif" alt= "c++boost.gif (8819 bytes)">Pointers
</h1>
<h2><a name="problem">The Problem With Pointers</a></h2>
<p>
In general, raw pointers passed to or returned from functions are problematic
for Boost.Python because pointers have too many potential meanings. Is it an iterator?
A pointer to a single element? An array? When used as a return value, is the
caller expected to manage (delete) the pointed-to object or is the pointer
really just a reference? If the latter, what happens to Python references to the
referent when some C++ code deletes it?
<p>
There are a few cases in which pointers are converted automatically:
<ul>
<li>Both const- and non-const pointers to wrapped class instances can be passed
<i>to</i> C++ functions.
<li>Values of type <code>const char*</code> are interpreted as
null-terminated 'C' strings and when passed to or returned from C++ functions are
converted from/to Python strings.
</ul>
<h3>Can you avoid the problem?</h3>
<p>My first piece of advice to anyone with a case not covered above is
``find a way to avoid the problem.'' For example, if you have just one
or two functions that return a pointer to an individual <code>const
T</code>, and <code>T</code> is a wrapped class, you may be able to write a ``thin
converting wrapper'' over those two functions as follows:
<blockquote><pre>
const Foo* f(); // original function
const Foo& f_wrapper() { return *f(); }
...
my_module.def(f_wrapper, "f");
</pre></blockquote>
<p>
Foo must have a public copy constructor for this technique to work, since Boost.Python
converts <code>const T&</code> values <code>to_python</code> by copying the <code>T</code>
value into a new extension instance.
<h2>Dealing with the problem</h2>
<p>The first step in handling the remaining cases is to figure out what the pointer
means. Several potential solutions are provided in the examples that follow:
<h3>Returning a pointer to a wrapped type</h3>
<h4>Returning a const pointer</h4>
<p>If you have lots of functions returning a <code>const T*</code> for some
wrapped <code>T</code>, you may want to provide an automatic
<code>to_python</code> conversion function so you don't have to write lots of
thin wrappers. You can do this simply as follows:
<blockquote><pre>
BOOST_PYTHON_BEGIN_CONVERSION_NAMESPACE // this is a gcc 2.95.2 bug workaround
PyObject* to_python(const Foo* p) {
return to_python(*p); // convert const Foo* in terms of const Foo&
}
BOOST_PYTHON_END_CONVERSION_NAMESPACE
</pre></blockquote>
<h4>If you can't (afford to) copy the referent, or the pointer is non-const</h4>
<p>If the wrapped type doesn't have a public copy constructor, if copying is
<i>extremely</i> costly (remember, we're dealing with Python here), or if the
pointer is non-const and you really need to be able to modify the referent from
Python, you can use the following dangerous trick. Why dangerous? Because python
can not control the lifetime of the referent, so it may be destroyed by your C++
code before the last Python reference to it disappears:
<blockquote><pre>
BOOST_PYTHON_BEGIN_CONVERSION_NAMESPACE // this is a gcc 2.95.2 bug workaround
PyObject* to_python(Foo* p)
{
return boost::python::python_extension_class_converters&lt;Foo&gt;::smart_ptr_to_python(p);
}
PyObject* to_python(const Foo* p)
{
return to_python(const_cast&lt;Foo*&gt;(p));
}
BOOST_PYTHON_END_CONVERSION_NAMESPACE
</pre></blockquote>
This will cause the Foo* to be treated as though it were an owning smart
pointer, even though it's not. Be sure you don't use the reference for anything
from Python once the pointer becomes invalid, though. Don't worry too much about
the <code>const_cast&lt;&gt;</code> above: Const-correctness is completely lost
to Python anyway!
<h3>[In/]Out Parameters and Immutable Types</h3>
<p>If you have an interface that uses non-const pointers (or references) as
in/out parameters to types which in Python are immutable (e.g. int, string),
there simply is <i>no way</i> to get the same interface in Python. You must
resort to transforming your interface with simple thin wrappers as shown below:
<blockquote><pre>
const void f(int* in_out_x); // original function
const int f_wrapper(int in_x) { f(in_x); return in_x; }
...
my_module.def(f_wrapper, "f");
</pre></blockquote>
<p>Of course, [in/]out parameters commonly occur only when there is already a
return value. You can handle this case by returning a Python tuple:
<blockquote><pre>
typedef unsigned ErrorCode;
const char* f(int* in_out_x); // original function
...
#include &lt;boost/python/objects.hpp&gt;
const boost::python::tuple f_wrapper(int in_x) {
const char* s = f(in_x);
return boost::python::tuple(s, in_x);
}
...
my_module.def(f_wrapper, "f");
</pre></blockquote>
<p>Now, in Python:
<blockquote><pre>
&gt;&gt;&gt; str,out_x = f(3)
</pre></blockquote>
<p>
Previous: <a href="enums.html">Enums</a>
Up: <a href="index.html">Top</a>
<p>
&copy; Copyright David Abrahams 2000. Permission to copy, use, modify,
sell and distribute this document is granted provided this copyright
notice appears in all copies. This document is provided "as is" without
express or implied warranty, and with no claim as to its suitability
for any purpose.
<p>
Updated: Nov 26, 2000
</div>

106
doc/richcmp.html Normal file
View File

@@ -0,0 +1,106 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN"
"http://www.w3.org/TR/REC-html40/strict.dtd">
<title>Rich Comparisons</title>
<div>
<img src="../../../c++boost.gif"
alt="c++boost.gif (8819 bytes)"
align="center"
width="277" height="86">
<hr>
<h1>Rich Comparisons</h1>
<hr>
In Python versions up to and including Python 2.0, support for
implementing comparisons on user-defined classes and extension types
was quite simple. Classes could implement a <tt>__cmp__</tt> method
that was given two instances of a class as arguments, and could only
return <tt>0</tt> if they were equal or <tt>+1</tt> or <tt>-1</tt> if
they were not. The method could not raise an exception or return
anything other than an integer value.
In Python 2.1, <b>Rich Comparisons</b> were added (see
<a href="http://python.sourceforge.net/peps/pep-0207.html">PEP 207</a>).
Python classes can now individually overload each of the &lt;, &lt;=,
&gt;, &gt;=, ==, and != operations.
<p>
For more detailed information, search for "rich comparison"
<a href="http://www.python.org/doc/current/ref/customization.html"
>here</a>.
<p>
Boost.Python supports both automatic overloading and manual overloading
of the Rich Comparison operators. The <b>compile-time</b> support is
independent of the Python version that is used when compiling
Boost.Python extension modules. That is, <tt>op_lt</tt> for example can
always be used, and the C++ <tt>operator&lt;</tt> will always be bound
to the Python method <tt>__lt__</tt>. However, the <b>run-time</b>
behavior will depend on the Python version.
<p>
With Python versions before 2.1, the Rich Comparison operators will not
be called by Python when any of the six comparison operators
(<tt>&lt;</tt>, <tt>&lt;=</tt>, <tt>==</tt>, <tt>!=</tt>,
<tt>&gt;</tt>, <tt>&gt;=</tt>) is used in an expression. The only way
to access the corresponding methods is to call them explicitly, e.g.
<tt>a.__lt__(b)</tt>. Only with Python versions 2.1 or higher will
expressions like <tt>a &lt; b</tt> work as expected.
<p>
To support Rich Comparisions, the Python C API was modified between
Python versions 2.0 and 2.1. A new slot was introduced in the
<tt>PyTypeObject</tt> structure: <tt>tp_richcompare</tt>. For backwards
compatibility, a flag (<tt>Py_TPFLAGS_HAVE_RICHCOMPARE</tt>) has to be
set to signal to the Python interpreter that Rich Comparisions are
supported by a particular type.
There is only one flag for all the six comparison operators.
When any of the six operators is wrapped automatically or
manually, Boost.Python will set this flag. Attempts to use comparison
operators at the Python level that are not defined at the C++ level
will then lead to an <tt>AttributeError</tt> when the Python 2.1
(or higher) interpreter tries, e.g., <tt>a.__lt__(b)</tt>. That
is, in general all six operators should be supplied. Automatically
wrapped operators and manually wrapped operators can be mixed. For
example:<pre>
boost::python::class_builder&lt;code&gt; py_code(this_module, "code");
py_code.def(boost::python::constructor&lt;&gt;());
py_code.def(boost::python::constructor&lt;int&gt;());
py_code.def(boost::python::operators&lt;( boost::python::op_eq
| boost::python::op_ne)&gt;());
py_code.def(NotImplemented, "__lt__");
py_code.def(NotImplemented, "__le__");
py_code.def(NotImplemented, "__gt__");
py_code.def(NotImplemented, "__ge__");
</pre>
<tt>NotImplemented</tt> is a simple free function that (currently) has
to be provided by the user. For example:<pre>
boost::python::ref
NotImplemented(const code&amp;, const code&amp;) {
return
boost::python::ref(Py_NotImplemented, boost::python::ref::increment_count);
}
</pre>
See also:
<ul>
<li><a href="../example/richcmp1.cpp"><tt>../example/richcmp1.cpp</tt></a>
<li><a href="../example/richcmp2.cpp"><tt>../example/richcmp2.cpp</tt></a>
<li><a href="../example/richcmp3.cpp"><tt>../example/richcmp3.cpp</tt></a>
</ul>
<hr>
&copy; Copyright Nicholas K. Sauter &amp; Ralf W. Grosse-Kunstleve 2001.
Permission to copy, use, modify, sell and distribute this document is
granted provided this copyright notice appears in all copies. This
document is provided "as is" without express or implied warranty, and
with no claim as to its suitability for any purpose.
<p>
Updated: July 2001
</div>

973
doc/special.html Normal file
View File

@@ -0,0 +1,973 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<title>
Special Method and Operator Support
</title>
<div>
<h1>
<img width="277" height="86" id="_x0000_i1025" align="middle" src=
"../../../c++boost.gif" alt="c++boost.gif (8819 bytes)">Special Method and
Operator Support
</h1>
<h2>
Overview
</h2>
<p>
Boost.Python supports all of the standard <a href=
"http://www.python.org/doc/current/ref/specialnames.html">
special method names</a> supported by real Python class instances <em>
except</em> <code>__complex__</code> (more on the reasons <a href=
"#reasons">below</a>). In addition, it can quickly and easily expose
suitable C++ functions and operators as Python operators. The following
categories of special method names are supported:
<ul>
<li><a href="#general">Basic Customization</a>
<li><a href="#numeric">Numeric Operators</a>
<li><a href="#sequence_and_mapping">Sequence and Mapping protocols</a>
<li><a href="#getter_setter">Attribute Getters and Setters</a>
</ul>
<h2><a name="general">Basic Customization</a></h2>
<p>
Python provides a number of special operators for basic customization of a
class. Only a brief description is provided below; more complete
documentation can be found <a
href="http://www.python.org/doc/current/ref/customization.html">here</a>.
<dl>
<dt>
<b><tt class='method'>__init__</tt></b>(<i>self</i>)
<dd>
Initialize the class instance. For extension classes not subclassed in
Python, <code> __init__</code> is defined by
<pre> my_class.def(boost::python::constructor<...>())</pre>
(see section <a href="example1.html">"A Simple Example Using Boost.Python"</a>).<p>
<dt>
<b><tt class='method'>__del__</tt></b>(<i>self</i>)
<dd>
Called when the extension instance is about to be destroyed. For extension classes
not subclassed in Python, <code> __del__</code> is always defined automatically by
means of the class' destructor.
<dt>
<b><tt class='method'>__repr__</tt></b>(<i>self</i>)
<dd>
Create a string representation from which the object can be
reconstructed.
<dt>
<b><tt class='method'>__str__</tt></b>(<i>self</i>)
<dd>
Create a string representation which is suitable for printing.
<dt>
<b><tt class='method'>__lt__</tt></b>(<i>self, other</i>)
<dt>
<b><tt class='method'>__le__</tt></b>(<i>self, other</i>)
<dt>
<b><tt class='method'>__eq__</tt></b>(<i>self, other</i>)
<dt>
<b><tt class='method'>__ne__</tt></b>(<i>self, other</i>)
<dt>
<b><tt class='method'>__gt__</tt></b>(<i>self, other</i>)
<dt>
<b><tt class='method'>__ge__</tt></b>(<i>self, other</i>)
<dd>
Rich Comparison methods.
New in Python 2.1.
See <a href="richcmp.html">Rich Comparisons</a>.
<dt>
<b><tt class='method'>__cmp__</tt></b>(<i>self, other</i>)
<dd>
Three-way compare function.
See <a href="richcmp.html">Rich Comparisons</a>.
<dt>
<b><tt class='method'>__hash__</tt></b>(<i>self</i>)
<dd>
Called for the key object for dictionary operations, and by the
built-in function hash(). Should return a 32-bit integer usable as a
hash value for dictionary operations (only allowed if __cmp__ is also
defined)
<dt>
<b><tt class='method'>__nonzero__</tt></b>(<i>self</i>)
<dd>
called if the object is used as a truth value (e.g. in an if
statement)
<dt>
<b><tt class='method'>__call__</tt></b> (<var>self</var><big>[</big><var>, args...</var><big>]</big>)
<dd>
Called when the instance is ``called'' as a function; if this method
is defined, <code><var>x</var>(arg1, arg2, ...)</code> is a shorthand for
<code><var>x</var>.__call__(arg1, arg2, ...)</code>.
</dl>
If we have a suitable C++ function that supports any of these features,
we can export it like any other function, using its Python special name.
For example, suppose that class <code>Foo</code> provides a string
conversion function:
<blockquote><pre>
std::string to_string(Foo const&amp; f)
{
std::ostringstream s;
s &lt;&lt; f;
return s.str();
}
</pre></blockquote>
This function would be wrapped like this:
<blockquote><pre>
boost::python::class_builder&lt;Foo&gt; foo_class(my_module, "Foo");
foo_class.def(&amp;to_string, "__str__");
</pre></blockquote>
Note that Boost.Python also supports <em>automatic wrapping</em> of
<code>__str__</code> and <code>__cmp__</code>. This is explained in the <a
href="#numeric">next section</a> and the <a href="#numeric_table">Table of
Automatically Wrapped Methods</a>.
<h2><a name="numeric">Numeric Operators</a></h2>
<p>
Numeric operators can be exposed manually, by <code>def</code>ing C++
[member] functions that support the standard Python <a
href="http://www.python.org/doc/current/ref/numeric-types.html">numeric
protocols</a>. This is the same basic technique used to expose
<code>to_string()</code> as <code>__str__()</code> above, and is <a
href="#numeric_manual">covered in detail below</a>. Boost.Python also supports
<i>automatic wrapping</i> of numeric operators whenever they have already
been defined in C++.
<h3><a name="numeric_auto">Exposing C++ Operators Automatically</a></h3>
<p>
Supose we wanted to expose a C++ class
<code>BigNum</code> which supports addition. That is, in C++ we can write:
<blockquote><pre>
BigNum a, b, c;
...
c = a + b;
</pre></blockquote>
<p>
To enable the same functionality in Python, we first wrap the <code>
BigNum</code> class as usual:
<blockquote><pre>
boost::python::class_builder&lt;BigNum&gt; bignum_class(my_module, "BigNum");
bignum_class.def(boost::python::constructor&lt;&gt;());
...
</pre></blockquote>
Then we export the addition operator like this:
<blockquote><pre>
bignum_class.def(boost::python::operators&lt;boost::python::op_add&gt;());
</pre></blockquote>
Since BigNum also supports subtraction, multiplication, and division, we
want to export those also. This can be done in a single command by
``or''ing the operator identifiers together (a complete list of these
identifiers and the corresponding operators can be found in the <a href=
"#numeric_table">Table of Automatically Wrapped Methods</a>):
<blockquote><pre>
bignum_class.def(boost::python::operators&lt;(boost::python::op_sub | boost::python::op_mul | boost::python::op_div)&gt;());
</pre></blockquote>
[Note that the or-expression must be enclosed in parentheses.]
<p>This form of operator definition can be used to wrap unary and
homogeneous binary operators (a <i>homogeneous</i> operator has left and
right operands of the same type). Now suppose that our C++ library also
supports addition of BigNums and plain integers:
<blockquote><pre>
BigNum a, b;
int i;
...
a = b + i;
a = i + b;
</pre></blockquote>
To wrap these heterogeneous operators, we need to specify a different type for
one of the operands. This is done using the <code>right_operand</code>
and <code>left_operand</code> templates:
<blockquote><pre>
bignum_class.def(boost::python::operators&lt;boost::python::op_add&gt;(), boost::python::right_operand&lt;int&gt;());
bignum_class.def(boost::python::operators&lt;boost::python::op_add&gt;(), boost::python::left_operand&lt;int&gt;());
</pre></blockquote>
Boost.Python uses overloading to register several variants of the same
operation (more on this in the context of <a href="#coercion">
coercion</a>). Again, several operators can be exported at once:
<blockquote><pre>
bignum_class.def(boost::python::operators&lt;(boost::python::op_sub | boost::python::op_mul | boost::python::op_div)&gt;(),
boost::python::right_operand&lt;int&gt;());
bignum_class.def(boost::python::operators&lt;(boost::python::op_sub | boost::python::op_mul | boost::python::op_div)&gt;(),
boost::python::left_operand&lt;int&gt;());
</pre></blockquote>
The type of the operand not mentioned is taken from the class being wrapped. In
our example, the class object is <code>bignum_class</code>, and thus the
other operand's type is ``<code>BigNum const&amp;</code>''. You can override
this default by explicitly specifying a type in the <code>
operators</code> template:
<blockquote><pre>
bignum_class.def(boost::python::operators&lt;boost::python::op_add, BigNum&gt;(), boost::python::right_operand&lt;int&gt;());
</pre></blockquote>
<p>
Note that automatic wrapping uses the <em>expression</em>
``<code>left + right</code>'' and can be used uniformly
regardless of whether the C++ operators are supplied as free functions
<blockquote><pre>
BigNum operator+(BigNum, BigNum)
</pre></blockquote>
or as member functions
<blockquote><pre>
BigNum::operator+(BigNum).
</pre></blockquote>
<p>
For the Python built-in functions <code>pow()</code> and
<code>abs()</code>, there is no corresponding C++ operator. Instead,
automatic wrapping attempts to wrap C++ functions of the same name. This
only works if those functions are known in namespace
<code>python</code>. On some compilers (e.g. MSVC) it might be
necessary to add a using declaration prior to wrapping:
<blockquote><pre>
namespace boost { namespace python {
using my_namespace::pow;
using my_namespace::abs;
}
</pre></blockquote>
<h3><a name="numeric_manual">Wrapping Numeric Operators Manually</a></h3>
<p>
In some cases, automatic wrapping of operators may be impossible or
undesirable. Suppose, for example, that the modulo operation for BigNums
is defined by a set of functions called <code>mod()</code>:
<blockquote><pre>
BigNum mod(BigNum const&amp; left, BigNum const&amp; right);
BigNum mod(BigNum const&amp; left, int right);
BigNum mod(int left, BigNum const&amp; right);
</pre></blockquote>
<p>
For automatic wrapping of the modulo function, <code>operator%()</code> would be needed.
Therefore, the <code>mod()</code>-functions must be wrapped manually. That is, we have
to export them explicitly with the Python special name "__mod__":
<blockquote><pre>
bignum_class.def((BigNum (*)(BigNum const&amp;, BigNum const&amp;))&amp;mod, "__mod__");
bignum_class.def((BigNum (*)(BigNum const&amp;, int))&amp;mod, "__mod__");
</pre></blockquote>
<p>
The third form of <code>mod()</code> (with <code>int</code> as left operand) cannot
be wrapped directly. We must first create a function <code>rmod()</code> with the
operands reversed:
<blockquote><pre>
BigNum rmod(BigNum const&amp; right, int left)
{
return mod(left, right);
}
</pre></blockquote>
This function must be wrapped under the name "__rmod__" (standing for "reverse mod"):
<blockquote><pre>
bignum_class.def(&amp;rmod, "__rmod__");
</pre></blockquote>
Many of the possible operator names can be found in the <a href=
"#numeric_table">Table of Automatically Wrapped Methods</a>. Special treatment is
necessary to export the <a href="#ternary_pow">ternary pow</a> operator.
<p>
Automatic and manual wrapping can be mixed arbitrarily. Note that you
cannot overload the same operator for a given extension class on both
``<code>int</code>'' and ``<code>float</code>'', because Python implicitly
converts these types into each other. Thus, the overloaded variant
found first (be it ``<code>int</code>`` or ``<code>float</code>'') will be
used for either of the two types.
<h3><a name="inplace">Inplace Operators</a></h3>
<p>
Boost.Python can also be used to expose inplace numeric operations
(i.e., <code>+=</code> and so forth). These operators must be wrapped
manually, as described in the previous section. For example, suppose
the class BigNum has an <code>operator+=</code>:
<blockquote><pre>
BigNum& operator+= (BigNum const&amp; right);
</pre></blockquote>
This can be exposed by first writing a wrapper function:
<blockquote><pre>
BigNum& iadd (BigNum&amp; self, const BigNum&amp; right)
{
return self += right;
}
</pre></blockquote>
and then exposing the wrapper with
<blockquote><pre>
bignum_class.def(&amp;iadd, "__iadd__");
</pre></blockquote>
<h3><a name="coercion">Coercion</a></h3>
Plain Python can only execute operators with identical types on the left
and right hand side. If it encounters an expression where the types of
the left and right operand differ, it tries to coerce these types to a
common type before invoking the actual operator. Implementing good
coercion functions can be difficult if many type combinations must be
supported.
<p>
Boost.Python solves this problem the same way that C++ does: with <em><a
href="overloading.html">overloading</a></em>. This technique drastically
simplifies the code neccessary to support operators: you just register
operators for all desired type combinations, and Boost.Python automatically
ensures that the correct function is called in each case; there is no
need for user-defined coercion functions. To enable operator
overloading, Boost.Python provides a standard coercion which is <em>implicitly
registered</em> whenever automatic operator wrapping is used.
<p>
If you wrap all operator functions manually, but still want to use
operator overloading, you have to register the standard coercion
function explicitly:
<blockquote><pre>
// this is not necessary if automatic operator wrapping is used
bignum_class.def_standard_coerce();
</pre></blockquote>
If you encounter a situation where you absolutely need a customized
coercion, you can still define the "__coerce__" operator manually. The signature
of a coercion function should look like one of the following (the first is
the safest):
<blockquote><pre>
boost::python::tuple custom_coerce(boost::python::reference left, boost::python::reference right);
boost::python::tuple custom_coerce(PyObject* left, PyObject* right);
PyObject* custom_coerce(PyObject* left, PyObject* right);
</pre></blockquote>
The resulting <code>tuple</code> must contain two elements which
represent the values of <code>left</code> and <code>right</code>
converted to the same type. Such a function is wrapped as usual:
<blockquote><pre>
// this must be called before any use of automatic operator
// wrapping or a call to some_class.def_standard_coerce()
some_class.def(&amp;custom_coerce, "__coerce__");
</pre></blockquote>
Note that the standard coercion (defined by use of automatic
operator wrapping on a <code>class_builder</code> or a call to
<code>class_builder::def_standard_coerce()</code>) will never be applied if
a custom coercion function has been registered. Therefore, in
your coercion function you should call
<blockquote><pre>
boost::python::standard_coerce(left, right);
</pre></blockquote>
for all cases that you don't want to handle yourself.
<h3><a name="ternary_pow">The Ternary <code>pow()</code> Operator</a></h3>
<p>
In addition to the usual binary <code>pow(x, y)</code> operator (meaning
<i>x<sup>y</sup></i>), Python also provides a ternary variant that implements
<i>x<sup>y</sup> <b>mod</b> z</i>, presumably using a more efficient algorithm than
concatenation of power and modulo operators. Automatic operator wrapping
can only be used with the binary variant. Ternary <code>pow()</code> must
always be wrapped manually. For a homgeneous ternary <code>pow()</code>,
this is done as usual:
<blockquote><pre>
BigNum power(BigNum const&amp; first, BigNum const&amp; second, BigNum const&amp; modulus);
typedef BigNum (ternary_function1)(const BigNum&amp;, const BigNum&amp;, const BigNum&amp;);
...
bignum_class.def((ternary_function1)&amp;power, "__pow__");
</pre></blockquote>
If you want to support this function with non-uniform argument
types, wrapping is a little more involved. Suppose you have to wrap:
<blockquote><pre>
BigNum power(BigNum const&amp; first, int second, int modulus);
BigNum power(int first, BigNum const&amp; second, int modulus);
BigNum power(int first, int second, BigNum const&amp; modulus);
</pre></blockquote>
The first variant can be wrapped as usual:
<blockquote><pre>
typedef BigNum (ternary_function2)(const BigNum&amp;, int, int);
bignum_class.def((ternary_function2)&amp;power, "__pow__");
</pre></blockquote>
In the second variant, however, <code>BigNum</code> appears only as second
argument, and in the last one it's the third argument. These functions
must be presented to Boost.Python such that that the <code>BigNum</code>
argument appears in first position:
<blockquote><pre>
BigNum rpower(BigNum const&amp; second, int first, int modulus)
{
return power(first, second, modulus);
}
BigNum rrpower(BigNum const&amp; modulus, int first, int second)
{
return power(first, second, modulus);
}
</pre></blockquote>
<p>These functions must be wrapped under the names "__rpow__" and "__rrpow__"
respectively:
<blockquote><pre>
bignum_class.def((ternary_function2)&amp;rpower, "__rpow__");
bignum_class.def((ternary_function2)&amp;rrpower, "__rrpow__");
</pre></blockquote>
Note that "__rrpow__" is an extension not present in plain Python.
<h2><a name="numeric_table">Table of Automatically Wrapped Methods</a></h2>
<p>
Boost.Python can automatically wrap the following <a href=
"http://www.python.org/doc/current/ref/specialnames.html">
special methods</a>:
<p>
<table summary="special numeric methods" cellpadding="5" border="1"
width="100%">
<tr>
<td align="center">
<b>Python Operator Name</b>
<td align="center">
<b>Python Expression</b>
<td align="center">
<b>C++ Operator Id</b>
<td align="center">
<b>C++ Expression Used For Automatic Wrapping</b><br>
with <code>cpp_left = from_python(left,
type&lt;Left&gt;())</code>,<br>
<code>cpp_right = from_python(right,
type&lt;Right&gt;())</code>,<br>
and <code>cpp_oper = from_python(oper, type&lt;Oper&gt;())</code>
<tr>
<td>
<code>__add__, __radd__</code>
<td>
<code>left + right</code>
<td>
<code>op_add</code>
<td>
<code>cpp_left + cpp_right</code>
<tr>
<td>
<code>__sub__, __rsub__</code>
<td>
<code>left - right</code>
<td>
<code>op_sub</code>
<td>
<code>cpp_left - cpp_right</code>
<tr>
<td>
<code>__mul__, __rmul__</code>
<td>
<code>left * right</code>
<td>
<code>op_mul</code>
<td>
<code>cpp_left * cpp_right</code>
<tr>
<td>
<code>__div__, __rdiv__</code>
<td>
<code>left / right</code>
<td>
<code>op_div</code>
<td>
<code>cpp_left / cpp_right</code>
<tr>
<td>
<code>__mod__, __rmod__</code>
<td>
<code>left % right</code>
<td>
<code>op_mod</code>
<td>
<code>cpp_left % cpp_right</code>
<tr>
<td>
<code>__divmod__, __rdivmod__</code>
<td>
<code>(quotient, remainder)<br>
= divmod(left, right)</code>
<td>
<code>op_divmod</code>
<td>
<code>cpp_left / cpp_right</code>
<br><code>cpp_left % cpp_right</code>
<tr>
<td>
<code>__pow__, __rpow__</code>
<td>
<code>pow(left, right)</code><br>
(binary power)
<td>
<code>op_pow</code>
<td>
<code>pow(cpp_left, cpp_right)</code>
<tr>
<td>
<code>__rrpow__</code>
<td>
<code>pow(left, right, modulo)</code><br>
(ternary power modulo)
<td colspan="2">
no automatic wrapping, <a href="#ternary_pow">special treatment</a>
required
<tr>
<td>
<code>__lshift__, __rlshift__</code>
<td>
<code>left &lt;&lt; right</code>
<td>
<code>op_lshift</code>
<td>
<code>cpp_left &lt;&lt; cpp_right</code>
<tr>
<td>
<code>__rshift__, __rrshift__</code>
<td>
<code>left &gt;&gt; right</code>
<td>
<code>op_rshift</code>
<td>
<code>cpp_left &gt;&gt; cpp_right</code>
<tr>
<td>
<code>__and__, __rand__</code>
<td>
<code>left &amp; right</code>
<td>
<code>op_and</code>
<td>
<code>cpp_left &amp; cpp_right</code>
<tr>
<td>
<code>__xor__, __rxor__</code>
<td>
<code>left ^ right</code>
<td>
<code>op_xor</code>
<td>
<code>cpp_left ^ cpp_right</code>
<tr>
<td>
<code>__or__, __ror__</code>
<td>
<code>left | right</code>
<td>
<code>op_or</code>
<td>
<code>cpp_left | cpp_right</code>
<tr>
<td>
<code>__cmp__, __rcmp__</code>
<td>
<code>cmp(left, right)</code><br>
<br>See <a href="richcmp.html">Rich Comparisons</a>.
<td>
<code>op_cmp</code>
<td>
<code>cpp_left &lt; cpp_right </code>
<br><code>cpp_right &lt; cpp_left</code>
<tr>
<td>
<code>__lt__</code>
<br><code>__le__</code>
<br><code>__eq__</code>
<br><code>__ne__</code>
<br><code>__gt__</code>
<br><code>__ge__</code>
<td>
<code>left &lt; right</code>
<br><code>left &lt;= right</code>
<br><code>left == right</code>
<br><code>left != right</code>
<br><code>left &gt; right</code>
<br><code>left &gt;= right</code>
<br>See <a href="richcmp.html">Rich Comparisons</a>
<td>
<code>op_lt</code>
<br><code>op_le</code>
<br><code>op_eq</code>
<br><code>op_ne</code>
<br><code>op_gt</code>
<br><code>op_ge</code>
<td>
<code>cpp_left &lt; cpp_right </code>
<br><code>cpp_left &lt;= cpp_right </code>
<br><code>cpp_left == cpp_right </code>
<br><code>cpp_left != cpp_right </code>
<br><code>cpp_left &gt; cpp_right </code>
<br><code>cpp_left &gt;= cpp_right </code>
<tr>
<td>
<code>__neg__</code>
<td>
<code>-oper </code> (unary negation)
<td>
<code>op_neg</code>
<td>
<code>-cpp_oper</code>
<tr>
<td>
<code>__pos__</code>
<td>
<code>+oper </code> (identity)
<td>
<code>op_pos</code>
<td>
<code>+cpp_oper</code>
<tr>
<td>
<code>__abs__</code>
<td>
<code>abs(oper) </code> (absolute value)
<td>
<code>op_abs</code>
<td>
<code>abs(cpp_oper)</code>
<tr>
<td>
<code>__invert__</code>
<td>
<code>~oper </code> (bitwise inversion)
<td>
<code>op_invert</code>
<td>
<code>~cpp_oper</code>
<tr>
<td>
<code>__int__</code>
<td>
<code>int(oper) </code> (integer conversion)
<td>
<code>op_int</code>
<td>
<code>long(cpp_oper)</code>
<tr>
<td>
<code>__long__</code>
<td>
<code>long(oper) </code><br>
(infinite precision integer conversion)
<td>
<code>op_long</code>
<td>
<code>PyLong_FromLong(cpp_oper)</code>
<tr>
<td>
<code>__float__</code>
<td>
<code>float(oper) </code> (float conversion)
<td>
<code>op_float</code>
<td>
<code>double(cpp_oper)</code>
<tr>
<td>
<code>__str__</code>
<td>
<code>str(oper) </code> (string conversion)
<td>
<code>op_str</code>
<td>
<code>std::ostringstream s; s &lt;&lt; oper;</code>
<tr>
<td>
<code>__coerce__</code>
<td>
<code>coerce(left, right)</code>
<td colspan="2">
usually defined automatically, otherwise <a href="#coercion">
special treatment</a> required
</table>
<h2><a name="sequence_and_mapping">Sequence and Mapping Operators</a></h2>
<p>
Sequence and mapping operators let wrapped objects behave in accordance
to Python's iteration and access protocols. These protocols differ
considerably from the ones found in C++. For example, Python's typical
iteration idiom looks like
<blockquote><pre>
for i in S:
</pre></blockquote>
while in C++ one writes
<blockquote><pre>
for (iterator i = S.begin(), end = S.end(); i != end; ++i)
</pre></blockquote>
<p>One could try to wrap C++ iterators in order to carry the C++ idiom into
Python. However, this does not work very well because
<ol>
<li>It leads to
non-uniform Python code (wrapped sequences support a usage different from
Python built-in sequences) and
<li>Iterators (e.g. <code>std::vector::iterator</code>) are often implemented as plain C++
pointers which are <a href="pointers.html#problem">problematic</a> for any automatic
wrapping system.
</ol>
<p>
It is a better idea to support the standard <a
href="http://www.python.org/doc/current/ref/sequence-types.html">Python
sequence and mapping protocols</a> for your wrapped containers. These
operators have to be wrapped manually because there are no corresponding
C++ operators that could be used for automatic wrapping. The Python
documentation lists the relevant <a href=
"http://www.python.org/doc/current/ref/sequence-types.html">
container operators</a>. In particular, expose __getitem__, __setitem__
and remember to raise the appropriate Python exceptions
(<code>PyExc_IndexError</code> for sequences,
<code>PyExc_KeyError</code> for mappings) when the requested item is not
present.
<p>
In the following example, we expose <code>std::map&lt;std::size_t,std::string&gt;</code>:
<blockquote>
<pre>
typedef std::map&lt;std::size_t, std::string&gt; StringMap;
// A helper function for dealing with errors. Throw a Python exception
// if p == m.end().
void throw_key_error_if_end(
const StringMap&amp; m,
StringMap::const_iterator p,
std::size_t key)
{
if (p == m.end())
{
PyErr_SetObject(PyExc_KeyError, boost::python::converters::to_python(key));
boost::python::throw_error_already_set();
}
}
// Define some simple wrapper functions which match the Python protocol
// for __getitem__, __setitem__, and __delitem__. Just as in Python, a
// free function with a ``self'' first parameter makes a fine class method.
const std::string&amp; get_item(const StringMap&amp; self, std::size_t key)
{
const StringMap::const_iterator p = self.find(key);
throw_key_error_if_end(self, p, key);
return p-&gt;second;
}
// Sets the item corresponding to key in the map.
void StringMapPythonClass::set_item(StringMap&amp; self, std::size_t key, const std::string&amp; value)
{
self[key] = value;
}
// Deletes the item corresponding to key from the map.
void StringMapPythonClass::del_item(StringMap&amp; self, std::size_t key)
{
const StringMap::iterator p = self.find(key);
throw_key_error_if_end(self, p, key);
self.erase(p);
}
class_builder&lt;StringMap&gt; string_map(my_module, "StringMap");
string_map.def(boost::python::constructor&lt;&gt;());
string_map.def(&amp;StringMap::size, "__len__");
string_map.def(get_item, "__getitem__");
string_map.def(set_item, "__setitem__");
string_map.def(del_item, "__delitem__");
</pre>
</blockquote>
<p>
Then in Python:
<blockquote>
<pre>
&gt;&gt;&gt; m = StringMap()
&gt;&gt;&gt; m[1]
Traceback (innermost last):
File "&lt;stdin&gt;", line 1, in ?
KeyError: 1
&gt;&gt;&gt; m[1] = 'hello'
&gt;&gt;&gt; m[1]
'hello'
&gt;&gt;&gt; del m[1]
&gt;&gt;&gt; m[1] # prove that it's gone
Traceback (innermost last):
File "&lt;stdin&gt;", line 1, in ?
KeyError: 1
&gt;&gt;&gt; del m[2]
Traceback (innermost last):
File "&lt;stdin&gt;", line 1, in ?
KeyError: 2
&gt;&gt;&gt; len(m)
0
&gt;&gt;&gt; m[0] = 'zero'
&gt;&gt;&gt; m[1] = 'one'
&gt;&gt;&gt; m[2] = 'two'
&gt;&gt;&gt; m[3] = 'three'
&gt;&gt;&gt; len(m)
4
</pre>
</blockquote>
<h2><a name="getter_setter">Customized Attribute Access</a></h2>
<p>
Just like built-in Python classes, Boost.Python extension classes support <a
href="http://www.python.org/doc/current/ref/attribute-access.html">special
the usual attribute access methods</a> <code>__getattr__</code>,
<code>__setattr__</code>, and <code>__delattr__</code>.
Because writing these functions can
be tedious in the common case where the attributes being accessed are
known statically, Boost.Python checks the special names
<ul>
<li>
<code>__getattr__<em>&lt;name&gt;</em>__</code>
<li>
<code>__setattr__<em>&lt;name&gt;</em>__</code>
<li>
<code>__delattr__<em>&lt;name&gt;</em>__</code>
</ul>
to provide functional access to the attribute <em>&lt;name&gt;</em>. This
facility can be used from C++ or entirely from Python. For example, the
following shows how we can implement a ``computed attribute'' in Python:
<blockquote>
<pre>
&gt;&gt;&gt; class Range(AnyBoost.PythonExtensionClass):
... def __init__(self, start, end):
... self.start = start
... self.end = end
... def __getattr__length__(self):
... return self.end - self.start
...
&gt;&gt;&gt; x = Range(3, 9)
&gt;&gt;&gt; x.length
6
</pre>
</blockquote>
<h4>
Direct Access to Data Members
</h4>
<p>
Boost.Python uses the special <code>
__xxxattr__<em>&lt;name&gt;</em>__</code> functionality described above
to allow direct access to data members through the following special
functions on <code>class_builder&lt;&gt;</code> and <code>
extension_class&lt;&gt;</code>:
<ul>
<li>
<code>def_getter(<em>pointer-to-member</em>, <em>name</em>)</code> //
read access to the member via attribute <em>name</em>
<li>
<code>def_setter(<em>pointer-to-member</em>, <em>name</em>)</code> //
write access to the member via attribute <em>name</em>
<li>
<code>def_readonly(<em>pointer-to-member</em>, <em>name</em>)</code>
// read-only access to the member via attribute <em>name</em>
<li>
<code>def_read_write(<em>pointer-to-member</em>, <em>
name</em>)</code> // read/write access to the member via attribute
<em>name</em>
</ul>
<p>
Note that the first two functions, used alone, may produce surprising
behavior. For example, when <code>def_getter()</code> is used, the
default functionality for <code>setattr()</code> and <code>
delattr()</code> remains in effect, operating on items in the extension
instance's name-space (i.e., its <code>__dict__</code>). For that
reason, you'll usually want to stick with <code>def_readonly</code> and
<code>def_read_write</code>.
<p>
For example, to expose a <code>std::pair&lt;int,long&gt;</code> we
might write:
<blockquote>
<pre>
typedef std::pair&lt;int,long&gt; Pil;
int first(const Pil&amp; x) { return x.first; }
long second(const Pil&amp; x) { return x.second; }
...
my_module.def(first, "first");
my_module.def(second, "second");
class_builder&lt;Pil&gt; pair_int_long(my_module, "Pair");
pair_int_long.def(boost::python::constructor&lt;&gt;());
pair_int_long.def(boost::python::constructor&lt;int,long&gt;());
pair_int_long.def_read_write(&amp;Pil::first, "first");
pair_int_long.def_read_write(&amp;Pil::second, "second");
</pre>
</blockquote>
<p>
Now your Python class has attributes <code>first</code> and <code>
second</code> which, when accessed, actually modify or reflect the
values of corresponding data members of the underlying C++ object. Now
in Python:
<blockquote>
<pre>
&gt;&gt;&gt; x = Pair(3,5)
&gt;&gt;&gt; x.first
3
&gt;&gt;&gt; x.second
5
&gt;&gt;&gt; x.second = 8
&gt;&gt;&gt; x.second
8
&gt;&gt;&gt; second(x) # Prove that we're not just changing the instance __dict__
8
</pre>
</blockquote>
<h2>
<a name="reasons">And what about <code>__complex__</code>?</a>
</h2>
<p>
That, dear reader, is one problem we don't know how to solve. The
Python source contains the following fragment, indicating the
special-case code really is hardwired:
<blockquote>
<pre>
/* XXX Hack to support classes with __complex__ method */
if (PyInstance_Check(r)) { ...
</pre>
</blockquote>
<p>
Next: <a href="under-the-hood.html">A Peek Under the Hood</a>
Previous: <a href="inheritance.html">Inheritance</a>
Up: <a href= "index.html">Top</a>
<p>
&copy; Copyright David Abrahams and Ullrich K&ouml;the 2000.
Permission to copy, use, modify, sell and distribute this document is
granted provided this copyright notice appears in all copies. This
document is provided ``as is'' without express or implied
warranty, and with no claim as to its suitability for any purpose.
<p>
Updated: Nov 26, 2000
</div>

61
doc/under-the-hood.html Normal file
View File

@@ -0,0 +1,61 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<title>
A Peek Under the Hood
</title>
<h1>
<img src="../../../c++boost.gif" alt="c++boost.gif (8819 bytes)" align="center"
width="277" height="86">
</h1>
<h1>
A Peek Under the Hood
</h1>
<p>
Declaring a <code>class_builder&lt;T&gt;</code> causes the instantiation
of an <code>extension_class&lt;T&gt;</code> to which it forwards all
member function calls and which is doing most of the real work.
<code>extension_class&lt;T&gt;</code> is a subclass of <code>
PyTypeObject</code>, the <code> struct</code> which Python's 'C' API uses
to describe a type. <a href="example1.html#world_class">An instance of the
<code>extension_class&lt;&gt;</code></a> becomes the Python type object
corresponding to <code>hello::world</code>. When we <a href=
"example1.html#add_world_class">add it to the module</a> it goes into the
module's dictionary to be looked up under the name "world".
<p>
Boost.Python uses C++'s template argument deduction mechanism to determine the
types of arguments to functions (except constructors, for which we must
<a href="example1.html#Constructor_example">provide an argument list</a>
because they can't be named in C++). Then, it calls the appropriate
overloaded functions <code>PyObject*
to_python(</code><em>S</em><code>)</code> and <em>
S'</em><code>from_python(PyObject*,
type&lt;</code><em>S</em><code>&gt;)</code> which convert between any C++
type <em>S</em> and a <code>PyObject*</code>, the type which represents a
reference to any Python object in its 'C' API. The <a href=
"example1.html#world_class"><code>extension_class&lt;T&gt;</code></a>
template defines a whole raft of these conversions (for <code>T, T*,
T&amp;, std::auto_ptr&lt;T&gt;</code>, etc.), using the same inline
friend function technique employed by <a href="../../utility/operators.htm">the boost operators
library</a>.
<p>
Because the <code>to_python</code> and <code>from_python</code> functions
for a user-defined class are defined by <code>
extension_class&lt;T&gt;</code>, it is important that an instantiation of
<code> extension_class&lt;T&gt;</code> is visible to any code which wraps
a C++ function with a <code>T, T*, const T&amp;</code>, etc. parameter or
return value. In particular, you may want to create all of the classes at
the top of your module's init function, then <code>def</code> the member
functions later to avoid problems with inter-class dependencies.
<p>
Next: <a href="building.html">Building a Module with Boost.Python</a>
Previous: <a href="special.html">Special Method and Operator Support</a>
Up: <a href="index.html">Top</a>
<p>
&copy; Copyright David Abrahams 2000. Permission to copy, use, modify,
sell and distribute this document is granted provided this copyright
notice appears in all copies. This document is provided "as is" without
express or implied warranty, and with no claim as to its suitability for
any purpose.
<p>
Updated: Nov 26, 2000

62
include/boost/python.hpp
View File

@@ -1,62 +0,0 @@
// Copyright David Abrahams 2002. Permission to copy, use,
// modify, sell and distribute this software is granted provided this
// copyright notice appears in all copies. This software is provided
// "as is" without express or implied warranty, and with no claim as
// to its suitability for any purpose.
#ifndef PYTHON_DWA2002810_HPP
# define PYTHON_DWA2002810_HPP
# include <boost/python/args.hpp>
# include <boost/python/args_fwd.hpp>
# include <boost/python/back_reference.hpp>
# include <boost/python/bases.hpp>
# include <boost/python/borrowed.hpp>
# include <boost/python/call.hpp>
# include <boost/python/call_method.hpp>
# include <boost/python/class.hpp>
# include <boost/python/copy_const_reference.hpp>
# include <boost/python/copy_non_const_reference.hpp>
# include <boost/python/data_members.hpp>
# include <boost/python/def.hpp>
# include <boost/python/default_call_policies.hpp>
# include <boost/python/dict.hpp>
# include <boost/python/enum.hpp>
# include <boost/python/errors.hpp>
# include <boost/python/exception_translator.hpp>
# include <boost/python/extract.hpp>
# include <boost/python/handle.hpp>
# include <boost/python/has_back_reference.hpp>
# include <boost/python/implicit.hpp>
# include <boost/python/init.hpp>
# include <boost/python/instance_holder.hpp>
# include <boost/python/iterator.hpp>
# include <boost/python/list.hpp>
# include <boost/python/long.hpp>
# include <boost/python/lvalue_from_pytype.hpp>
# include <boost/python/make_function.hpp>
# include <boost/python/manage_new_object.hpp>
# include <boost/python/module.hpp>
# include <boost/python/numeric.hpp>
# include <boost/python/object.hpp>
# include <boost/python/object_protocol.hpp>
# include <boost/python/object_protocol_core.hpp>
# include <boost/python/operators.hpp>
# include <boost/python/other.hpp>
# include <boost/python/overloads.hpp>
# include <boost/python/pointee.hpp>
# include <boost/python/ptr.hpp>
# include <boost/python/reference_existing_object.hpp>
# include <boost/python/return_internal_reference.hpp>
# include <boost/python/return_value_policy.hpp>
# include <boost/python/scope.hpp>
# include <boost/python/self.hpp>
# include <boost/python/slice_nil.hpp>
# include <boost/python/str.hpp>
# include <boost/python/to_python_converter.hpp>
# include <boost/python/to_python_indirect.hpp>
# include <boost/python/to_python_value.hpp>
# include <boost/python/tuple.hpp>
# include <boost/python/type_id.hpp>
# include <boost/python/with_custodian_and_ward.hpp>
#endif PYTHON_DWA2002810_HPP

3
include/boost/python/converter/rvalue_from_python_data.hpp
View File

@@ -94,8 +94,7 @@ struct rvalue_from_python_data : rvalue_from_python_storage<T>
{
# if (!defined(__MWERKS__) || __MWERKS__ >= 0x3000) \
&& (!defined(__EDG_VERSION__) || __EDG_VERSION__ >= 245) \
&& (!defined(__DECCXX_VER) || __DECCXX_VER > 60590014) \
&& !(defined(__APPLE__) && defined(__MACH__) && __APPLE_CC__ <= 1161)
&& (!defined(__DECCXX_VER) || __DECCXX_VER > 60590014)
// This must always be a POD struct with m_data its first member.
BOOST_STATIC_ASSERT(BOOST_PYTHON_OFFSETOF(rvalue_from_python_storage<T>,stage1) == 0);
# endif

2
include/boost/python/errors.hpp
View File

@@ -46,9 +46,11 @@ inline T* expect_non_null(T* x)
return x;
}
# ifdef BOOST_PYTHON_V2
// Return source if it is an instance of pytype; throw an appropriate
// exception otherwise.
BOOST_PYTHON_DECL PyObject* pytype_check(PyTypeObject* pytype, PyObject* source);
# endif
}} // namespace boost::python

12
include/boost/python/init.hpp
View File

@@ -138,16 +138,16 @@ struct init_base
init_base(char const* doc_, detail::keyword_range const& keywords_)
: m_doc(doc_), m_keywords(keywords_)
{}
init_base(char const* doc_)
: m_doc(doc_)
{}
DerivedT const& derived() const
{
return *static_cast<DerivedT const*>(this);
}
char const* doc_string() const
{
return m_doc;
@@ -162,7 +162,7 @@ struct init_base
{
return default_call_policies();
}
private: // data members
char const* m_doc;
detail::keyword_range m_keywords;
@@ -192,7 +192,7 @@ class init_with_call_policies
{
return this->m_policies;
}
private: // data members
CallPoliciesT m_policies;
};
@@ -355,7 +355,7 @@ namespace detail
if (keywords.second > keywords.first)
--keywords.second;
typename mpl::pop_front<ReversedArgs>::type next;
define_class_init_helper<N-1>::apply(cl, policies, next, doc, keywords);
}

837
include/boost/python/operators.hpp
View File

@@ -1,332 +1,555 @@
// Copyright David Abrahams 2002. Permission to copy, use,
// modify, sell and distribute this software is granted provided this
// copyright notice appears in all copies. This software is provided
// "as is" without express or implied warranty, and with no claim as
// to its suitability for any purpose.
#ifndef OPERATORS_DWA2002530_HPP
# define OPERATORS_DWA2002530_HPP
// (C) Copyright Ullrich Koethe and David Abrahams 2000-2001. Permission to
// copy, use, modify, sell and distribute this software is granted provided
// this copyright notice appears in all copies. This software is provided "as
// is" without express or implied warranty, and with no claim as to its
// suitability for any purpose.
//
// The authors gratefully acknowlege the support of Dragon Systems, Inc., in
// producing this work.
//
// Revision History:
// 23 Jan 2001 - Another stupid typo fix by Ralf W. Grosse-Kunstleve (David Abrahams)
// 20 Jan 2001 - Added a fix from Ralf W. Grosse-Kunstleve (David Abrahams)
#ifndef OPERATORS_UK112000_H_
# define OPERATORS_UK112000_H_
# ifdef BOOST_PYTHON_V2
# include <boost/python/detail/wrap_python.hpp>
# include <boost/python/converter/arg_to_python.hpp>
# include <boost/python/detail/operator_id.hpp>
# include <boost/python/detail/not_specified.hpp>
# include <boost/python/back_reference.hpp>
# include <boost/mpl/if.hpp>
# include <boost/python/self.hpp>
# include <boost/python/other.hpp>
# include <boost/lexical_cast.hpp>
# include <boost/python/refcount.hpp>
# include <string>
# include <complex>
# include <boost/python/operators2.hpp>
namespace boost { namespace python {
# else
# include <boost/python/reference.hpp>
# include <boost/python/detail/functions.hpp>
// When STLport is used with native streams, _STL::ostringstream().str() is not
// _STL::string, but std::string. This confuses to_python(), so we'll use
// strstream instead. Also, GCC 2.95.2 doesn't have sstream.
# if defined(__SGI_STL_PORT) ? defined(__SGI_STL_OWN_IOSTREAMS) : (!defined(__GNUC__) || __GNUC__ > 2)
# define BOOST_PYTHON_USE_SSTREAM
# endif
# if defined(BOOST_PYTHON_USE_SSTREAM)
# include <sstream>
# else
# include <strstream>
# endif
namespace boost { namespace python {
BOOST_PYTHON_DECL tuple standard_coerce(ref l, ref r);
namespace detail {
// helper class for automatic operand type detection
// during operator wrapping.
struct auto_operand {};
}
// Define operator ids that can be or'ed together
// (boost::python::op_add | boost::python::op_sub | boost::python::op_mul).
// This allows to wrap several operators in one line.
enum operator_id
{
op_add = 0x1,
op_sub = 0x2,
op_mul = 0x4,
op_div = 0x8,
op_mod = 0x10,
op_divmod =0x20,
op_pow = 0x40,
op_lshift = 0x80,
op_rshift = 0x100,
op_and = 0x200,
op_xor = 0x400,
op_or = 0x800,
op_neg = 0x1000,
op_pos = 0x2000,
op_abs = 0x4000,
op_invert = 0x8000,
op_int = 0x10000,
op_long = 0x20000,
op_float = 0x40000,
op_str = 0x80000,
op_cmp = 0x100000,
op_gt = 0x200000,
op_ge = 0x400000,
op_lt = 0x800000,
op_le = 0x1000000,
op_eq = 0x2000000,
op_ne = 0x4000000
};
// Wrap the operators given by "which". Usage:
// foo_class.def(boost::python::operators<(boost::python::op_add | boost::python::op_sub)>());
template <long which, class operand = boost::python::detail::auto_operand>
struct operators {};
// Wrap heterogeneous operators with given left operand type. Usage:
// foo_class.def(boost::python::operators<(boost::python::op_add | boost::python::op_sub)>(),
// boost::python::left_operand<int>());
template <class T>
struct left_operand {};
// Wrap heterogeneous operators with given right operand type. Usage:
// foo_class.def(boost::python::operators<(boost::python::op_add | boost::python::op_sub)>(),
// boost::python::right_operand<int>());
template <class T>
struct right_operand {};
namespace detail
{
// This is essentially the old v1 to_python(). It will be eliminated
// once the public interface for to_python is settled on.
template <class T>
PyObject* convert_result(T const& x)
template <class Specified>
struct operand_select
{
return converter::arg_to_python<T>(x).release();
}
template <class wrapped_type>
struct wrapped
{
typedef Specified type;
};
};
// Operator implementation template declarations. The nested apply
// declaration here keeps MSVC6 happy.
template <operator_id> struct operator_l
template <>
struct operand_select<auto_operand>
{
template <class L, class R> struct apply;
template <class wrapped_type>
struct wrapped
{
typedef const wrapped_type& type;
};
};
template <long> struct define_operator;
// Base class which grants access to extension_class_base::add_method() to its derived classes
struct add_operator_base
{
protected:
static inline void add_method(extension_class_base* target, function* method, const char* name)
{ target->add_method(method, name); }
};
//
// choose_op, choose_unary_op, and choose_rop
//
// These templates use "poor man's partial specialization" to generate the
// appropriate add_method() call (if any) for a given operator and argument set.
//
// Usage:
// choose_op<(which & op_add)>::template args<left_t,right_t>::add(ext_class);
//
// (see extension_class<>::def_operators() for more examples).
//
template <long op_selector>
struct choose_op
{
template <class Left, class Right = Left>
struct args : add_operator_base
{
static inline void add(extension_class_base* target)
{
typedef define_operator<op_selector> def_op;
add_method(target,
new typename def_op::template operator_function<Left, Right>(),
def_op::name());
}
};
};
// specialization for 0 has no effect
template <>
struct choose_op<0>
{
template <class Left, class Right = Left>
struct args
{
static inline void add(extension_class_base*)
{
}
};
};
template <operator_id> struct operator_r
template <long op_selector>
struct choose_unary_op
{
template <class L, class R> struct apply;
};
template <operator_id> struct operator_1
{
template <class T> struct apply;
};
// MSVC6 doesn't want us to do this sort of inheritance on a nested
// class template, so we use this layer of indirection to avoid
// ::template<...> on the nested apply functions below
template <operator_id id, class L, class R>
struct operator_l_inner
: operator_l<id>::template apply<L,R>
{};
template <operator_id id, class L, class R>
struct operator_r_inner
: operator_r<id>::template apply<L,R>
{};
template <operator_id id, class T>
struct operator_1_inner
: operator_1<id>::template apply<T>
{};
// Define three different binary_op templates which take care of
// these cases:
// self op self
// self op R
// L op self
//
// The inner apply metafunction is used to adjust the operator to
// the class type being defined. Inheritance of the outer class is
// simply used to provide convenient access to the operation's
// name().
// self op self
template <operator_id id>
struct binary_op : operator_l<id>
{
template <class T>
struct apply : operator_l_inner<id,T,T>
template <class Operand>
struct args : add_operator_base
{
static inline void add(extension_class_base* target)
{
typedef define_operator<op_selector> def_op;
add_method(target,
new typename def_op::template operator_function<Operand>(),
def_op::name());
}
};
};
// self op R
template <operator_id id, class R>
struct binary_op_l : operator_l<id>
{
template <class T>
struct apply : operator_l_inner<id,T,R>
{
};
};
// L op self
template <operator_id id, class L>
struct binary_op_r : operator_r<id>
{
template <class T>
struct apply : operator_r_inner<id,L,T>
{
};
};
template <operator_id id>
struct unary_op : operator_1<id>
{
template <class T>
struct apply : operator_1_inner<id,T>
{
};
};
// This type is what actually gets returned from operators used on
// self_t
template <operator_id id, class L = not_specified, class R = not_specified>
struct operator_
: mpl::if_<
is_same<L,self_t>
, typename mpl::if_<
is_same<R,self_t>
, binary_op<id>
, binary_op_l<id,typename unwrap_other<R>::type>
>::type
, typename mpl::if_<
is_same<L,not_specified>
, unary_op<id>
, binary_op_r<id,typename unwrap_other<L>::type>
>::type
>::type
{
};
}
# define BOOST_PYTHON_BINARY_OPERATION(id, rid, expr) \
namespace detail \
{ \
template <> \
struct operator_l<op_##id> \
{ \
template <class L, class R> \
struct apply \
{ \
static inline PyObject* execute(L const& l, R const& r) \
{ \
return detail::convert_result(expr); \
} \
}; \
static char const* name() { return "__" #id "__"; } \
}; \
\
template <> \
struct operator_r<op_##id> \
{ \
template <class L, class R> \
struct apply \
{ \
static inline PyObject* execute(R const& r, L const& l) \
{ \
return detail::convert_result(expr); \
} \
}; \
static char const* name() { return "__" #rid "__"; } \
}; \
}
# define BOOST_PYTHON_BINARY_OPERATOR(id, rid, op) \
BOOST_PYTHON_BINARY_OPERATION(id, rid, l op r) \
namespace self_ns \
{ \
template <class L, class R> \
inline detail::operator_<detail::op_##id,L,R> \
operator##op(L const&, R const&) \
{ \
return detail::operator_<detail::op_##id,L,R>(); \
} \
}
BOOST_PYTHON_BINARY_OPERATOR(add, radd, +)
BOOST_PYTHON_BINARY_OPERATOR(sub, rsub, -)
BOOST_PYTHON_BINARY_OPERATOR(mul, rmul, *)
BOOST_PYTHON_BINARY_OPERATOR(div, rdiv, /)
BOOST_PYTHON_BINARY_OPERATOR(mod, rmod, %)
BOOST_PYTHON_BINARY_OPERATOR(lshift, rlshift, <<)
BOOST_PYTHON_BINARY_OPERATOR(rshift, rrshift, >>)
BOOST_PYTHON_BINARY_OPERATOR(and, rand, &)
BOOST_PYTHON_BINARY_OPERATOR(xor, rxor, ^)
BOOST_PYTHON_BINARY_OPERATOR(or, ror, |)
BOOST_PYTHON_BINARY_OPERATOR(gt, lt, >)
BOOST_PYTHON_BINARY_OPERATOR(ge, le, >=)
BOOST_PYTHON_BINARY_OPERATOR(lt, gt, <)
BOOST_PYTHON_BINARY_OPERATOR(le, ge, <=)
BOOST_PYTHON_BINARY_OPERATOR(eq, eq, ==)
BOOST_PYTHON_BINARY_OPERATOR(ne, ne, !=)
# undef BOOST_PYTHON_BINARY_OPERATOR
// pow isn't an operator in C++; handle it specially.
BOOST_PYTHON_BINARY_OPERATION(pow, rpow, pow(l,r))
# undef BOOST_PYTHON_BINARY_OPERATION
namespace self_ns
{
# ifndef BOOST_NO_ARGUMENT_DEPENDENT_LOOKUP
template <class L, class R>
inline detail::operator_<detail::op_pow,L,R>
pow(L const&, R const&)
// specialization for 0 has no effect
template <>
struct choose_unary_op<0>
{
return detail::operator_<detail::op_pow,L,R>();
}
# else
// When there's no argument-dependent lookup, we need these
// overloads to handle the case when everything is imported into the
// global namespace. Note that the plain overload below does /not/
// take const& arguments. This is needed by MSVC6 at least, or it
// complains of ambiguities, since there's no partial ordering.
inline detail::operator_<detail::op_pow,self_t,self_t>
pow(self_t, self_t)
template <class Operand>
struct args
{
static inline void add(extension_class_base*)
{
}
};
};
template <long op_selector>
struct choose_rop
{
return detail::operator_<detail::op_pow,self_t,self_t>();
}
template <class R>
inline detail::operator_<detail::op_pow,self_t,R>
pow(self_t const&, R const&)
template <class Left, class Right = Left>
struct args : add_operator_base
{
static inline void add(extension_class_base* target)
{
typedef define_operator<op_selector> def_op;
add_method(target,
new typename def_op::template roperator_function<Right, Left>(),
def_op::rname());
}
};
};
// specialization for 0 has no effect
template <>
struct choose_rop<0>
{
return detail::operator_<detail::op_pow,self_t,R>();
}
template <class L>
inline detail::operator_<detail::op_pow,L,self_t>
pow(L const&, self_t const&)
{
return detail::operator_<detail::op_pow,L,self_t>();
}
# endif
}
template <class Left, class Right = Left>
struct args
{
static inline void add(extension_class_base*)
{
}
};
};
# define BOOST_PYTHON_INPLACE_OPERATOR(id, op) \
namespace detail \
{ \
template <> \
struct operator_l<op_##id> \
{ \
template <class L, class R> \
struct apply \
{ \
static inline PyObject* \
execute(back_reference<L&> l, R const& r) \
{ \
l.get() op r; \
return python::incref(l.source().ptr()); \
} \
}; \
static char const* name() { return "__" #id "__"; } \
}; \
} \
namespace self_ns \
{ \
template <class R> \
inline detail::operator_<detail::op_##id,self_t,R> \
operator##op(self_t const&, R const&) \
{ \
return detail::operator_<detail::op_##id,self_t,R>(); \
} \
}
// Fully specialize define_operator for all operators defined in operator_id above.
// Every specialization defines one function object for normal operator calls and one
// for operator calls with operands reversed ("__r*__" function variants).
// Specializations for most operators follow a standard pattern: execute the expression
// that uses the operator in question. This standard pattern is realized by the following
// macros so that the actual specialization can be done by just calling a macro.
# define PY_DEFINE_BINARY_OPERATORS(id, oper) \
template <> \
struct define_operator<op_##id> \
{ \
template <class Left, class Right = Left> \
struct operator_function : function \
{ \
PyObject* do_call(PyObject* arguments, PyObject* /* keywords */) const \
{ \
tuple args(ref(arguments, ref::increment_count)); \
\
return BOOST_PYTHON_CONVERSION::to_python( \
BOOST_PYTHON_CONVERSION::from_python(args[0].get(), boost::python::type<Left>()) oper \
BOOST_PYTHON_CONVERSION::from_python(args[1].get(), boost::python::type<Right>())); \
} \
\
const char* description() const \
{ return "__" #id "__"; } \
}; \
\
template <class Right, class Left> \
struct roperator_function : function \
{ \
PyObject* do_call(PyObject* arguments, PyObject* /* keywords */) const \
{ \
tuple args(ref(arguments, ref::increment_count)); \
\
return BOOST_PYTHON_CONVERSION::to_python( \
BOOST_PYTHON_CONVERSION::from_python(args[1].get(), boost::python::type<Left>()) oper \
BOOST_PYTHON_CONVERSION::from_python(args[0].get(), boost::python::type<Right>())); \
} \
\
const char* description() const \
{ return "__r" #id "__"; } \
\
}; \
\
static const char * name() { return "__" #id "__"; } \
static const char * rname() { return "__r" #id "__"; } \
}
BOOST_PYTHON_INPLACE_OPERATOR(iadd,+=)
BOOST_PYTHON_INPLACE_OPERATOR(isub,-=)
BOOST_PYTHON_INPLACE_OPERATOR(imul,*=)
BOOST_PYTHON_INPLACE_OPERATOR(idiv,/=)
BOOST_PYTHON_INPLACE_OPERATOR(imod,%=)
BOOST_PYTHON_INPLACE_OPERATOR(ilshift,<<=)
BOOST_PYTHON_INPLACE_OPERATOR(irshift,>>=)
BOOST_PYTHON_INPLACE_OPERATOR(iand,&=)
BOOST_PYTHON_INPLACE_OPERATOR(ixor,^=)
BOOST_PYTHON_INPLACE_OPERATOR(ior,|=)
# define BOOST_PYTHON_UNARY_OPERATOR(id, op, func_name) \
namespace detail \
{ \
template <> \
struct operator_1<op_##id> \
{ \
template <class T> \
struct apply \
{ \
static PyObject* execute(T const& x) \
{ \
return detail::convert_result(op(x)); \
} \
}; \
static char const* name() { return "__" #id "__"; } \
}; \
} \
namespace self_ns \
{ \
inline detail::operator_<detail::op_##id> \
func_name(self_t const&) \
{ \
return detail::operator_<detail::op_##id>(); \
} \
}
# undef BOOST_PYTHON_INPLACE_OPERATOR
# define PY_DEFINE_UNARY_OPERATORS(id, oper) \
template <> \
struct define_operator<op_##id> \
{ \
template <class operand> \
struct operator_function : function \
{ \
PyObject* do_call(PyObject* arguments, PyObject* /* keywords */) const \
{ \
tuple args(ref(arguments, ref::increment_count)); \
\
return BOOST_PYTHON_CONVERSION::to_python( \
oper(BOOST_PYTHON_CONVERSION::from_python(args[0].get(), boost::python::type<operand>()))); \
} \
\
const char* description() const \
{ return "__" #id "__"; } \
}; \
\
static const char * name() { return "__" #id "__"; } \
}
BOOST_PYTHON_UNARY_OPERATOR(neg, -, operator-)
BOOST_PYTHON_UNARY_OPERATOR(pos, +, operator+)
BOOST_PYTHON_UNARY_OPERATOR(abs, abs, abs)
BOOST_PYTHON_UNARY_OPERATOR(invert, ~, operator~)
BOOST_PYTHON_UNARY_OPERATOR(int, long, int_)
BOOST_PYTHON_UNARY_OPERATOR(long, PyLong_FromLong, long_)
BOOST_PYTHON_UNARY_OPERATOR(float, double, float_)
BOOST_PYTHON_UNARY_OPERATOR(complex, std::complex<double>, complex_)
BOOST_PYTHON_UNARY_OPERATOR(str, lexical_cast<std::string>, str)
# undef BOOST_PYTHON_UNARY_OPERATOR
PY_DEFINE_BINARY_OPERATORS(add, +);
PY_DEFINE_BINARY_OPERATORS(sub, -);
PY_DEFINE_BINARY_OPERATORS(mul, *);
PY_DEFINE_BINARY_OPERATORS(div, /);
PY_DEFINE_BINARY_OPERATORS(mod, %);
PY_DEFINE_BINARY_OPERATORS(lshift, <<);
PY_DEFINE_BINARY_OPERATORS(rshift, >>);
PY_DEFINE_BINARY_OPERATORS(and, &);
PY_DEFINE_BINARY_OPERATORS(xor, ^);
PY_DEFINE_BINARY_OPERATORS(or, |);
PY_DEFINE_BINARY_OPERATORS(gt, >);
PY_DEFINE_BINARY_OPERATORS(ge, >=);
PY_DEFINE_BINARY_OPERATORS(lt, <);
PY_DEFINE_BINARY_OPERATORS(le, <=);
PY_DEFINE_BINARY_OPERATORS(eq, ==);
PY_DEFINE_BINARY_OPERATORS(ne, !=);
PY_DEFINE_UNARY_OPERATORS(neg, -);
PY_DEFINE_UNARY_OPERATORS(pos, +);
PY_DEFINE_UNARY_OPERATORS(abs, abs);
PY_DEFINE_UNARY_OPERATORS(invert, ~);
PY_DEFINE_UNARY_OPERATORS(int, long);
PY_DEFINE_UNARY_OPERATORS(long, PyLong_FromLong);
PY_DEFINE_UNARY_OPERATORS(float, double);
# undef PY_DEFINE_BINARY_OPERATORS
# undef PY_DEFINE_UNARY_OPERATORS
// Some operators need special treatment, e.g. because there is no corresponding
// expression in C++. These are specialized manually.
// pow(): Manual specialization needed because an error message is required if this
// function is called with three arguments. The "power modulo" operator is not
// supported by define_operator, but can be wrapped manually (see special.html).
template <>
struct define_operator<op_pow>
{
template <class Left, class Right = Left>
struct operator_function : function
{
PyObject* do_call(PyObject* arguments, PyObject* /* keywords */) const
{
tuple args(ref(arguments, ref::increment_count));
if (args.size() == 3 && args[2]->ob_type != Py_None->ob_type)
{
PyErr_SetString(PyExc_TypeError, "expected 2 arguments, got 3");
throw_argument_error();
}
return BOOST_PYTHON_CONVERSION::to_python(
pow(BOOST_PYTHON_CONVERSION::from_python(args[0].get(), boost::python::type<Left>()),
BOOST_PYTHON_CONVERSION::from_python(args[1].get(), boost::python::type<Right>())));
}
const char* description() const
{ return "__pow__"; }
};
template <class Right, class Left>
struct roperator_function : function
{
PyObject* do_call(PyObject* arguments, PyObject* /* keywords */) const
{
tuple args(ref(arguments, ref::increment_count));
if (args.size() == 3 && args[2]->ob_type != Py_None->ob_type)
{
PyErr_SetString(PyExc_TypeError, "bad operand type(s) for pow()");
throw_argument_error();
}
return BOOST_PYTHON_CONVERSION::to_python(
pow(BOOST_PYTHON_CONVERSION::from_python(args[1].get(), boost::python::type<Left>()),
BOOST_PYTHON_CONVERSION::from_python(args[0].get(), boost::python::type<Right>())));
}
const char* description() const
{ return "__rpow__"; }
};
static const char * name() { return "__pow__"; }
static const char * rname() { return "__rpow__"; }
};
// divmod(): Manual specialization needed because we must actually call two operators and
// return a tuple containing both results
template <>
struct define_operator<op_divmod>
{
template <class Left, class Right = Left>
struct operator_function : function
{
PyObject* do_call(PyObject* arguments, PyObject* /* keywords */) const
{
tuple args(ref(arguments, ref::increment_count));
PyObject * res = PyTuple_New(2);
PyTuple_SET_ITEM(res, 0,
BOOST_PYTHON_CONVERSION::to_python(
BOOST_PYTHON_CONVERSION::from_python(args[0].get(), boost::python::type<Left>()) /
BOOST_PYTHON_CONVERSION::from_python(args[1].get(), boost::python::type<Right>())));
PyTuple_SET_ITEM(res, 1,
BOOST_PYTHON_CONVERSION::to_python(
BOOST_PYTHON_CONVERSION::from_python(args[0].get(), boost::python::type<Left>()) %
BOOST_PYTHON_CONVERSION::from_python(args[1].get(), boost::python::type<Right>())));
return res;
}
const char* description() const
{ return "__divmod__"; }
};
template <class Right, class Left>
struct roperator_function : function
{
PyObject* do_call(PyObject* arguments, PyObject* /* keywords */) const
{
tuple args(ref(arguments, ref::increment_count));
PyObject * res = PyTuple_New(2);
PyTuple_SET_ITEM(res, 0,
BOOST_PYTHON_CONVERSION::to_python(
BOOST_PYTHON_CONVERSION::from_python(args[1].get(), boost::python::type<Left>()) /
BOOST_PYTHON_CONVERSION::from_python(args[0].get(), boost::python::type<Right>())));
PyTuple_SET_ITEM(res, 1,
BOOST_PYTHON_CONVERSION::to_python(
BOOST_PYTHON_CONVERSION::from_python(args[1].get(), boost::python::type<Left>()) %
BOOST_PYTHON_CONVERSION::from_python(args[0].get(), boost::python::type<Right>())));
return res;
}
const char* description() const
{ return "__rdivmod__"; }
};
static const char * name() { return "__divmod__"; }
static const char * rname() { return "__rdivmod__"; }
};
// cmp(): Manual specialization needed because there is no three-way compare in C++.
// It is implemented by two one-way comparisons with operators reversed in the second.
template <>
struct define_operator<op_cmp>
{
template <class Left, class Right = Left>
struct operator_function : function
{
PyObject* do_call(PyObject* arguments, PyObject* /* keywords */) const
{
tuple args(ref(arguments, ref::increment_count));
return BOOST_PYTHON_CONVERSION::to_python(
(BOOST_PYTHON_CONVERSION::from_python(args[0].get(), boost::python::type<Left>()) <
BOOST_PYTHON_CONVERSION::from_python(args[1].get(), boost::python::type<Right>())) ?
- 1 :
(BOOST_PYTHON_CONVERSION::from_python(args[1].get(), boost::python::type<Right>()) <
BOOST_PYTHON_CONVERSION::from_python(args[0].get(), boost::python::type<Left>())) ?
1 :
0) ;
}
const char* description() const
{ return "__cmp__"; }
};
template <class Right, class Left>
struct roperator_function : function
{
PyObject* do_call(PyObject* arguments, PyObject* /* keywords */) const
{
tuple args(ref(arguments, ref::increment_count));
return BOOST_PYTHON_CONVERSION::to_python(
(BOOST_PYTHON_CONVERSION::from_python(args[1].get(), boost::python::type<Left>()) <
BOOST_PYTHON_CONVERSION::from_python(args[0].get(), boost::python::type<Right>())) ?
- 1 :
(BOOST_PYTHON_CONVERSION::from_python(args[0].get(), boost::python::type<Right>()) <
BOOST_PYTHON_CONVERSION::from_python(args[1].get(), boost::python::type<Left>())) ?
1 :
0) ;
}
const char* description() const
{ return "__rcmp__"; }
};
static const char * name() { return "__cmp__"; }
static const char * rname() { return "__rcmp__"; }
};
# ifndef BOOST_PYTHON_USE_SSTREAM
class unfreezer {
public:
unfreezer(std::ostrstream& s) : m_stream(s) {}
~unfreezer() { m_stream.freeze(false); }
private:
std::ostrstream& m_stream;
};
# endif
// str(): Manual specialization needed because the string conversion does not follow
// the standard pattern relized by the macros.
template <>
struct define_operator<op_str>
{
template <class operand>
struct operator_function : function
{
PyObject* do_call(PyObject* arguments, PyObject*) const
{
tuple args(ref(arguments, ref::increment_count));
// When STLport is used with native streams, _STL::ostringstream().str() is not
// _STL::string, but std::string.
# ifdef BOOST_PYTHON_USE_SSTREAM
std::ostringstream s;
s << BOOST_PYTHON_CONVERSION::from_python(args[0].get(), boost::python::type<operand>());
return BOOST_PYTHON_CONVERSION::to_python(s.str());
# else
std::ostrstream s;
s << BOOST_PYTHON_CONVERSION::from_python(args[0].get(), boost::python::type<operand>()) << char();
auto unfreezer unfreeze(s);
return BOOST_PYTHON_CONVERSION::to_python(const_cast<char const *>(s.str()));
# endif
}
const char* description() const
{ return "__str__"; }
};
static const char * name() { return "__str__"; }
};
} // namespace detail
}} // namespace boost::python
# ifdef BOOST_NO_ARGUMENT_DEPENDENT_LOOKUP
using boost::python::self_ns::abs;
using boost::python::self_ns::int_;
using boost::python::self_ns::long_;
using boost::python::self_ns::float_;
using boost::python::self_ns::complex_;
using boost::python::self_ns::str;
using boost::python::self_ns::pow;
# endif
#endif // OPERATORS_DWA2002530_HPP
# undef BOOST_PYTHON_USE_SSTREAM
# endif
#endif /* OPERATORS_UK112000_H_ */

1265
test/comprehensive.cpp Normal file
View File

File diff suppressed because it is too large Load Diff

235
test/comprehensive.hpp Normal file
View File

@@ -0,0 +1,235 @@
// (C) Copyright David Abrahams 2000. Permission to copy, use, modify, sell and
// distribute this software is granted provided this copyright notice appears
// in all copies. This software is provided "as is" without express or implied
// warranty, and with no claim as to its suitability for any purpose.
//
// The author gratefully acknowleges the support of Dragon Systems, Inc., in
// producing this work.
#ifndef BPL_TEST_DWA052200_H_
# define BPL_TEST_DWA052200_H_
//
// Example code demonstrating extension class usage
//
# include <boost/python/class_builder.hpp>
# include <boost/python/callback.hpp>
# include <boost/utility.hpp>
# include <cstring>
# include <iostream>
# include <cstddef>
# include <string>
# include <map>
namespace bpl_test {
//
// example: Foo, Bar, and Baz are C++ classes we want to wrap.
//
class Foo // prohibit copying, proving that it doesn't choke
: private boost::noncopyable // our generation of to_python().
{
public: // constructor/destructor
Foo(int x) : m_x(x) {}
virtual ~Foo() {}
public: // non-virtual functions
const char* mumble(); // mumble something
void set(long x); // change the held value
// These two call virtual functions
std::string call_pure(); // call a pure virtual fuction
int call_add_len(const char* s) const; // virtual function with a default implementation
// A couple nested classs.
struct Foo_A { const char* mumble(); };
struct Foo_B { const char* mumble(); };
private:
// by default, sum the held value and the length of s
virtual int add_len(const char* s) const;
// Derived classes can do whatever they want here, but they must do something!
virtual std::string pure() const = 0;
public: // friend declarations
// If you have private virtual functions such as add_len which you want to
// override in Python and have default implementations, they must be
// accessible by the thing making the def() call on the extension_class (in
// this case, the nested PythonClass itself), and by the C++ derived class
// which is used to cause the Python callbacks (in this case,
// FooCallback). See the definition of FooCallback::add_len()
struct PythonClass;
friend struct PythonClass;
friend class FooCallback;
private:
int m_x; // the held value
};
//
// Bar and Baz have mutually-recursive type conversion dependencies (see
// pass_xxx functions). I've done this to prove that it doesn't cause a
// problem for Python class definitions, which happen later.
//
// Bar and Baz functions are only virtual to increase the likelihood of a crash
// if I inadvertently use a pointer to garbage memory (a likely thing to test
// for considering the amount of type casting needed to translate to and from
// Python).
struct Baz;
struct Bar
{
Bar(int x, int y) : m_first(x), m_second(y) {}
virtual int first() const { return m_first; }
virtual int second() const { return m_second; }
virtual Baz pass_baz(Baz x);
int m_first, m_second;
};
struct Baz
{
virtual Bar pass_bar(const Bar& x) { return x; }
// We can return smart pointers
virtual std::auto_ptr<Baz> clone() { return std::auto_ptr<Baz>(new Baz(*this)); }
// This illustrates creating a polymorphic derived class of Foo
virtual boost::shared_ptr<Foo> create_foo();
// We can accept smart pointer parameters
virtual int get_foo_value(boost::shared_ptr<Foo>);
// Show what happens in python when we take ownership from an auto_ptr
virtual void eat_baz(std::auto_ptr<Baz>);
};
typedef std::map<std::size_t, std::string> StringMap;
typedef std::pair<int, int> IntPair;
IntPair make_pair(int, int);
typedef std::less<IntPair> CompareIntPair;
typedef std::pair<std::string, std::string> StringPair;
inline std::string first_string(const StringPair& x)
{
return x.first;
}
inline std::string second_string(const StringPair& x)
{
return x.second;
}
struct Range
{
Range(int x)
: m_start(x), m_finish(x) {}
Range(int start, int finish)
: m_start(start), m_finish(finish) {}
std::size_t length() const
{ return m_finish < m_start ? 0 : m_finish - m_start; }
void length(std::size_t new_length)
{ m_finish = m_start + new_length; }
int operator[](std::size_t n)
{ return m_start + n; }
Range slice(std::size_t start, std::size_t end)
{
if (start > length())
start = length();
if (end > length())
end = length();
return Range(m_start + start, m_start + end);
}
int m_start, m_finish;
};
////////////////////////////////////////////////////////////////////////
// //
// Begin wrapping code. Usually this would live in a separate header. //
// //
////////////////////////////////////////////////////////////////////////
// Since Foo has virtual functions which we want overriden in Python, we must
// derive FooCallback.
class FooCallback : public Foo
{
public:
// Note the additional constructor parameter "self", which is needed to
// allow function overriding from Python.
FooCallback(PyObject* self, int x);
friend struct PythonClass; // give it access to the functions below
private: // implementations of Foo virtual functions that are overridable in python.
int add_len(const char* x) const;
// A function which Python can call in case bar is not overridden from
// Python. In true Python style, we use a free function taking an initial
// self parameter. You can put this function anywhere; it needn't be a
// static member of the wrapping class.
static int default_add_len(const Foo* self, const char* x);
// Since Foo::pure() is pure virtual, we don't need a corresponding
// default_pure(). A failure to override it in Python will result in an
// exception at runtime when pure() is called.
std::string pure() const;
private: // Required boilerplate if functions will be overridden
PyObject* m_self; // No, we don't want a boost::python::ref here, or we'd get an ownership cycle.
};
// Define the Python base class
struct Foo::PythonClass : boost::python::class_builder<Foo, FooCallback> { PythonClass(boost::python::module_builder&); };
// No virtual functions on Bar or Baz which are actually supposed to behave
// virtually from C++, so we'll rely on the library to define a wrapper for
// us. Even so, Python class_t types for each type we're wrapping should be
// _defined_ here in a header where they can be seen by other extension class
// definitions, since it is the definition of the boost::python::class_builder<> that
// causes to_python/from_python conversion functions to be generated.
struct BarPythonClass : boost::python::class_builder<Bar> { BarPythonClass(boost::python::module_builder&); };
struct BazPythonClass : boost::python::class_builder<Baz> { BazPythonClass(boost::python::module_builder&); };
struct StringMapPythonClass
: boost::python::class_builder<StringMap>
{
StringMapPythonClass(boost::python::module_builder&);
// These static functions implement the right argument protocols for
// implementing the Python "special member functions" for mapping on
// StringMap. Could just as easily be global functions.
static const std::string& get_item(const StringMap& m, std::size_t key);
static void set_item(StringMap& m, std::size_t key, const std::string& value);
static void del_item(StringMap& m, std::size_t key);
};
struct IntPairPythonClass
: boost::python::class_builder<IntPair>
{
IntPairPythonClass(boost::python::module_builder&);
// The following could just as well be a free function; it implements the
// getattr functionality for IntPair.
static int getattr(const IntPair&, const std::string& s);
static void setattr(IntPair&, const std::string& name, int value);
static void delattr(IntPair&, const char* name);
};
struct CompareIntPairPythonClass
: boost::python::class_builder<CompareIntPair>
{
CompareIntPairPythonClass(boost::python::module_builder&);
};
} // namespace bpl_test
#endif // BPL_TEST_DWA052200_H_

1281
test/comprehensive.py Normal file
View File

File diff suppressed because it is too large Load Diff