What is the correct return value policy for a def_rw accessor to an nb::ndarray member variable?

[mikeroberts3000]

Hello there, I have a quick silly question about return value policies. In particular, I'm curious about the correct return value policy to use in the following situation. Suppose I have a C++ container class that defines an nb::ndarray member variable.

struct Container
{
    nb::ndarray<nb::numpy> array;
};

Suppose I use nanobind to define a make_container method at module scope in a Python extension module. Suppose this method: (1) creates a new Container object on the stack; (2) allocates some heap memory; (3) creates a new nb::ndarray object on the stack using the heap-allocated memory for its internal storage; (4) assigns the stack-allocated nb::ndarray to the stack-allocated Container object's array member variable; and (5) returns the Container object.

NB_MODULE(my_ext, m)
{
    auto container_class = nanobind::class_<Container>(m, "Container");
    container_class.def(nanobind::init<>());
    container_class.def_rw("array", &Container::array, nb::rv_policy::reference);

    m.def("make_container", []() -> Container {
        Container container;
        float* data = new float[10];
        for (int i = 0; i < 10; i++) {
            data[i] = (float)i;
        }
        nb::capsule capsule = nb::capsule(data, [](void* data) noexcept -> void { delete[] (float*)data; });
        container.array = nb::ndarray<nb::numpy>(data, {10}, capsule, {}, nb::dtype<float>());
        return container;
    });
}

In Python code, suppose I want to call make_container and access the returned NumPy array as follows.

container = my_ext.make_container()
array = container.array
container = None
print(array)
array = None

If I don't explicitly set a return value policy when calling def_rw(...), I get the following error when attempting to access container.array in the Python code above.

RuntimeError: nanobind::detail::ndarray_export(): reference_internal policy cannot be applied (ndarray already has an owner)

In contrast, if I set nb::rv_policy::reference as the return value policy (as shown in the code snippet above), then this Python code behaves exactly as expected. When using nb::rv_policy::reference, the deletion callback for the nb::ndarray gets called immediately after I assign array = None, but not before, which is exactly what I would expect. I verified the exact order of operations using print statements that I have omitted from the code above for brevity.

This result has led to some confusion on my side though.

• Is nb::rv_policy::reference the correct policy to use in this type of situation, or does it just happen to work correctly in this specific case?
• Why isn't nb::rv_policy::reference_internal the correct policy to use? The documentation suggests this policy should be used when accessing member fields, so I would have guessed that it should be used here.
• When using nb::rv_policy::reference, does assigning array = container.array increment some kind of reference count on the nb::ndarray& reference returned by the def_rw(...) accessor? I'm assuming the accessor returns a reference but it wasn't totally clear to me if this is the case. When using nb::rv_policy::reference, how does Python know to wait until array = None before calling the deletion callback for the nb::ndarray?