Abstract

摘要

Boost.Python is an open source C++ library which provides a conciseIDL-like interface for binding C++ classes and functions toPython. Leveraging the full power of C++ compile-time introspectionand of recently developed metaprogramming techniques, this is achievedentirely in pure C++, without introducing a new syntax.Boost.Python's rich set of features and high-level interface make itpossible to engineer packages from the ground up as hybrid systems,giving programmers easy and coherent access to both the efficientcompile-time polymorphism of C++ and the extremely convenient run-timepolymorphism of Python.

Boost.Python是一个开源C++库，它提供了一个简明的IDL式的接口，用于把C++类和函数绑定到Python。借助C++强大的编译时内省能力和最近发展的元编程技术，绑定工作完全用纯C++实现，而没有引入新的语法。Boost.Python丰富的特性和高级接口，使得完全按混合系统设计软件包成为可能，并让程序员以轻松连贯的方式，同时使用C++高效的编译时多态，和Python极端便利的运行时多态。

Introduction

介绍

Python and C++ are in many ways as different as two languages couldbe: while C++ is usually compiled to machine-code, Python isinterpreted.  Python's dynamic type system is often cited as thefoundation of its flexibility, while in C++ static typing is thecornerstone of its efficiency. C++ has an intricate and difficultcompile-time meta-language, while in Python, practically everythinghappens at runtime.

作为两种语言，Python和C++存在很多差异。C++一般被编译为机器码，而Python是解释执行的。Python的动态类型系统通常被认为是它灵活性的基础，而C++的静态类型系统是C++效率的基石。C++有一种复杂艰深的编译时元语言，而在Python中，几乎一切都发生在运行时。

Yet for many programmers, these very differences mean that Python andC++ complement one another perfectly.  Performance bottlenecks inPython programs can be rewritten in C++ for maximal speed, andauthors of powerful C++ libraries choose Python as a middlewarelanguage for its flexible system integration capabilities.Furthermore, the surface differences mask some strong similarities:

然而对很多程序员来说，这些差异也意味着Python和C++可以完美互补。为了提高运行速度，Python程序的性能瓶颈可以用C++重写，而大型C++库的作者们，为了获得灵活的系统集成能力，选择Python作为中间件语言。此外，在表面差异掩盖之下，二者有一些非常相似之处：

• 'C'-family control structures (if, while, for...)
• Support for object-orientation, functional programming, and genericprogramming (these are both multi-paradigm programming languages.)
• Comprehensive operator overloading facilities, recognizing theimportance of syntactic variability for readability andexpressivity.
• High-level concepts such as collections and iterators.
• High-level encapsulation facilities (C++: namespaces, Python: modules)to support the design of re-usable libraries.
• Exception-handling for effective management of error conditions.
• C++ idioms in common use, such as handle/body classes andreference-counted smart pointers mirror Python reference semantics.

• 'C'-家族的控制结构（if, while, for...）
• 支持面向对象、函数式编程，以及泛型编程（它们都是多范式（multi-paradigm）编程语言。）
• 认同语法可变性（syntactic variability）对于提高代码可读性和表达力的重要作用，提供了对运算符重载的广泛支持。
• 高级概念，如集合和迭代器。
• 高级封装机制（C++：名字空间，Python：模块），以支持可重用库的设计。
• 异常处理，提供有效的错误管理。
• 通用的C++惯用法，如handle/body类，和引用计数的智能指针，即Python的引用语义。

Given Python's rich 'C' interoperability API, it should in principlebe possible to expose C++ type and function interfaces to Python withan analogous interface to their C++ counterparts.  However, thefacilities provided by Python alone for integration with C++ arerelatively meager.  Compared to C++ and Python, 'C' has only veryrudimentary abstraction facilities, and support for exception-handlingis completely missing.  'C' extension module writers are required tomanually manage Python reference counts, which is both annoyinglytedious and extremely error-prone. Traditional extension modules alsotend to contain a great deal of boilerplate code repetition whichmakes them difficult to maintain, especially when wrapping an evolvingAPI.

