【轉】Boost.Python

標籤：

http://edyfox.codecarver.org/html/boost_python.html

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!")

【轉】Boost.Python