woaidongmao

Boost.Python 是 Boost 中的一個組件， 使用它能夠大大簡化用 C++ 為 Python 寫擴展庫的步驟，提高開發效率， 雖然目前它對 Python 嵌入 C++ 的支持還不是很多， 但也能提供很大方便。另外， 華宇煜也編寫了一份關于 Boost.Python 簡明教程。

1 Boost 安裝簡介

在正式開始使用 Boost.Python 之前， 我們必須先編譯 Boost。 首先到 Boost 的官方站點 下載 Boost 的源碼包， 把它們解壓到你喜歡的目錄，為編譯做好準備。 另外， 在正式安裝 Boost.Python 之前， 我們必須先正確安裝 Python。

1.1 Linux 下的編譯

首先切換到 Boost 源碼所在的路徑， 執行 ./configure 腳本，為配置腳本提供 Python 運行環境相應的參數：

./configure --with-python=/usr/bin/python \
            --with-python-version=2.4 \
            --with-python-root=/usr

然后， 和絕大部分 Linux 程序一行， 執行 make 就可以開始編譯了。編譯完畢后， 切換到 root 權限后再執行 make install，把 Boost 相應的頭文件和庫文件復制到相應的地方， 就可以使用了。

1.2 使用 MinGW + MSys 在 Windows 下的編譯

首先需要編譯的是 Boost 的編譯工具 bjam， 直接到 bjam 所在目錄下， 即 Boost 源碼包所在目錄下的 \tools\build\jam_src， 執行 build.bat mingw，稍等片刻， bjam.exe 就編譯好了。 把編譯好的 bjam.exe 復制到你的 %PATH% 路徑能夠直接找到的地方， 為后續的編譯工作做好準備。

接下來， 切換到 Boost 源碼所在路徑， 執行 bjam 進行編譯。 我們需要提供關于 Python 的一些參數， 變量 PYTHON_ROOT 指向 Python 運行環境所在的目錄，變量 PYTHON_VERSION 的值為 Python 的版本號， 如果你的 Python 安裝路徑與滇狐不同，請將相應的變量修改為你機器上相應的路徑， 編譯命令行如下：

bjam.exe "-sTOOLS=mingw" "-sPYTHON_ROOT=E:\Python" "-sPYTHON_VERSION=2.4"

編譯完畢后， 你將會在你的 C:\Boost 下找到編譯得到的 Boost 相應頭文件與庫文件， 你可以根據你的需要將它移動到別的地方備用。

2 使用 Boost.Python 嵌入 Python 模塊到 C++

Boost.Python 目前并沒有提供完整的將 Python 模塊嵌入到 C++ 的包裝庫，因此許多工作我們還必須通過 Python C API 來進行。 但是， 利用 Boost.Python 中提供的一些模塊， 能夠給我們的工作帶來極大便利。

2.1 修改模塊加載路徑，裝入 Python 模塊

與任何一個其它 Python 嵌入 C/C++ 的程序一樣， 我們需要在第一條 #include 語句處含入 Python.h， 并在程序開始時調用 Py_Initialize()，在程序結束時調用 Py_Finalize()。

接下來， 我們便可以開始準備裝入 Python 模塊了。 為了讓 Python 解釋器能夠正確地找到 Python 模塊所在的位置， 我們需要將 Python 模塊所在的路徑添加到模塊搜索路徑中，添加搜索路徑的 Python 語句如下：

import sys
if not '/module/path' in sys.path:
    sys.path.append('/module/path')

我們使用 Python C API 執行類似的語句， 就能將模塊的搜索路徑添加到 Python 解釋器中。 添加了搜索路徑后， 就可以通過 PyImport_ImportModule 函數加載 Python 模塊了。 PyImport_ImportModule 返回值是 PyObject *， 為了避免手工處理繁瑣的引用計數等問題，我們求助于 Boost.Python 提供的 handle 模塊， 將 PyObject * 封裝起來， 以方便使用， 代碼如下：

#include <boost/python.hpp>

...

    boost::python::handle<>* _module; // Module handle.
    std::string path; // Path of the Python module.
    std::string module; // Module name.

...

    try
    {
        PyRun_SimpleString("import sys");
        PyRun_SimpleString((std::string("if not '") + path
            + "' in sys.path: sys.path.append('" + path + "')").c_str());
        _module = new boost::python::handle<>(
            PyImport_ImportModule((char *) module));
        ...
    }
    catch (...)
    {
        PyErr_Print();
        PyErr_Clear();
        delete _module;
        _module = NULL;
        return false;
    }

...