因为Python有着丰富的'C'语言集成API，原则上，向Python导出C++类型和函数接口应该是可行的，并且导出的接口与对应C++的接口应该是相似的。然而，Python本身提供的C++集成功能相对比较弱。和C++，Python相比，'C'只有非常基本的抽象能力，而且完全不支持异常处理。'C'扩展模块的作者必须手工管理Python的引用计数，这不仅单调乏味，令人恼火，而且还极易出错。传统的扩展模块往往包含大量重复的样板代码，使它们难以维护，尤其是当要封装的API尚处于发展之中。

These limitations have lead to the development of a variety of wrappingsystems.  SWIG is probably the most popular package for theintegration of C/C++ and Python. A more recent development is SIP,which was specifically designed for interfacing Python with the Qtgraphical user interface library.  Both SWIG and SIP introduce theirown specialized languages for customizing inter-language bindings.This has certain advantages, but having to deal with three differentlanguages (Python, C/C++ and the interface language) also introducespractical and mental difficulties.  The CXX package demonstrates aninteresting alternative.  It shows that at least some parts ofPython's 'C' API can be wrapped and presented through a much moreuser-friendly C++ interface. However, unlike SWIG and SIP, CXX doesnot include support for wrapping C++ classes as new Python types.

这些限制导致了多种封装系统的发展。SWIG可能是最流行的C/C++和Python集成系统。还有最近发展的SIP，它是专门为Qt图形用户界面库设计的，用于提供Qt的Python接口。为了定制语言间的绑定，SWIG和SIP都引入了它们自己的专用语言。这有一定的好处，但是你不得不去应付三种不同语言（Python、C/C++和接口语言），所以也带来了事实上和心理上的困难。CXX软件包展示了另一种令人感兴趣的选择。它显示，至少可以封装部分Python 'C' API，将它们表示为更友好的C++接口。然而，不像SWIG和SIP，CXX不能将C++类封装成新的Python类型。

The features and goals of Boost.Python overlap significantly withmany of these other systems.  That said, Boost.Python attempts tomaximize convenience and flexibility without introducing a separatewrapping language.  Instead, it presents the user with a high-levelC++ interface for wrapping C++ classes and functions, managing much ofthe complexity behind-the-scenes with static metaprogramming.Boost.Python also goes beyond the scope of earlier systems byproviding:

Boost.Python的特性和目标与这些系统有很多重叠。Boost.Python努力提高封装的便利性和灵活性，但不引入单独的封装语言。相反，它通过静态元编程，在幕后管理大量的复杂性，呈现给用户一个高级C++接口来封装C++类和函数。Boost.Python也在如下领域超越了早期的系统：

• Support for C++ virtual functions that can be overridden in Python.
• Comprehensive lifetime management facilities for low-level C++pointers and references.
• Support for organizing extensions as Python packages,with a central registry for inter-language type conversions.
• A safe and convenient mechanism for tying into Python's powerfulserialization engine (pickle).
• Coherence with the rules for handling C++ lvalues and rvalues thatcan only come from a deep understanding of both the Python and C++type systems.

• 支持C++虚函数，并能在Python中覆盖。
• 对于低级的C++指针和引用，提供全面的生命期管理机制。
• 支持按Python包组织扩展模块，通过中心注册表进行语言间类型转换。
• 通过一种安全方便的机制，引入Python强大的序列化引擎（pickle）。
• 与C++处理左值和右值的规则相一致，该一致性只能来自于对Python和C++类型系统的深入理解。

The key insight that sparked the development of Boost.Python is thatmuch of the boilerplate code in traditional extension modules could beeliminated using C++ compile-time introspection.  Each argument of awrapped C++ function must be extracted from a Python object using aprocedure that depends on the argument type.  Similarly the function'sreturn type determines how the return value will be converted from C++to Python.  Of course argument and return types are part of eachfunction's type, and this is exactly the source from whichBoost.Python deduces most of the information required.

