Copyright © 2002-2005 Joel de Guzman, David Abrahams
Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt ) @@ -83,18 +83,18 @@
- QuickStartThe Boost Python Library is a framework for interfacing Python and - C++. It allows you to quickly and seamlessly expose C++ classes functions and - objects to Python, and vice-versa, using no special tools -- just your C++ - compiler. It is designed to wrap C++ interfaces non-intrusively, so that you - should not have to change the C++ code at all in order to wrap it, making Boost.Python + The Boost Python Library is a framework for interfacing Python and C++. It + allows you to quickly and seamlessly expose C++ classes functions and objects + to Python, and vice-versa, using no special tools -- just your C++ compiler. + It is designed to wrap C++ interfaces non-intrusively, so that you should not + have to change the C++ code at all in order to wrap it, making Boost.Python ideal for exposing 3rd-party libraries to Python. The library's use of advanced metaprogramming techniques simplifies its syntax for users, so that wrapping code takes on the look of a kind of declarative interface definition language (IDL).
- + Hello World
@@ -123,19 +123,23 @@ That's it. We're done. We can now build this as a shared library. The resulting DLL is now visible to Python. Here's a sample Python session:
- ++
>>> import hello >>> print hello.greet() hello, world- -
Next stop... Building your Hello World module - from start to finish...
+
++ Next stop... Building your Hello World module + from start to finish... +
Last revised: October 31, 2005 at 18:46:06 GMT |
+Last revised: February 14, 2006 at 02:23:06 GMT |
diff --git a/doc/tutorial/doc/html/python/embedding.html b/doc/tutorial/doc/html/python/embedding.html index fa6cce61..26eaff1e 100644 --- a/doc/tutorial/doc/html/python/embedding.html +++ b/doc/tutorial/doc/html/python/embedding.html @@ -11,7 +11,7 @@
 |
