Boost(2)：boost.python库介绍及简单示例

1. boost.python介绍

将c/c++的函数接口转换为Python接口有好几种解决方案，不同于C语言的简单直接，C++因使用了大量的面向对象编程的思想导致转换为Python接口时相对比较复杂，boost.python的目标就是为了简单方便地将C++程序转换成Python的接口。

BoostPython库是boost c++库的其中一个子库，使用它可以轻松地将C++的函数接口转换成Python接口。在大部分情况下你不需要对原先的C++代码做任何修改，boost.python会对C++类再做一层封装，使它编译后符合Python的语言规范。

2. 简单例程

按照程序员的江湖规矩，一个新的学习开始时，首先从HelloWorld程序下手。在这个例程中，首先使用c++函数输出"hello world"，然后将这个函数封装成python的接口，在python环境下调用该函数实现打印。

注：本文例程运行在boost_1_73_0版本下。

整体文件结构如下：

/boost$ tree
├── 01_HelloWorld
│   ├── CMakeLists.txt
│   ├── hello.py
│   └── HelloWorld.cpp
└── CMakeLists.txt

1 directory, 4 files

创建boost目录用于保存后续的示例代码，boost目录下的CMakeLists.txt主要完成必要的库的查找工作，如这里会用到Python和Boost，然后再添加子目录下的CMakeLists.txt文件。

2.1 主目录下的CMakeLists.txt

内容如下：

project(Boost_Test)
cmake_minimum_required(VERSION 2.8.3)

# find python
find_package(PythonInterp REQUIRED)
find_package(PythonLibs ${PYTHON_VERSION_MAJOR}.${PYTHON_VERSION_MINOR} EXACT REQUIRED)

# now search for the boost component
# depending on the boost version it is called either python,
# python2, python27, python3, python36, python37, ...
list(
  APPEND _components
    python${PYTHON_VERSION_MAJOR}${PYTHON_VERSION_MINOR}
    python${PYTHON_VERSION_MAJOR}
    python
  )

message(BOOST_ROOT " ${BOOST_ROOT}")

set(_boost_python_found "")
set(Boost_NAMESPACE "libboost")
set(Boost_USE_MULTITHREADED ON)
set(Boost_USE_STATIC_LIBS OFF)
set(Boost_USE_STATIC_RUNTIME OFF)
foreach(_component IN ITEMS ${_components})
  find_package(Boost COMPONENTS ${_component})
  if(Boost_FOUND)
    set(_boost_python_found ${_component})
    break()
  endif()
endforeach()

#if(_boost_python_found STREQUAL "")
#  message(FATAL_ERROR "No matching Boost.Python component found")
#endif()

include_directories("${PYTHON_INCLUDE_DIRS}")
include_directories("${Boost_INCLUDE_DIRS}")
message(PYTHON_INCLUDE_DIRS " ${PYTHON_INCLUDE_DIRS}")
message(PYTHON_LIBRARIES " ${PYTHON_LIBRARIES}")
message(Boost_INCLUDE_DIRS " ${Boost_INCLUDE_DIRS}")
message(Boost_LIBRARIES " ${Boost_LIBRARIES}")

ADD_SUBDIRECTORY(01_HelloWorld)

2.2 HelloWorld.cpp

char const* greet()
{
   return "hello, world";
}

#include <boost/python.hpp>

BOOST_PYTHON_MODULE(hello)
{
    using namespace boost::python;
    def("greet", greet);
}

2.3 hello.py

#!/usr/bin/env python

import hello
print (hello.greet())

2.4 子目录下的CMakeLists.txt

这个文件主要完成编译库文件以及链接工作，注意MODULE_NAME必须与BOOST_PYTHON_MODULE()下的相同，比如这里都是hello。

set(MODULE_NAME  hello)

include_directories(${CMAKE_SOURCE_DIR})

add_library(${MODULE_NAME} SHARED
	HelloWorld.cpp
	)

if (UNIX)
  set_target_properties(${MODULE_NAME}
    PROPERTIES
    PREFIX ""
  )
elseif (WIN32)
  set_target_properties(${MODULE_NAME}
  PROPERTIES
  SUFFIX ".pyd"
  )
endif()

target_link_libraries(${MODULE_NAME}
  ${Boost_LIBRARIES}
  ${PYTHON_LIBRARIES}
)

对于windows系统，编译的python模块应该以".pyd"为后缀。而对于linux系统，默认会在模块名称前加"lib"，而Boost.Python要求模块名称和库文件名称保持一致，所以这里要声明不对库文件添加前缀。

3. 编译运行

3.1 编译

cd boost
mkdir build
cmake ..
make

之后，在build/01_HelloWorld目录下会生成hello.so的库文件。

3.2 运行

cd 01_HelloWorld

# 在不install so的情况下，将python文件拷贝到so目录
cp ../../01_HelloWorld/hello.py .

python hello.py

3.3 运行结果

#python hello.py
hello, world

4. Boost接口

4.1 BOOST_PYTHON_MODULE宏

这个宏定义在boost/python/module.hpp文件下，该文件提供了创建Boost.Python扩展模块的基本工具。目前也只有这个宏。

BOOST_PYTHON_MODULE用于声明python模块初始化函数，其使用格式如下：

BOOST_PYTHON_MODULE(name)
{
   ...
}

name 参数必须与要初始化的模块的名称完全匹配，并且必须符合 Python 的标识符命名规则。

4.2 def

def接口是Boost.Python提供的自由函数版本，它能将当前作用域中的函数转换为python的接口，如示例中的greet()函数。后面还会看到有转换类内函数的版本。

def的使用方式如下：

#include <boost/python.hpp>

BOOST_PYTHON_MODULE(my_module)
{
	def("name", function_ptr);
	def("name", function_ptr, call_policies);
	def("name", function_ptr, "documentation string");
	def("name", function_ptr, call_policies, "documentation string");
}

其中name表示python接口下的函数名称，可以与c++的名称不同。function_ptr是对应的c++函数指针，即函数名。call_policies在后面用到的时候再详细说明。

参考资料

https://wiki.python.org/moin/boost.python/GettingStarted

https://www.boost.org/doc/libs/1_78_0/libs/python/doc/html/tutorial/index.html

https://www.boost.org/doc/libs/1_78_0/libs/python/doc/html/reference/high_level_components/boost_python_module_hpp.html