一个关键性的发现启动了Boost.Python的开发，即利用C++的编译时内省，可以消除传统扩展模块中的大量样板代码。如每个封装的C++函数的参数都是从Python对象提取的，提取时必须根据参数类型调用相应的过程。类似地，函数返回值从C++转换成Python时，返回值的类型决定了如何转换。因为参数和返回值的类型是每个函数类型的一部分，所以Boost.Python可以从函数类型推导出大部分所需的信息。

This approach leads to user guided wrapping: as much information isextracted directly from the source code to be wrapped as is possiblewithin the framework of pure C++, and some additional information issupplied explicitly by the user.  Mostly the guidance is mechanicaland little real intervention is required.  Because the interfacespecification is written in the same full-featured language as thecode being exposed, the user has unprecedented power available whenshe does need to take control.

这种方法导致了“用户指导的封装（user guided wrapping）”：在纯C++的框架内，从待封装的源代码中直接提取尽可能多的信息，而一些额外的信息由用户显式提供。通常这种指导是自动的，很少需要真正的干涉。因为接口规范和导出代码是用同一门全功能的语言写的，当用户确实需要取得控制时，他所拥有的权力是空前强大的。

Boost.Python Design Goals

Boost.Python的设计目标

The primary goal of Boost.Python is to allow users to expose C++classes and functions to Python using nothing more than a C++compiler.  In broad strokes, the user experience should be one ofdirectly manipulating C++ objects from Python.

Boost.Python的首要目标是，让用户只用C++编译器就能向Python导出C++类和函数。大体来讲，用户的体验应该是，能够从Python直接操作C++对象。

However, it's also important not to translate all interfaces tooliterally: the idioms of each language must be respected.  Forexample, though C++ and Python both have an iterator concept, they areexpressed very differently.  Boost.Python has to be able to bridge theinterface gap.

然而，有一点也很重要，那就是不要过于按字面翻译所有接口：必须考虑每种语言的惯用法。例如，虽然C++和Python都有迭代器的概念，表达方式却很不一样。Boost.Python必须能够消除这种接口的差异。

It must be possible to insulate Python users from crashes resultingfrom trivial misuses of C++ interfaces, such as accessingalready-deleted objects.  By the same token the library shouldinsulate C++ users from low-level Python 'C' API, replacingerror-prone 'C' interfaces like manual reference-count management andraw PyObject pointers with more-robust alternatives.

Python用户可能会误用C++接口，因此，Boost.Python必须能够隔离因轻微的误用而造成的崩溃，例如访问已删除的对象。同样的，Boost.Python库应该把C++用户从低级的Python 'C' API中解放出来，将容易出错的'C'接口，如手工引用计数管理、原始的PyObject指针，替换为更健壮的接口。

Support for component-based development is crucial, so that C++ typesexposed in one extension module can be passed to functions exposed inanother without loss of crucial information like C++ inheritancerelationships.

支持基于组件的开发是至关重要的，这样，一个扩展模块导出的C++类型，可以传递给另一个模块导出的函数，而不丢失重要的信息，比如C++的继承关系。

Finally, all wrapping must be non-intrusive, without modifying oreven seeing the original C++ source code.  Existing C++ libraries haveto be wrappable by third parties who only have access to header filesand binaries.

最后，所有的封装必须是非侵入性的（non-intrusive），不能修改最初的C++源码，甚至不必看到源码。第三方必须能够封装现有的C++库，即使他只有头文件和二进制库。

Hello Boost.Python World

Hello Boost.Python World

And now for a preview of Boost.Python, and how it improves on the rawfacilities offered by Python. Here's a function we might want toexpose:

