numpy · mhvk · Oct 12, 2025 · Oct 8, 2025 · Oct 12, 2025 · Oct 12, 2025
diff --git a/doc/release/upcoming_changes/29900.c_api.rst b/doc/release/upcoming_changes/29900.c_api.rst
@@ -0,0 +1,5 @@
+A new `PyUFunc_AddLoopsFromSpecs` convenience function has been added to the C API.
+-----------------------------------------------------------------------------------
+This function allows adding multiple ufunc loops from their specs in one call using
+a NULL-terminated array of `PyUFunc_LoopSlot` structs. It allows registering
+sorting and argsorting loops using the new ArrayMethod API.
diff --git a/doc/release/upcoming_changes/29900.new_feature.rst b/doc/release/upcoming_changes/29900.new_feature.rst
@@ -0,0 +1,9 @@
+DType sorting and argsorting supports the ArrayMethod API
+---------------------------------------------------------
+User-defined dtypes can now implement custom sorting and argsorting using
+the ArrayMethod API. This mechanism can be used in place of the `PyArray_ArrFuncs`
+slots which may be deprecated in the future.
+
+The sorting and argsorting methods are registered by passing the arraymethod
+specs that implement the operations to the new `PyUFunc_AddLoopsFromSpecs` function.
+See the ArrayMethod API documentation for details.
diff --git a/doc/source/reference/c-api/array.rst b/doc/source/reference/c-api/array.rst
@@ -1886,6 +1886,34 @@ with the rest of the ArrayMethod API.
    the main ufunc registration function.  This adds a new implementation/loop
    to a ufunc.  It replaces `PyUFunc_RegisterLoopForType`.
 
+.. c:type:: PyUFunc_LoopSlot
+
+   Structure used to add multiple loops to ufuncs from ArrayMethod specs.
+   This is used in `PyUFunc_AddLoopsFromSpecs`.
+
+    .. c:struct:: PyUFunc_LoopSlot
+
+        .. c:member:: const char *name
+
+            The name of the ufunc to add the loop to.
+
+        .. c:member:: PyArrayMethod_Spec *spec
+
+            The ArrayMethod spec to use to create the loop.
+
+.. c:function:: int PyUFunc_AddLoopsFromSpecs( \
+                        PyUFunc_LoopSlot *slots)
+
+    .. versionadded:: 2.4
+
+    Add multiple loops to ufuncs from ArrayMethod specs. This also
+    handles the registration of methods for the ufunc-like functions
+    ``sort`` and ``argsort``. See :ref:`array-methods-sorting` for details.
+
+    The ``slots`` argument must be a  NULL-terminated array of
+    `PyUFunc_LoopSlot` (see above), which give the name of the
+    ufunc and spec needed to create the loop.
+
 .. c:function:: int PyUFunc_AddPromoter( \
                         PyObject *ufunc, PyObject *DType_tuple, PyObject *promoter)
 
@@ -2036,6 +2064,36 @@ code:
         Py_INCREF(loop_descrs[2]);
     }
 
+.. _array-methods-sorting:
+
+Sorting and Argsorting
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Sorting and argsorting methods for dtypes can be registered using the
+ArrayMethod API. This is done by adding an ArrayMethod spec with the name
+``"sort"`` or ``"argsort"`` respectively.  The spec must have ``nin=1``
+and ``nout=1`` for both sort and argsort. Sorting is inplace, hence we
+enforce that ``data[0] == data[1]``. Argsorting returns a new array of
+indices, so the output must be of ``NPY_INTP`` type.
+
+The ``context`` passed to the loop contains the ``parameters`` field which
+for these operations is a ``PyArrayMethod_SortParameters *`` struct. This
+struct contains a ``flags`` field which is a bitwise OR of ``NPY_SORTKIND``
+values indicating the kind of sort to perform (that is, whether it is a
+stable and/or descending sort). If the strided loop depends on the flags,
+a good way to deal with this is to define :c:macro:`NPY_METH_get_loop`,
+and not set any of the other loop slots.
+
+.. c:struct:: PyArrayMethod_SortParameters
+
+    .. c:member:: NPY_SORTKIND flags
+
+        The flags passed to the sort operation. This is a bitwise OR of
+        ``NPY_SORTKIND`` values indicating the kind of sort to perform.
+
+These specs can be registered using :c:func:`PyUFunc_AddLoopsFromSpecs`
+along with other ufunc loops.
+
 API for calling array methods
 -----------------------------
 

