The Boost Python Library (Boost.Python)

Synopsis

Use the Boost Python Library to quickly and easily export a C++ library to Python such that the Python interface is very similar to the C++ interface. It is designed to be minimally intrusive on your C++ design. In most cases, you should not have to alter your C++ classes in any way in order to use them with Boost.Python. The system should simply ``reflect'' your C++ classes and functions into Python. The major features of Boost.Python include support for:

• Subclassing extension types in Python
• Overriding virtual functions in Python
• [Member] function Overloading
• Automatic wrapping of numeric operators

Supported Platforms

Boost.Python is known to have been tested against Python 2.2.1 using the following compilers:

• MSVC++6sp5. All tests pass.

• MSVC++7 (Visual Studio .NET). All tests pass.

• Metrowerks CodeWarrior Pro7.2 and Pro7.0 for Windows. All tests pass.

• GCC 3.0.4 under Cygwin and RedHat Linux 7.1. All tests pass.

• Compaq C++ V6.2-024 for Digital UNIX (an EDG-based compiler). All tests pass.
  Note that the Boost.Compatibility library must be included (see e.g. tru64_cxx.mak in the build directory).

• Silicon Graphics MIPSpro Version 7.3.1.2m (an EDG-based compiler). All tests pass.
  Note that the Boost.Compatibility library must be included (see e.g. irix_CC.mak in the build directory).

• GCC 2.95.2 under MinGW and RedHat Linux 7.1. Compilation succeeds, but some tests fail at runtime due to exception handling bugs. It is therefore highly recommended to use GCC 3.0.4 instead.

• Intel C++ 6.0 beta: Comprehensive test fails to link due to a linker bug. Other tests seem to work.

• Intel C++ 5.0 Comprehensive test fails at runtime due to an exception-handling bug. Other tests seem to work.

Note that pickling doesn't work with Python 2.2 due to a core language bug. This is fixed in 2.2.1.

Boost.Python has also been used with other versions of Python back to Python 1.5.2. It is expected that the older Python releases still work, but we are not regularly testing for backward compatibility.

Credits

• David Abrahams originated and wrote most of the library, and continues to coordinate development.
• Ullrich Koethe had independently developed a similar system. When he discovered Boost.Python, he generously contributed countless hours of coding and much insight into improving it. He is responsible for an early version of the support for function overloading and wrote the support for reflecting C++ inheritance relationships. He has helped to improve error-reporting from both Python and C++, and has designed an extremely easy-to-use way of exposing numeric operators, including a way to avoid explicit coercion by means of overloading.
• Ralf W. Grosse-Kunstleve contributed pickle support and numerous other small improvements. He's working on a way to allow types exported by multiple modules to interact.
• The members of the boost mailing list and the Python community supplied invaluable early feedback. In particular, Ron Clarke, Mark Evans, Anton Gluck, Chuck Ingold, Prabhu Ramachandran, and Barry Scott took the brave step of trying to use Boost.Python while it was still in early stages of development.
• The development of Boost.Python wouldn't have been possible without the generous support of Dragon Systems/Lernout and Hauspie, Inc who supported its development as an open-source project.

Table of Contents

1. A Brief Introduction to writing Python extension modules
2. Comparisons between Boost.Python and other systems for extending Python
3. A Simple Example
4. Exporting Classes
5. Overridable Virtual Functions
6. Function Overloading
7. Inheritance
8. Special Method and Operator Support
9. A Peek Under the Hood
10. Building an Extension Module
11. Pickle Support
12. Cross-Extension-Module Dependencies
13. Wrapping Enums
14. Pointers and Smart Pointers
15. Internal Data Structures

Documentation is a major ongoing project; assistance is greatly appreciated! In the meantime, useful examples of every Boost.Python feature should be evident in the regression test files test/comprehensive.[py/hpp/cpp]

Questions should be directed to the Python C++ SIG.

© Copyright David Abrahams 2001. Permission to copy, use, modify, sell and distribute this document is granted provided this copyright notice appears in all copies. This document is provided ``as is'' without express or implied warranty, and with no claim as to its suitability for any purpose.

Updated: Apr 2002