pyo3-arrow

轻量级的Apache Arrow集成，用于pyo3。旨在使Rust库更容易添加互操作、零拷贝的Python绑定。

具体来说，pyo3-arrow使用arrowcrate实现了Python对象和Rust表示之间的零拷贝FFI转换。这依赖于Arrow PyCapsule接口，以实现Python Arrow生态系统中的无缝互操作性。

使用方法

我们只需用几行代码就可以包装一个在Python中使用的函数。

当您将定义在pyo3_arrow中的结构体用作函数的参数时，它将通过零拷贝FFI自动将用户输入转换为Rust arrow对象。然后，一旦完成，调用to_arro3或to_pyarrow将数据导回到Python。

use pyo3::prelude::*;
use pyo3_arrow::error::PyArrowResult;
use pyo3_arrow::PyArray;

/// Take elements by index from an Array, creating a new Array from those
/// indexes.
#[pyfunction]
pub fn take(py: Python, values: PyArray, indices: PyArray) -> PyArrowResult<PyObject> {
    // We can call py.allow_threads to ensure the GIL is released during our
    // operations
    // This example just wraps `arrow_select::take::take`
    let output_array =
        py.allow_threads(|| arrow_select::take::take(values.as_ref(), indices.as_ref(), None))?;

    // Construct a PyArray and export it to the arro3 Python Arrow
    // implementation
    Ok(PyArray::new(output_array, values.field().clone()).to_arro3(py)?)
}

然后在Python端，我们可以调用这个函数（通过arro3.compute.take导出）

import pyarrow as pa
from arro3.compute import take

arr = pa.array([2, 3, 0, 1])
output = take(arr, arr)
output
# <arro3.core._rust.Array at 0x10787b510>
pa.array(output)
# <pyarrow.lib.Int64Array object at 0x10aa11000>
# [
#   0,
#   1,
#   2,
#   3
# ]

在这个例子中，我们使用pyarrow创建原始数组并查看结果，但不需要使用pyarrow。它确实展示了Arrow PyCapsule接口如何使这些Arrow对象在Python Arrow实现之间共享变得无缝。

使用Arrow数据作为输入

只需在您的函数签名中包含pyo3-arrow的一个结构体，用户输入将自动转换

这使用了Arrow PyCapsule接口。但请注意，它只定义了三个方法，而pyo3-arrow包含更多的结构体。几个结构体是重载的，并使用相同的底层传输机制。

例如，PySchema和PyField都使用__arrow_c_schema__机制，但行为不同。前者期望传输的字段是结构体类型，其子节点会被解包为模式中的字段，而后者没有约束，以原样传递字段。PySchema如果传入的字段不是结构体类型，则会出错。

PyArray 和 PyRecordBatch 都使用了 __arrow_c_array__ 机制。

PyTable、PyChunkedArray 和 PyRecordBatchReader 都使用了 __arrow_c_stream__ 机制。

将 Arrow 数据返回到 Python。

使用您自己的类

如果您正在将您自己的 Arrow 兼容类导出到 Python，您可以直接在您自己的类上实现相关的 Arrow PyCapsule 接口方法。

要导出流数据，请添加一个具有以下签名的类方法

use pyo3_arrow::ffi::to_stream_pycapsule;

fn __arrow_c_stream__<'py>(
    &'py self,
    py: Python<'py>,
    requested_schema: Option<Bound<PyCapsule>>,
) -> PyResult<Bound<'py, PyCapsule>> {

    // Construct a PyTable from your data
    let table: PyTable = todo!();
    table.__arrow_c_stream__(py, requested_schema)
}

导出模式或数组数据类似于，只是使用 __arrow_c_schema__ 和 __arrow_c_array__ 方法。

如果您不想导出您自己的类，请参考以下解决方案。

使用 arro3.core

arro3.core 是一个非常轻量级的 Python Arrow 实现，设计用于轻量级（<1MB）和相对稳定。相比之下，pyarrow 大约是 ~100MB。

您必须依赖于 arro3-core Python 包；然后您可以使用每个导出的 Arrow 对象的 to_arro3 方法将数据传递到 arro3.core 类。

使用 pyarrow

pyarrow，标准的 Python Arrow 实现，是一个非常庞大的依赖项。它本身大约有 100MB 的大小，加上对 numpy 的强依赖性，大约还有 35MB。然而，numpy 很可能在用户环境中已经存在，pyarrow 也相当常见，因此要求 pyarrow 依赖项可能不是问题。

在这种情况下，您必须依赖于 pyarrow，并且您可以使用 Python 结构体的 to_pyarrow 方法将数据返回到 Python。这需要 pyarrow>=14（要返回 PyRecordBatchReader，则需要 pyarrow>=15）。