diff --git a/numpy/_core/code_generators/cversions.txt b/numpy/_core/code_generators/cversions.txt
@@ -80,5 +80,7 @@
 0x00000013 = 2b8f1f4da822491ff030b2b37dff07e3
 # Version 20 (NumPy 2.3.0)
 0x00000014 = e56b74d32a934d085e7c3414cb9999b8,
-# Version 21 (NumPy 2.4.0) Add 'same_value' casting, header additions
-0x00000015 = e56b74d32a934d085e7c3414cb9999b8,
+# Version 21 (NumPy 2.4.0)
+# Add 'same_value' casting, header additions.
+# General loop registration for ufuncs, sort, and argsort
+0x00000015 = fbd24fc5b2ba4f7cd3606ec6128de7a5
diff --git a/numpy/_core/code_generators/numpy_api.py b/numpy/_core/code_generators/numpy_api.py
@@ -412,7 +412,7 @@ def get_annotations():
 }
 
 ufunc_types_api = {
-    'PyUFunc_Type':                             (0,)
+    'PyUFunc_Type':                             (0,),
 }
 
 ufunc_funcs_api = {
@@ -468,6 +468,8 @@ def get_annotations():
     'PyUFunc_AddPromoter':                           (44, MinVersion("2.0")),
     'PyUFunc_AddWrappingLoop':                       (45, MinVersion("2.0")),
     'PyUFunc_GiveFloatingpointErrors':               (46, MinVersion("2.0")),
+    # End 2.0 API
+    'PyUFunc_AddLoopsFromSpecs':                     (47, MinVersion("2.4")),
 }
 
 # List of all the dicts which define the C API

diff --git a/numpy/_core/include/numpy/dtype_api.h b/numpy/_core/include/numpy/dtype_api.h
@@ -145,6 +145,13 @@ typedef struct {
 } PyArrayMethod_Spec;
 
 
+// This is used for the convenience function `PyUFunc_AddLoopsFromSpecs`
+typedef struct {
+    const char *name;
+    PyArrayMethod_Spec *spec;
+} PyUFunc_LoopSlot;
+
+
 /*
  * ArrayMethod slots
  * -----------------

diff --git a/numpy/_core/src/common/npy_import.h b/numpy/_core/src/common/npy_import.h
@@ -6,6 +6,10 @@
 #include "numpy/npy_common.h"
 #include "npy_atomic.h"
 
+#ifdef __cplusplus
+extern "C" {
+#endif
+
 /*
  * Cached references to objects obtained via an import. All of these are
  * can be initialized at any time by npy_cache_import_runtime.
@@ -45,6 +49,8 @@ typedef struct npy_runtime_imports_struct {
     PyObject *_var;
     PyObject *_view_is_safe;
     PyObject *_void_scalar_to_string;
+    PyObject *sort;
+    PyObject *argsort;
 } npy_runtime_imports_struct;
 
 NPY_VISIBILITY_HIDDEN extern npy_runtime_imports_struct npy_runtime_imports;
@@ -112,4 +118,8 @@ npy_cache_import_runtime(const char *module, const char *attr, PyObject **obj) {
 NPY_NO_EXPORT int
 init_import_mutex(void);
 
+#ifdef __cplusplus
+}
+#endif
+
 #endif  /* NUMPY_CORE_SRC_COMMON_NPY_IMPORT_H_ */