使用 Boost::Python 将 C++ 库封装为 Python 扩展

编译 nlohmann json schema validator 库

该库支持产出可执行的 bin 文件以及可供其他项目使用的动态库。为了可以将该扩展包装成 Python 扩展，我们需要先生成该库的动态库。

首先根据 nlohmann_json_schema_validator 的编译文档编译出动态库。通常需要使用 CMake 配置，确保开启 BUILD_SHARED_LIBS 选项。

Boost::Python 封装 C/C++ 代码

在安装 Boost 的时候，虽然 Boost 的头文件中存在 Boost::Python 相关的 hpp 文件，但是默认却没有该动态库。因此，在使用 Boost::Python 之前，首先需要安装该库。

# macOS 示例
brew install boost-python3

# Linux 示例 (Ubuntu/Debian)
sudo apt-get install libboost-python-dev

然后，我们用 C++ 编写 class json_validator_python 来封装 nlohmann_json_schema_validator 库，并利用 Boost::Python 来导出。

// jsv_python.cpp
#include <iomanip>
#include <iostream>

#include <nlohmann/json-schema.hpp>
#include <boost/python.hpp>

using namespace boost::python;

class JSON_SCHEMA_VALIDATOR_API json_validator_python
{
private:
    nlohmann::json_schema::json_validator validator;

public:
    json_validator_python() {}
    
    void set_root_schema(const std::string &json_string) 
    {
        // 解析 JSON 字符串
        auto parsed = nlohmann::json::parse(json_string.begin(), json_string.end());
        validator.set_root_schema(parsed);
    }

    void validate(const std::string &json_string) const
    {
        // 解析并验证
        auto data = nlohmann::json::parse(json_string.begin(), json_string.end());
        validator.validate(data);
    }
};

// json_schema_validator 为 module 名，必需和生成的 so 库名一样
BOOST_PYTHON_MODULE(json_schema_validator)
{
    class_<json_validator_python, boost::noncopyable>("json_validator_python")
            .def("set_root_schema", &json_validator_python::set_root_schema)
            .def("validate", &json_validator_python::validate)
            ;
}

如上所示的 BOOST_PYTHON_MODULE 代码，目的是导出类及成员方法。这些导出的类和方法可以在 Python 中直接导入并实例化。关于 Boost::Python 更详细的使用，可以参考其官方文档。

编译并产出 Python 扩展

使用 g++ 进行编译。注意需要指定正确的头文件路径和库路径。

# 1. 编译目标文件
export JSON_SCHEMA_PATH=/path/to/nlohmann-json-schema-validator
export BOOST_PATH=/usr/local/opt/boost
export PYTHON_INCLUDE=$(python3-config --includes)

g++ --std=c++11 -fPIC -c jsv_python.cpp \
-I${JSON_SCHEMA_PATH}/src \
-I/usr/include/nlohmann \
-I${BOOST_PATH}/include \
-I${PYTHON_INCLUDE}

# 2. 链接生成共享库
g++ --std=c++11 -shared \
-L${JSON_SCHEMA_PATH}/build/lib \
-L${BOOST_PATH}/lib \
-L$(python3-config --prefix)/lib \
-lnlohmann_json_schema_validator \
-lboost_python38 -lpython3.8 \
-o json_schema_validator.so jsv_python.o

如上的指令，会生成封装之后的 Python 扩展：json_schema_validator.so。

测试 python 扩展

在当前目录执行如下的 Python 代码，可以发现，我们封装的扩展已经可以当做 Python 扩展来导入并使用了。

import json_schema_validator as jsv

validator = jsv.json_validator_python()

isValidator = True
try:
    # 设置根 Schema
    validator.set_root_schema('{"type":"object", "properties": {"a":{"type": "string"}}}')
    # 验证数据
    validator.validate('{"a":"1"}');
except Exception as e:
    print(f"Validation Error: {e}")
    isValidator = False

print(isValidator)

使用 distutils 编译并分发扩展

为了使用方便，推荐使用 distutils 或 setuptools 模块编译 Python 扩展，这样可以自动化处理依赖路径。

创建 setup.py 文件：

from distutils.core import setup, Extension
import os

os.environ["CC"] = "g++"
os.environ["CXX"] = "g++"

module1 = Extension('json_schema_validator',
                    include_dirs = ['../../src',
                        '../../',
                        '/usr/local/opt/boost/include'],
                    libraries = ['boost_python38', 'python3.8',
                        'nlohmann_json_schema_validator'],
                    library_dirs = ['/usr/local/opt/boost/lib',
                        '.'],
                    sources = ['jsv_python.cpp'],
                    extra_compile_args=['--std=c++11'],
                    extra_link_args=['--std=c++11'])

setup(
    name='json-schema-validator',
    version='1.0',
    description='json schema validator extension',
    ext_modules=[module1]
)

执行以下命令进行构建和安装：

$ python3 setup.py build
$ python3 setup.py install

安装后，可能需要设置环境变量以便运行时能找到动态库：

# macOS / Linux
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib/python3.8/site-packages/json_schema_validator

常见问题与排查

在实际开发过程中，可能会遇到以下常见问题：

1. 找不到模块错误

如果报错 ImportError: No module named json_schema_validator，请检查以下几点：

• 确认 setup.py 中的 name 参数与生成的 .so 文件名一致。
• 确认 Python 环境是否正确激活。
• 检查 sys.path 是否包含了安装目录。

2. 动态库链接错误

如果运行时报错 undefined symbol 或 library not found，通常是链接顺序或路径问题。

• 确保 -L 参数指向了包含 .so 文件的目录。
• 确保 -l 参数对应的库名称正确（去掉前缀 lib 和后缀 .so）。
• 在 macOS 上，可能需要设置 DYLD_LIBRARY_PATH 而不是 LD_LIBRARY_PATH。

3. 跨平台兼容性

• Windows: 动态库后缀为 .pyd，依赖项需放在同一目录下或通过 PATH 环境变量添加。
• Linux: 注意 glibc 版本兼容性，尽量在较新的系统上编译。
• macOS: 注意架构兼容性（x86_64 vs arm64），建议使用 Universal 二进制或针对当前架构编译。

进阶：打包为 Wheel

为了更方便地分发，建议将扩展打包为 Wheel 格式（.whl）。这需要安装 wheel 包并使用 bdist_wheel 命令。

pip install wheel
python setup.py bdist_wheel

生成的 .whl 文件可以直接通过 pip install 安装，无需用户自行编译 C++ 代码，极大降低了部署成本。

总结

本文详细介绍了利用 Boost::Python 将 C++ 库封装为 Python 扩展的完整流程。从环境准备、C++ 代码封装、编译链接到最终的分发测试，涵盖了关键步骤。通过这种方式，开发者可以利用 C++ 的高性能特性增强 Python 应用的功能，同时保持 Python 开发的便捷性。在处理跨语言数据交互和性能敏感模块时，这种混合编程模式是非常有效的解决方案。