现在来预览一下Boost.Python，看看它是如何改进Python原有的封装机制的。下面是我们想导出的函数:

char const* greet(unsigned x)
{
   static char const* const msgs[] = { "hello", "Boost.Python", "world!" };

   if (x > 2) 
       throw std::range_error("greet: index out of range");

   return msgs[x];
}

To wrap this function in standard C++ using the Python 'C' API, we'dneed something like this:

在标准C++中，用Python 'C' API来封装这个函数，我们需要像这样做:

extern "C" // all Python interactions use 'C' linkage and calling convention
{
    // Wrapper to handle argument/result conversion and checking
    PyObject* greet_wrap(PyObject* args, PyObject * keywords)
    {
         int x;
         if (PyArg_ParseTuple(args, "i", &x))    // extract/check arguments
         {
             char const* result = greet(x);      // invoke wrapped function
             return PyString_FromString(result); // convert result to Python
         }
         return 0;                               // error occurred
    }

    // Table of wrapped functions to be exposed by the module
    static PyMethodDef methods[] = {
        { "greet", greet_wrap, METH_VARARGS, "return one of 3 parts of a greeting" }
        , { NULL, NULL, 0, NULL } // sentinel
    };

    // module initialization function
    DL_EXPORT init_hello()
    {
        (void) Py_InitModule("hello", methods); // add the methods to the module
    }
}

Now here's the wrapping code we'd use to expose it with Boost.Python:

而这是用Boost.Python来导出函数的封装代码：

#include <boost/python.hpp>
using namespace boost::python;
BOOST_PYTHON_MODULE(hello)
{
    def("greet", greet, "return one of 3 parts of a greeting");
}

and here it is in action:

这是运行结果：

>>> import hello
>>> for x in range(3):
...     print hello.greet(x)
...
hello
Boost.Python
world!

Aside from the fact that the 'C' API version is much more verbose,it's worth noting a few things that it doesn't handle correctly:

使用'C' API的版本要冗长的多，此外，还需要注意，有些东西它没有正确处理：

• The original function accepts an unsigned integer, and the Python'C' API only gives us a way of extracting signed integers. TheBoost.Python version will raise a Python exception if we try to passa negative number to hello.greet, but the other one will proceedto do whatever the C++ implementation does when converting annegative integer to unsigned (usually wrapping to some very largenumber), and pass the incorrect translation on to the wrappedfunction.

  原来的函数接受一个无符号整数，然而Python 'C' API只能提取有符号整数。如果我们试图向hello.greet传递一个负数，Boost.Python版会引发Python异常，而另一个则会继续：执行C++代码，将负数转换为无符号数（通常会变成一个很大的数），然后把不正确的转换结果传递给被封装的函数。

• That brings us to the second problem: if the C++ greet()function is called with a number greater than 2, it will throw anexception.  Typically, if a C++ exception propagates across theboundary with code generated by a 'C' compiler, it will cause acrash.  As you can see in the first version, there's no C++scaffolding there to prevent this from happening.  Functions wrappedby Boost.Python automatically include an exception-handling layerwhich protects Python users by translating unhandled C++ exceptionsinto a corresponding Python exception.

  这引起了第二个问题：如果输入一个大于2的参数，C++ greet()函数会抛出异常。典型的，如果C++异常传播时，跨越了'C'编译器生成的代码的边界，就会导致崩溃。正如你在第一个版本中所见，那儿没有防止崩溃的C++机制。而Boost.Python封装的函数自动包含了异常处理层，它把未处理的C++异常翻译成相应的Python异常，从而保护了Python用户。

