#
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

among others.

## Supported Platforms

Boost.Python is known to have been tested in the following configurations:

- Against Python 2.0 using the following compiler/library combinations:
  - MSVC++6sp4 with the native library.
  - An upcoming release of Metrowerks CodeWarrior Pro6 for Windows with the native library (the first release has a bug that's fatal to Boost.Python)
  - Intel C++ 5.0. Compilation succeeds, but tests FAILED at runtime due to a bug in its exception-handling implementation.
- 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 Boost.Python)

## 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 boost mailing list.

© 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: Mar 6, 2001