The Boost Python Library (BPL)

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 BPL. The system should simply “reflect” your C++ classes and functions into Python. The major features of BPL include support for:

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

Supported Platforms

BPL has been tested in the following configurations:

• Against Python 1.5.2 using the following compiler/library:
  • MSVC++6sp4
  • MSVC++6sp4/STLport 4.0
  • GCC 2.95.2 [by Ullrich Koethe]
  • GCC 2.95.2/STLport 4.0
  • Compaq C++ V6.2-024 for Digital UNIX V5.0 Rev. 910 (an EDG-based compiler) with STLport-4.1b3 [by Ralf W. Grosse-Kunstleve]
  • An upcoming release of Metrowerks CodeWarrior Pro6 for Windows (the first release has a bug that's fatal to BPL)
  
  
• Against Python 2.0 using the following compiler/library combinations:
  • MSVC++6sp4 [by Alex Martelli]

Credits

• David Abrahams originated and wrote the library.
• Ullrich Koethe had independently developed a similar system. When he discovered BPL, 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.
• The members of the boost mailing list and the Python community supplied invaluable early feedback. In particular, Ron Clarke, Mark Evans, Anton Gluck, Ralf W. Grosse-Kunstleve, Chuck Ingold, Prabhu Ramachandran, and Barry Scott took the brave step of trying to use BPL while it was still in early stages of development.
• The development of BPL 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 BPL and other systems for extending Python
3. A Simple Example Using BPL
4. Overridable Virtual Functions
5. Function Overloading
6. Inheritance
7. Special Method and Operator Support
8. A Peek Under the Hood
9. Building a Module with BPL
10. Advanced Topics
    1. Pickling
    2. class_builder<>
    3. enums
    4. References
    5. Pointers and Smart Pointers
    6. Built-in Python Types
    7. Other Extension Types
    8. Templates

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

Questions should be directed to the boost mailing list.

© 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.

Updated: Nov 26, 2000