Best practice for flag-controlled size of return tuple?

[alecjacobson]

Hi, I'm new to writing python bindings. I'm wondering if the is the best style for dealing with flags that control which objects are returned. Generally my outputs will be Eigen matrices on the C++ side. This example is pretty representative:

  nb::object polar_svd(
    const nb::DRef<const Eigen::MatrixXN > &A,
    bool includeReflections,
    bool return_U,
    bool return_S,
    bool return_V)
  {
    Eigen::MatrixXN R, T, U, V;
    Eigen::VectorXN S;
    igl::polar_svd(A, includeReflections, R, T, U, S, V);

    std::vector<nb::object> results = {nb::cast(std::move(R)), nb::cast(std::move(T))};
    if (return_U) results.push_back(nb::cast(std::move(U)));
    if (return_S) results.push_back(nb::cast(std::move(S)));
    if (return_V) results.push_back(nb::cast(std::move(V)));

    return nb::tuple(nb::cast(std::move(results)));
  }

Alternatively I could consider every combination of the flags in a long cascade of if statements, but I'm hope for something tidier like this. Are there any pitfalls to the above approach? Any thing to improve?

[wjakob]

It seems like this kind of API might be a bit confusing to use from the Python end, and very difficult to type-check if you ever want to use MyPy/PyRight.

This aspect is not to be underestimated, since type-checkable projects are much easier to use in tools like VSCode that leverage the type annotations (you get squiggly underlines when something is wrong, and autocomplete becomes generally much more effective).

If you already computed the result, then what's wrong with just returning all of them? Then the user can ignore some return values as in

value, _, value_2, _ = command()

It ultimately ends up being less verbose and produces a function with a consistent type signature.

[wjakob]

Here in this case, I would also write: return std::make_tuple(..) with a C++ tuple, and let nanobind do all the nb::cast calls for you. You then need to include nanobind/stl/tuple.h.

[alecjacobson]

These are good points. Somehow I was under the impression python users liked these return_X flags.

[wjakob]

I think it's an bad pattern used by some NumPy/SciPy functions, but fortunately most don't do it. Given how important type checking has become in the last years, I think it's best to be avoided.

Creating std::vector to return a static fixed-sized set of things, and calling nb::cast many times inside your bindings are also best avoided. It's easiest when the C++ <-> Python interface is the actual signature of your function instead of moving that boundary into the function body. That way, you don't have do do any casting yourself.

Some advanced use cases may need this, but then you can also sometimes just make custom type caster (i.e., if there is a repeated pattern of custom style cast used in many parts of the codebase.)

[alecjacobson]

Thanks. This is super helpful. I'll rethink this