+ |
Home | Libraries | People | @@ -27,19 +27,20 @@ Embedding
- Handle is a class template, so why
- haven't we been using any template parameters?handle has a single template parameter specifying - the type of the managed object. This type is PyObject - 99% of the time, so the parameter was defaulted to PyObject - for convenience. Therefore we can use the shorthand handle<> - instead of the longer, but equivalent, handle<PyObject>. + |
| Handle is a class
+ template, so why haven't we been using any template
+ parameters? handle has a + single template parameter specifying the type of the managed object. + This type is PyObject 99% of the time, so the parameter + was defaulted to PyObject for convenience. Therefore + we can use the shorthand handle<> instead + of the longer, but equivalent, handle<PyObject>. |
- + Running Python code
@@ -184,7 +189,8 @@ exe embedded_program # name of the executable
PyObject* PyRun_String(char *str, int start, PyObject *globals, PyObject *locals)-
+ PyRun_String takes the code to execute as a null-terminated (C-style) string in its str parameter. The function returns a new reference to a Python object. Which object is returned depends on the start paramater. @@ -195,8 +201,9 @@ exe embedded_program # name of the executable
-Start symbols -
+ + Start symbols +|
- Note that we wrap the return value of PyRun_String
+ |
| Note that
+ we wrap the return value of PyRun_String
in a (nameless) handle even though we are not interested
in it. If we didn't do this, the the returned object would be kept
alive unnecessarily. Unless you want to be a Dr. Frankenstein, always
@@ -278,7 +285,7 @@ exe embedded_program # name of the executable
|
- + Beyond handles
@@ -326,15 +333,15 @@ exe embedded_program # name of the executable
|
- Note that object's member
- function to return the wrapped PyObject* is called
- ptr instead of get. This makes
- sense if you take into account the different functions that object
- and handle perform. |
| Note that
+ object's member function to return the wrapped
+ PyObject* is called ptr instead
+ of get. This makes sense if you take into account
+ the different functions that object and handle
+ perform. |
- + Exception handling
diff --git a/doc/tutorial/doc/html/python/exception.html b/doc/tutorial/doc/html/python/exception.html index cc6d632e..d443959b 100644 --- a/doc/tutorial/doc/html/python/exception.html +++ b/doc/tutorial/doc/html/python/exception.html @@ -11,7 +11,7 @@
|
+ |
Home | Libraries | People | @@ -26,10 +26,9 @@
|
+ |
Home | Libraries | People | @@ -35,7 +35,7 @@
- MSVC6/7 WorkaroundIf you are using - Microsoft Visual C++ 6 or 7, you have to write f - as: return call<int>(this->get_override("f").ptr());. |
| MSVC6/7 Workaround + If you are using Microsoft Visual C++ 6 or 7, you have to write + f as: + return call<int>(this->get_override("f").ptr());. |
BaseWrap's overridden virtual member function f @@ -392,16 +398,17 @@ .def("f", pure_virtual(&Base::f)) ;
pure_virtual signals Boost.Python +
+ pure_virtual signals Boost.Python that the function f is a pure virtual function.
|
- member function and methods Python, - like many object oriented languages uses the term methods. - Methods correspond roughly to C++'s member functions + |
| member function and
+ methods Python, like many object oriented languages + uses the term methods. Methods correspond + roughly to C++'s member functions |
- Virtual Functions with Default ImplementationsWe've seen in the previous - section how classes with pure virtual functions are wrapped using Boost.Python's - class wrapper facilities. If - we wish to wrap non-pure-virtual functions - instead, the mechanism is a bit different. + We've seen in the previous section how classes with pure virtual functions + are wrapped using Boost.Python's class + wrapper facilities. If we wish to wrap non-pure-virtual + functions instead, the mechanism is a bit different.
Recall that in the previous @@ -460,10 +466,9 @@
|
- MSVC6/7 Workaround If you are using - Microsoft Visual C++ 6 or 7, you have to rewrite the line with the - *note* as: return call<char const*>(f.ptr());. |
| MSVC6/7 Workaround + If you are using Microsoft Visual C++ 6 or 7, you have to rewrite + the line with the *note* as: return call<char const*>(f.ptr());. |
Finally, exposing: @@ -482,7 +487,8 @@
In Python, the results would be as expected:
- ++
>>> base = Base() >>> class Derived(Base): @@ -509,9 +515,9 @@-diff --git a/doc/tutorial/doc/html/python/functions.html b/doc/tutorial/doc/html/python/functions.html index 7070ccfe..81bf8263 100644 --- a/doc/tutorial/doc/html/python/functions.html +++ b/doc/tutorial/doc/html/python/functions.html @@ -11,7 +11,7 @@- - Class Operators/Special FunctionsPython Operators +
+ + Python Operators
C is well known for the abundance of operators. C++ extends this to the extremes @@ -522,7 +528,8 @@ Consider a file position class FilePos and a set of operators that take on FilePos instances:
- ++
class FilePos { /*...*/ }; @@ -558,7 +565,7 @@ expressions".- + Special Methods
@@ -588,9 +595,7 @@
- -
|
+ |
Home | Libraries | People | @@ -32,13 +32,15 @@
- Remember the Zen, Luke:"Explicit - is better than implicit" "In the face of ambiguity, - refuse the temptation to guess" - |
| Remember the Zen, Luke: + "Explicit is better than implicit" "In + the face of ambiguity, refuse the temptation to guess" + |
- OverloadingThe following illustrates a scheme for manually wrapping an overloaded - member functions. Of course, the same technique can be applied to wrapping - overloaded non-member functions. + The following illustrates a scheme for manually wrapping an overloaded member + functions. Of course, the same technique can be applied to wrapping overloaded + non-member functions.
We have here our C++ class: @@ -351,8 +354,8 @@ Namespaces are one honking great idea -- let's do more of those!
- Default ArgumentsBoost.Python wraps (member) function pointers. Unfortunately, - C++ function pointers carry no default argument info. Take a function f + Boost.Python wraps (member) function pointers. Unfortunately, C++ function + pointers carry no default argument info. Take a function f with default arguments:
@@ -401,7 +404,7 @@ Namespaces are one honking great idea -- let's do more of those!
- + BOOST_PYTHON_FUNCTION_OVERLOADS
@@ -431,7 +434,7 @@ Namespaces are one honking great idea -- let's do more of those! def("foo", foo, foo_overloads());
- + BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS
@@ -477,7 +480,7 @@ Namespaces are one honking great idea -- let's do more of those! reference for details.
- + init and optional
@@ -507,10 +510,10 @@ Namespaces are one honking great idea -- let's do more of those!
- Auto-OverloadingIt was mentioned in passing in the previous section that - BOOST_PYTHON_FUNCTION_OVERLOADS and BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS - can also be used for overloaded functions and member functions with a common - sequence of initial arguments. Here is an example: + It was mentioned in passing in the previous section that BOOST_PYTHON_FUNCTION_OVERLOADS + and BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS can also be + used for overloaded functions and member functions with a common sequence + of initial arguments. Here is an example:
void foo() @@ -551,7 +554,7 @@ Namespaces are one honking great idea -- let's do more of those! (0) arguments and a maximum of 3 arguments.- + Manual Wrapping
diff --git a/doc/tutorial/doc/html/python/hello.html b/doc/tutorial/doc/html/python/hello.html index 6d648bf9..fe93c26b 100644 --- a/doc/tutorial/doc/html/python/hello.html +++ b/doc/tutorial/doc/html/python/hello.html @@ -11,7 +11,7 @@
|
+ |
Home | Libraries | People | @@ -25,9 +25,9 @@
|
- Building without bjam Besides bjam, - there are of course other ways to get your module built. What's written - here should not be taken as "the one and only way". There are - of course other build tools apart from bjam. Take note however that the preferred build tool for Boost.Python + | |||||||||||||||||||||||||
| Building without bjam + Besides bjam, there are of course other ways to get your module + built. What's written here should not be taken as "the one and only + way". There are of course other build tools apart from bjam. + Take note however that the preferred build tool for Boost.Python is bjam. There are so many ways to set up the build incorrectly. Experience shows that 90% of the "I can't build Boost.Python" problems come from people who had to use a different tool. |
-
- Be sure not to include a third number, e.g. not
- "2.2.1", even if that's the version you have. |
| Be sure not to include a third number, e.g. not "2.2.1", even if that's the version
+ you have. |
Take note that you may also do that through the Jamrules file we put in our @@ -251,23 +252,29 @@ b and object bin\tutorial\hello.pyd\vc-7_1\debug\threading-multi\hello.exp
if you are on Unix.
-boost_python.dll and hello.pyd can be +
+ boost_python.dll and hello.pyd can be found somewhere in your project's bin directory. After a - successful build, you can just link in these DLLs with the Python interpreter. - In Windows for example, you can simply put these libraries inside the directory - where the Python executable is. + successful build, you make it possible for the system to find boost_python.dll + or libboost_python.so (usually done with LD_LIBRARY_PATH, DYLD_LIBRARY_PATH, + or some other variable on *nix and with PATH on Windows) and for Python to + find the hello module (Done with PYTHONPATH on all systems.)
You may now fire up Python and run our hello module:
- ++
>>> import hello >>> print hello.greet() hello, world- -
There you go... Have fun!
+
++ There you go... Have fun! +
| diff --git a/doc/tutorial/doc/html/python/iterators.html b/doc/tutorial/doc/html/python/iterators.html index 022620e1..4abaa075 100644 --- a/doc/tutorial/doc/html/python/iterators.html +++ b/doc/tutorial/doc/html/python/iterators.html @@ -11,7 +11,7 @@ |
|
+ |
Home | Libraries | People | @@ -26,10 +26,12 @@
|
+ |
Home | Libraries | People | @@ -32,11 +32,11 @@
|
- Beware the common pitfall of forgetting that
- the constructors of most of Python's mutable types make copies, just
- as in Python. |
| Beware the
+ common pitfall of forgetting that the constructors of most of Python's
+ mutable types make copies, just as in Python. |
Python: @@ -193,7 +197,7 @@ d['whatever'] = 3; // modifies the copy
- + class_<T> as objects
@@ -218,9 +222,9 @@
- Extracting C++ objectsAt some point, we will need to get C++ values out of - object instances. This can be achieved with the extract<T> - function. Consider the following: + At some point, we will need to get C++ values out of object instances. This + can be achieved with the extract<T> function. Consider + the following:
double x = o.attr("length"); // compile error @@ -253,8 +257,8 @@ if (x.check()) { Vec2& v = x(); ...-
- The astute reader might have noticed that the extract<T>
+
+ The astute reader might have noticed that the extract<T>
facility in fact solves the mutable copying problem:
@@ -266,12 +270,12 @@- EnumsBoost.Python has a nifty facility to capture and wrap C++ enums. While - Python has no enum type, we'll often want to expose our - C++ enums to Python as an int. Boost.Python's enum facility - makes this easy while taking care of the proper conversions from Python's - dynamic typing to C++'s strong static typing (in C++, ints cannot be implicitly - converted to enums). To illustrate, given a C++ enum: + Boost.Python has a nifty facility to capture and wrap C++ enums. While Python + has no enum type, we'll often want to expose our C++ enums + to Python as an int. Boost.Python's enum facility makes + this easy while taking care of the proper conversions from Python's dynamic + typing to C++'s strong static typing (in C++, ints cannot be implicitly converted + to enums). To illustrate, given a C++ enum:
enum choice { red, blue }; @@ -293,16 +297,17 @@
- + -
The scope is a - class that has an associated global Python object which controls the - Python namespace in which new extension classes and wrapped functions - will be defined as attributes. Details can be found here.
+
The scope is a class that has an associated global Python object + which controls the Python namespace in which new extension classes + and wrapped functions will be defined as attributes. Details can be + found here.You can access those values in Python as
- ++
>>> my_module.choice.red my_module.choice.red @@ -311,7 +316,8 @@ where my_module is the module where the enum is declared. You can also create a new scope around a class: - ++
scope in_X = class_<X>("X") .def( ... ) diff --git a/doc/tutorial/doc/html/python/techniques.html b/doc/tutorial/doc/html/python/techniques.html index 87f7798c..4f57d5b4 100644 --- a/doc/tutorial/doc/html/python/techniques.html +++ b/doc/tutorial/doc/html/python/techniques.html @@ -10,7 +10,7 @@
|
+ |
Home | Libraries | People | @@ -30,16 +30,16 @@
|
-
- The extension .pyd is used for python extension
- modules, which are just shared libraries. Using the default for your
- system, like .so for Unix and .dll
- for Windows, works just as well. |
| The extension .pyd is used
+ for python extension modules, which are just shared libraries. Using
+ the default for your system, like .so for Unix and
+ .dll for Windows, works just as well. |
Now, we create this directory structure for our Python package: @@ -124,7 +122,8 @@ into his PYTHONPATH and fire up the interpreter:
- ++
>>> import sounds.io >>> import sounds.filters @@ -146,7 +145,8 @@ If we want this flexibility, we will have to complicate our package hierarchy a little. First, we will have to change the name of the extension modules: - ++
/* file core.cpp */ BOOST_PYTHON_MODULE(_core) @@ -178,7 +178,8 @@ to each one. But if we leave it that way, the user will have to access the functions in the core module with this syntax: - ++
>>> import sounds.core._core >>> sounds.core._core.foo(...) @@ -237,8 +238,8 @@- Extending Wrapped Objects in PythonThanks to Python's flexibility, you can - easily add new methods to a class, even after it was already created: + Thanks to Python's flexibility, you can easily add new methods to a class, + even after it was already created:
>>> class C(object): pass @@ -256,12 +257,14 @@ A C instance!- Yes, Python rox.
+ Yes, Python rox.We can do the same with classes that were wrapped with Boost.Python. Suppose we have a class point in C++:
- ++
class point {...}; @@ -274,7 +277,8 @@ If we are using the technique from the previous session, Creating Packages, we can code directly into geom/__init__.py: - ++
from _geom import * @@ -285,7 +289,8 @@ # now we turn it into a member function point.__str__ = point_str-All point instances created from C++ will +
+ All point instances created from C++ will also have this member function! This technique has several advantages:
@@ -357,12 +362,13 @@
- Reducing Compiling TimeIf you have ever exported a lot of classes, you know - that it takes quite a good time to compile the Boost.Python wrappers. Plus - the memory consumption can easily become too high. If this is causing you - problems, you can split the class_ definitions in multiple files: + If you have ever exported a lot of classes, you know that it takes quite + a good time to compile the Boost.Python wrappers. Plus the memory consumption + can easily become too high. If this is causing you problems, you can split + the class_ definitions in multiple files: +
+-
/* file point.cpp */ #include <point.h> @@ -421,19 +427,16 @@
- -
- + -