如何无拷贝将datetime64[ns]数组传递给pybind11

问题1：pybind11是否有对应datetime64[ns]的专用类型？ #

pybind11官方未提供适配numpy datetime64[ns]的内置专用类型，无法直接以py::array_t<DateTime>的形式原生接收该类数组，需要自行做底层内存适配。

问题2：无拷贝传递的实现方案 #

存在完全轻量无拷贝的方案，无需复制数组内存，datetime64[ns]底层本身就是以连续int64类型存储纳秒时间戳，有两种常用实现路径：

路径1：C++侧直接接收datetime64数组，自行解析底层数据 #

无需Python侧做任何预处理，C++侧先做类型校验后直接读取底层int64指针即可，示例代码如下：

#include <pybind11/pybind11.h>
#include <pybind11/numpy.h>

namespace py = pybind11;

void process_datetime_arr(py::array arr) {
    // 校验输入类型合法性
    if (py::str(arr.dtype()) != "datetime64[ns]") {
        throw std::runtime_error("仅支持datetime64[ns]类型的数组输入");
    }
    // 直接获取底层int64指针，无任何内存拷贝
    const int64_t* data = static_cast<const int64_t*>(arr.data());
    const py::ssize_t arr_size = arr.size();

    // 遍历读取纳秒时间戳执行业务逻辑即可
    for (py::ssize_t i = 0; i < arr_size; ++i) {
        int64_t ns_timestamp = data[i];
        // 你的自定义处理逻辑
    }
}

PYBIND11_MODULE(example_moudle, m) {
    m.def("process_datetime_arr", &process_datetime_arr, "接收并处理datetime64[ns]数组");
}

Python侧调用时直接传入datetime64数组即可：

import numpy as np
import example_moudle

test_arr = np.array(['2024-01-01', '2024-01-02', '2024-01-03'], dtype='datetime64[ns]')
example_moudle.process_datetime_arr(test_arr)

路径2：Python侧生成无拷贝视图后传递 #

如果希望C侧代码更简洁，不需要处理类型校验，可以在Python侧先做dtype视图转换，该操作完全无拷贝，和原数组共享底层内存：
C侧直接接收int64数组即可：

#include <pybind11/pybind11.h>
#include <pybind11/numpy.h>

namespace py = pybind11;

void process_datetime_arr(py::array_t<int64_t> arr) {
    auto arr_view = arr.unchecked<1>(); // 1维数组场景，多维可调整模板参数
    for (py::ssize_t i = 0; i < arr_view.shape(0); ++i) {
        int64_t ns_timestamp = arr_view(i);
        // 你的自定义处理逻辑
    }
}

PYBIND11_MODULE(example_moudle, m) {
    m.def("process_datetime_arr", &process_datetime_arr, "处理转换后的datetime时间戳数组");
}

Python侧调用代码：

import numpy as np
import example_moudle

test_arr = np.array(['2024-01-01', '2024-01-02', '2024-01-03'], dtype='datetime64[ns]')
# 生成int64视图，无内存拷贝
int_view = test_arr.view('int64')
example_moudle.process_datetime_arr(int_view)

注意事项 #

• 两种方案的性能和直接传递原生int64数组完全一致，没有额外开销
• 如果需要修改数组内容，操作会直接同步到原Python侧的datetime64数组，因为二者共享内存
• 传递前建议确认datetime的单位为ns，避免时间戳单位不匹配导致逻辑错误

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