Deprecated _add_newdoc_ufunc

Author: mtsokol

doc/release/upcoming_changes/27735.new_feature.rst

@@ -1,3 +1,7 @@
 * UFuncs now support ``__dict__`` attribute and allow overriding ``__doc__``
   (either directly or via ``ufunc.__dict__["__doc__"]``). ``__dict__`` can be
-  used to also override other properties, such as ``__module__`` or ``__qualname__``.
+  used to also override other properties, such as ``__module__`` or
+  ``__qualname__``.
+
+* ``_add_newdoc_ufunc`` is now deprecated. ``ufunc.__doc__ = newdoc`` should
+  be used instead.

numpy/_core/src/umath/_struct_ufunc_tests.c

@@ -133,8 +133,8 @@ PyMODINIT_FUNC PyInit__struct_ufunc_tests(void)
     import_umath();
 
     add_triplet = PyUFunc_FromFuncAndData(NULL, NULL, NULL, 0, 2, 1,
-                                    PyUFunc_None, "add_triplet",
-                                    "add_triplet_docstring", 0);
+                                          PyUFunc_None, "add_triplet",
+                                          NULL, 0);
 
     dtype_dict = Py_BuildValue("[(s, s), (s, s), (s, s)]",
                                "f0", "u8", "f1", "u8", "f2", "u8");

numpy/_core/src/umath/umathmodule.c

@@ -167,6 +167,13 @@ ufunc_frompyfunc(PyObject *NPY_UNUSED(dummy), PyObject *args, PyObject *kwds) {
 PyObject *
 add_newdoc_ufunc(PyObject *NPY_UNUSED(dummy), PyObject *args)
 {
+
+    /* 2024-11-12, NumPy 2.2 */
+    if (DEPRECATE("_add_newdoc_ufunc is deprecated. "
+                  "Use `ufunc.__doc__ = newdoc` instead.") < 0) {
+        return NULL;
+    }
+
     PyUFuncObject *ufunc;
     PyObject *str;
     if (!PyArg_ParseTuple(args, "O!O!:_add_newdoc_ufunc", &PyUFunc_Type, &ufunc,

numpy/_core/tests/test_deprecations.py

@@ -15,6 +15,7 @@
     )
 
 from numpy._core._multiarray_tests import fromstring_null_term_c_api
+import numpy._core._struct_ufunc_tests as struct_ufunc
 
 try:
     import pytz
@@ -732,3 +733,13 @@ def test_deprecated(self):
                 self.assert_deprecated(np.save, args=sample_args,
                                     kwargs={'allow_pickle': allow_pickle,
                                             'fix_imports': False})
+
+
+class TestAddNewdocUFunc(_DeprecationTestCase):
+    # Deprecated in Numpy 2.2, 2024-11
+    def test_deprecated(self):
+        self.assert_deprecated(
+            lambda: np._core.umath._add_newdoc_ufunc(
+                struct_ufunc.add_triplet, "new docs"
+            )
+        )

numpy/_core/tests/test_umath.py

@@ -4884,9 +4884,11 @@ def func():
 
 
 class TestAdd_newdoc_ufunc:
+    @pytest.mark.filterwarnings("ignore:_add_newdoc_ufunc:DeprecationWarning")
     def test_ufunc_arg(self):
         assert_raises(TypeError, ncu._add_newdoc_ufunc, 2, "blah")
         assert_raises(ValueError, ncu._add_newdoc_ufunc, np.add, "blah")
 
+    @pytest.mark.filterwarnings("ignore:_add_newdoc_ufunc:DeprecationWarning")
     def test_string_arg(self):
         assert_raises(TypeError, ncu._add_newdoc_ufunc, np.add, 3)