DOC: Document if a function is affected by NPY_MAXARGS

[sergiopasra]

Issue with current documentation:

Some C-API functions have a limit in the number of arguments that can handle, given by the macro NPY_MAXARGS. But that limit is not described in the documentation of the function NpyIter_MultiNew. Other functions related with iterators might be affected, but you don't know it by reading the documentation.

Idea or request for content:

Those functions that have a limit in its arguments should have that limit documented.

[m-clare]

I'd like to contribute to this if possible. I took a look at which C-API functions called NpyIter_MultiNew with a variable number of arguments (there are a few that call with nop=2 or nop=3 and turned up the following functions:

• test_nditer_too_large
• PyArray_MapIterNew
• arr_ravel_multi_index

I think the first one is just for a test, but would the other two require documentation?

[ngoldbaum]

@m-clare, no I don't think so, since none of the functions you linked to are in the public C API.

Of course we could probably internally document this in a docstring, but the issue is about functions in the public API, and I think internal documentation like that is a pretty low priority.

Functions are in the public API if their docstring is prepended with /*NUMPY_API or /*UFUNC_API.

One example of a function in the public API that is affected by this issue is PyArray_EinsteinSum, since the nop restriction is enforced at runtime and it uses NPY_MAXARGS in its definition.

[m-clare]

Ah ok; thanks for the tip about public functions. I had rgreped looking for NPY_MAXARGS but I actually thought PyArray_EinsteinSum was already covered, because it does have a value error:

    /* nop+1 (+1 is for the output) must fit in NPY_MAXARGS */
    if (nop >= NPY_MAXARGS) {
        PyErr_SetString(PyExc_ValueError,
                    "too many operands provided to einstein sum function");
        return NULL;
    }

I'll take a closer look at other functions in the public API that are missing any handling.

[ngoldbaum]

The runtime error is one thing, but I think the ask in the issue is that the limit should be explicitly included in the docs. Note the C API docs are entered manually in sphinx and are not generated from the docstrings.

[sergiopasra]

Yes, what I was asking is to document the limit in the public API docs, in both the Python and C API.