DEP: Deprecate PyUFunc_GenericFunction public C-API function

This function provides mainly the same API as PyObject_Call()
with the exception of skipping ufunc overrides and output array
wraps.
It is fairly unwieldy to use, since ownership of all inputs and
outputs is transferred, but otherwise it still uses args and kwargs
as inputs.

As such, no known usage exists and PyObject_Call seems a reasonable
replacement for possible usage. Keeping it around means that we would
may have to add tests or risk breaking this function when ufunc
code is refactored.

1 files changed, 10 insertions, 9 deletions

diff --git a/doc/source/reference/c-api/ufunc.rst b/doc/source/reference/c-api/ufunc.rst
index c9cc60141..a5fee7570 100644
--- a/doc/source/reference/c-api/ufunc.rst
+++ b/doc/source/reference/c-api/ufunc.rst
@@ -253,15 +253,16 @@ Functions
 .. c:function:: int PyUFunc_GenericFunction( \
         PyUFuncObject* self, PyObject* args, PyObject* kwds, PyArrayObject** mps)
 
-    A generic ufunc call. The ufunc is passed in as *self*, the arguments
-    to the ufunc as *args* and *kwds*. The *mps* argument is an array of
-    :c:type:`PyArrayObject` pointers whose values are discarded and which
-    receive the converted input arguments as well as the ufunc outputs
-    when success is returned. The user is responsible for managing this
-    array and receives a new reference for each array in *mps*. The total
-    number of arrays in *mps* is given by *self* ->nin + *self* ->nout.
-
-    Returns 0 on success, -1 on error.
+    .. deprecated:: NumPy 1.19
+
+        Unless NumPy is made aware of an issue with this, this function
+        is scheduled for rapid removal without replacement.
+
+    Instead of this function ``PyObject_Call(ufunc, args, kwds)`` should be
+    used. The above function differs from this because it ignores support
+    for non-array, or array subclasses as inputs.
+    To ensure identical behaviour, it may be necessary to convert all inputs
+    using ``PyArray_FromAny(obj, NULL, 0, 0, NPY_ARRAY_ENSUREARRAY, NULL)``.
 
 .. c:function:: int PyUFunc_checkfperr(int errmask, PyObject* errobj)