diff --git a/docs/ndarray.rst b/docs/ndarray.rst index 57c704b6..849fe2be 100644 --- a/docs/ndarray.rst +++ b/docs/ndarray.rst @@ -626,6 +626,37 @@ this type. } else { /* ... */ } } +Array libraries +--------------- + +The Python `array API standard `__ +defines a common interface and interchange protocol for nd-array libraries. In particular, to +support inter-framework data exchange, custom array types should implement the + +- `__dlpack__ `__ and +- `__dlpack_device__ `__ + +methods. This is easy thanks to the nd-array integration in nanobind. An example is shown below: + +.. code-block:: cpp + + nb::class_(m, "MyArray") + // ... + .def("__dlpack__", [](nb::kwargs kwargs) { + return nb::ndarray<>( /* ... */); + }) + .def("__dlpack_device__", []() { + return std::make_pair(nb::device::cpu::value, 0); + }); + +Returning a raw :cpp:class:`nb::ndarray ` without framework annotation +will produce a DLPack capsule, which is what the interface expects. + +The ``kwargs`` argument can be used to provide additional parameters (for +example to request a copy), please see the DLPack documentation for details. +Note that nanobind does not yet implement the versioned DLPack protocol. The +version number should be ignored for now. + Frequently asked questions --------------------------