需要注意的是， 通過 Python C API 加載的 Python 解釋器并沒有把當前路徑列入默認的搜索路徑中。因此， 即使你的 Python 模塊就存放在當前路徑， 你也必須使用上面的代碼將當前路徑添加到搜索路徑中之后，才能通過 PyImport_ImportModule 加載到模塊。

當 Python 模塊使用完畢或程序結束時， 請使用 delete 將 _module 指針釋放， handle 被釋放的時候會自動釋放相應的 Python 模塊并回收相應資源。

2.2 調用 Python 函數

導入了 Python 模塊之后， 調用 Python 函數就非常容易了。 Boost.Python 里封裝了一個非常好用的模板函數 boost::python::call_method，它可以替你處理調用函數時需要處理的種種細節， 將你從 Python C API 中繁瑣的“將參數打包為 PyObject *”、 “構造 Tuple”、 “傳遞 Tuple”、 “解包返回值”等工作中徹底解放出來， 你只需要這樣：

    boost::python::call_method<返回值類型>(模塊指針, "Python 函數名",
        參數 1, 參數 2, ...);

模塊指針可以通過我們前面得到的 _module 的 get 方法獲得， 例如：

...
    bool result;
    std::string config_file;

    ...

    try
    {
        return boost::python::call_method<bool>(_module->get(), "initialize",
            config_file);
    }
    catch (...)
    {
        PyErr_Print();
        PyErr_Clear();
        ...
    }

...

2.3 使用 Python 類對象

使用 Python C API 調用 Python 函數和調用 Python 類對象是沒有太大區別的，我們只需要調用類的構造方法， 得到一個類對象， 然后把該類的指針看做模塊指針，按照前面調用普通函數的方法調用類成員方法就可以了。 例如， 下列代碼從 _module 中創建了一個 YukiSession 對象， 然后調用了其中的 on_welcome 方法。 除了展示調用類成員方法外， 這段代碼還展示了構造 Python list 對象、 從 Python list 對象中獲取元素的方式。

    ...

    boost::python::handle<> _yukisession;

    ...

    // Retrieve the module handle and namespace handle.
    boost::python::object main_module(*_module);
    boost::python::object main_namespace = main_module.attr("__dict__");

    // Call the method and get the object handle.
    _yukisession = boost::python::handle<>((PyRun_String(
        "YukiSession()", Py_eval_input,
        main_namespace.ptr(), main_namespace.ptr())));
    ...

    // Compose a list.
    boost::python::list param;
    param.append(boost::python::str(_addr.get_host_addr()));
    param.append(boost::python::str());

    // Call the method and retrieve the result.
    // Method is equivalent to:
    // "bool __thiscall YukiSession::on_welcome(list param);"
    result = boost::python::call_method<bool>
        (_yukisession.get(), "on_welcome", param);
    // Extract an item from a list.
    str = boost::python::call_method<std::string>
        (param.ptr(), "__getitem__", 1);

    ...

3 在嵌入的 Python 模塊中調用 C++ 程序

通過動態鏈接庫的方式使用 Boost.Python 導出 C++ 模塊到 Python 程序與在 C++ 可執行程序中導出模塊給嵌入的 Python 解釋器， 編寫程序的方式幾乎是完全相同的。因此這里只簡單介紹導出普通函數的方法， 想詳細了解更多高級功能， 如導出 C++ 類、 導出可被 Python 重載的類等， 可以參看華宇煜的 Boost.Python 簡明教程或官方 Boost.Python 文檔。

3.1 導出 C++ 函數

首先使用 BOOST_PYTHON_MODULE 宏定義需要導出給 Python 的模塊，然后用 boost::python::def 語句定義導出的函數、 參數列表以及 Doc String， 例如在下面的例子中， 我們導出了一個 C++ 函數 yukigettext，并重命名為 gettext：

const char *yukigettext(const char *id);

BOOST_PYTHON_MODULE(yuki)
{
    boost::python::def("gettext", yukigettext,
        boost::python::args("id"), "Translate message.");
}

3.2 為 Python 初始化 C++ 模塊

使用 BOOST_PYTHON_MODULE(name) 定義了 Python 模塊后，該宏會自動生成一個函數 initname， 我們需要在 Py_Initialize() 之后調用這個自動生成的函數， 初始化導出到 Python 的模塊。 例如我們剛才導出模塊用的宏 BOOST_PYTHON_MODULE(yuki)， 因此初始化的時候就應該調用 inityuki()：

...
    Py_Initialize();
    inityuki();
...

3.3 在 Python 模塊中調用 C++ 模塊

此時我們在 Python 模塊中只需要像普通的 Python 模塊那樣， 將導入的 C++ 模塊用 import 語句加載進來， 就可以調用了：

import yuki

...

print yuki.gettext("This is a test!")