如何封装含vector属性的C++类/结构体以实现Python流畅调用

背景与现有问题 #

现有C++嵌套结构体定义：

// myheader.hpp
#include <vector>
namespace mynames{
struct Data{
    struct Piece{
        double piece1;
        int piece2;
        std::vector<double> piece3;
    };
    std::vector<Piece> pieces;
};
}

通过Cython声明扩展类型后，现有Python封装实现了基本功能，但存在两个核心问题：

• 无法原地修改：piece3返回的是numpy拷贝，修改数组元素不会同步到C++内存，必须重新赋值才能生效。
• 性能瓶颈：pieces属性每次访问都会遍历并拷贝所有C++ Piece对象到Python实例，数据量大时开销极高。

优化方案 #

1. 实现piece3的原地修改：基于C++内存的numpy视图 #

修改Piece类中piece3的属性实现，直接将C++ vector<double>的内存暴露为numpy数组视图，无需拷贝。numpy数组的修改会直接同步到C++内存：

cdef class Piece:
    cdef cpp.Piece *_cppPiece
    # 其他初始化、析构、piece1/piece2属性保持不变

    @property
    def piece3(self):
        # 直接使用C++ vector内存创建numpy视图，无拷贝
        cdef double* data_ptr = self._cppPiece.piece3.data()
        cdef int size = self._cppPiece.piece3.size()
        if size == 0:
            return np.array([], dtype=np.double)
        # 创建不拥有内存的numpy数组，修改直接作用于C++ vector
        return np.frombuffer(<char*>data_ptr, dtype=np.double, count=size)
    
    @piece3.setter
    def piece3(self, arr):
        cdef np.ndarray[np.double_t, ndim=1] np_arr = np.asarray(arr, dtype=np.double)
        self._cppPiece.piece3.resize(np_arr.shape[0])
        if np_arr.shape[0] > 0:
            # 内存拷贝，将numpy数据写入C++ vector
            memcpy(self._cppPiece.piece3.data(), np_arr.data, np_arr.nbytes)

注意：如果C++ vector<double>发生内存重新分配（如resize、push_back触发扩容），之前创建的numpy视图会失效，访问会导致未定义行为。若需持久化数组，建议显式拷贝。

2. 优化pieces的性能：实现零拷贝的代理容器 #

为Data的pieces属性实现代理类，直接映射到C++ vector<Piece>，避免创建大量Python Piece实例的拷贝。代理类实现Python序列协议，直接操作原C++内存：

首先在mytypes.pyx中新增代理类：

cdef class PieceVectorProxy:
    cdef cpp.Data* _parent_data
    cdef vector[cpp.Piece]* _cpp_vector

    def __cinit__(self, cpp.Data* parent_data):
        self._parent_data = parent_data
        self._cpp_vector = &parent_data.pieces

    def __len__(self):
        return self._cpp_vector.size()

    def __getitem__(self, int idx):
        if idx < 0 or idx >= self._cpp_vector.size():
            raise IndexError("Index out of range")
        # 返回绑定到原C++ Piece对象的Python实例，无拷贝
        cdef Piece py_piece = Piece.__new__(Piece)
        py_piece._cppPiece = &self._cpp_vector.at(idx)
        return py_piece

    def __setitem__(self, int idx, Piece value):
        if idx < 0 or idx >= self._cpp_vector.size():
            raise IndexError("Index out of range")
        self._cpp_vector.at(idx) = deref(value._cppPiece)

    def append(self, Piece value):
        self._cpp_vector.push_back(deref(value._cppPiece))

    def clear(self):
        self._cpp_vector.clear()

    def resize(self, int size):
        self._cpp_vector.resize(size)

然后修改Data类的pieces属性：

cdef class Data:
    cdef cpp.Data *_cppData
    # 初始化、析构方法保持不变

    @property
    def pieces(self):
        # 返回代理容器，无任何数据拷贝
        return PieceVectorProxy(self._cppData)
    
    # 可选：保留setter以支持直接赋值整个数组
    @pieces.setter
    def pieces(self, arr):
        self._cppData.pieces.clear()
        self._cppData.pieces.reserve(len(arr))
        for pyPiece in arr:
            self._cppData.pieces.push_back(deref(pyPiece._cppPiece))

效果：

• 访问data.pieces[i]时，直接返回绑定到原C++ Piece对象的Python实例，无需拷贝。
• 修改data.pieces[i].piece1会直接同步到C++内存。
• 代理容器支持append、clear、resize等操作，完全映射C++ vector的功能。

优化后验证 #

# 测试原地修改piece3
a = Piece()
a.piece3 = [1,2,3]
a.piece3[0] = 55
print(a.piece3)  # 输出 [55.  2.  3.]，修改直接生效

# 测试pieces的零拷贝访问
data = Data()
data.pieces.append(a)
data.pieces[0].piece2 = 100
print(data.pieces[0].piece2)  # 输出100，直接修改原C++对象

内容的提问来源于stack exchange，提问作者Eney