• A slightly more-subtle limitation is that the argument conversionused in the Python 'C' API case can only get that integer x inone way.  PyArg_ParseTuple can't convert Python long objects(arbitrary-precision integers) which happen to fit in an unsignedint but not in a signed long, nor will it ever handle awrapped C++ class with a user-defined implicit operator unsignedint() conversion. Boost.Python's dynamic type conversionregistry allows users to add arbitrary conversion methods.

  一个更微妙的限制是，Python 'C' API的参数转换只能以“一种”方式取得整数x。如果有一个Python long对象（任意精度整数），它的大小正好属于unsigned int，但不属于signed long，PyArg_ParseTuple就不能对其进行转换。对于一个定义了operator unsigned int()，即用户自定义隐式转换的C++封装类，它同样无法处理。而Boost.Python的动态类型转换注册表允许用户添加任意的转换方法。

Library Overview

库概览

This section outlines some of the library's major features.  Except asneccessary to avoid confusion, details of library implementation areomitted.

本节简述了库的一些主要特性。在不影响理解的情况下，省略了库的实现细节。

struct World
{
    void set(std::string msg) { this->msg = msg; }
    std::string greet() { return msg; }
    std::string msg;
};

#include <boost/python.hpp>
BOOST_PYTHON_MODULE(hello)
{
    class_<World>("World")
        .def("greet", &World::greet)
        .def("set", &World::set)
    ;
}

class_<World>("World")

class_<World> w("World");

w.def("greet", &World::greet)

class_<World> w("World");
w.def("greet", &World::greet);
w.def("set", &World::set);

>>> import hello
>>> planet = hello.World()
>>> planet.set('howdy')
>>> planet.greet()
'howdy'

>>> planet = hello.World()

struct World
{
    World(std::string msg); // added constructor
    ...

class_<World>("World", init<std::string>())
    ...

class_<World>("World", init<std::string>())
    .def(init<double, double>())
    ...

class_<World>("World", init<std::string>())
    .def_readonly("msg", &World::msg)
    ...

>>> planet = hello.World('howdy')
>>> planet.msg
'howdy'

class_<World>("World", init<std::string>())
    .add_property("msg", &World::greet, &World::set)
    ...

>>> class World(object):
...     __init__(self, msg):
...         self.__msg = msg
...     def greet(self):
...         return self.__msg
...     def set(self, msg):
...         self.__msg = msg
...     msg = property(greet, set)

class_<rational<int> >("rational_int")
  .def(init<int, int>()) // constructor, e.g. rational_int(3,4)
  .def("numerator", &rational<int>::numerator)
  .def("denominator", &rational<int>::denominator)
  .def(-self)        // __neg__ (unary minus)
  .def(self + self)  // __add__ (homogeneous)
  .def(self * self)  // __mul__
  .def(self + int()) // __add__ (heterogenous)
  .def(int() + self) // __radd__
  ...

class_<Derived, bases<Base1,Base2> >("Derived")
     ...

>>> class L(list):
...      def __init__(self):
...          pass
...
>>> L().reverse()
>>> 

>>> class D(SomeBoostPythonClass):
...      def __init__(self):
...          pass
...
>>> D().some_boost_python_method()
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
TypeError: bad argument type for built-in operation

//
// interface to wrap:
//
class Base
{
 public:
    virtual int f(std::string x) { return 42; }
    virtual ~Base();
};

int calls_f(Base const& b, std::string x) { return b.f(x); }

//
// Wrapping Code
//

// Dispatcher class
struct BaseWrap : Base
{
    // Store a pointer to the Python object
    BaseWrap(PyObject* self_) : self(self_) {}
    PyObject* self;

    // Default implementation, for when f is not overridden
    int f_default(std::string x) { return this->Base::f(x); }
    // Dispatch implementation
    int f(std::string x) { return call_method<int>(self, "f", x); }
};

...
    def("calls_f", calls_f);
    class_<Base, BaseWrap>("Base")
        .def("f", &Base::f, &BaseWrap::f_default)
        ;

>>> class Derived(Base):
...     def f(self, s):
...          return len(s)
...
>>> calls_f(Base(), 'foo')
42
>>> calls_f(Derived(), 'forty-two')
9