BUG: Relax finfo to be easier accessible for all user dtypes (numpy#31563)

This allows `finfo` to be used for downstream user dtypes that do not subclass `inexact` or are "complex".  Where complex is defined by whether `arr.imag/arr.real` return the same "real" dtype correspondance.

Author: seberg

doc/source/reference/c-api/array.rst

@@ -3732,6 +3732,11 @@ member of ``PyArrayDTypeMeta_Spec`` struct.
    Returns 1 on success, 0 if the constant is not available,
    or -1 with an error set.
 
+   Implementing all ``finfo`` constants allows the DType to be used together
+   with `numpy.finfo`. Complex dtypes can support ``finfo`` by implementing the
+   ``imag`` and ``real`` slots (see  :c:func:`PyUFunc_AddLoopFromSpec`) when
+   the corresponding real DType implements it.
+
    **Constant IDs**:
 
     The following constant IDs are defined for retrieving dtype-specific values:

numpy/_core/getlimits.py

@@ -10,7 +10,7 @@
 from numpy._utils import set_module
 
 from . import numeric, numerictypes as ntypes
-from ._multiarray_umath import _populate_finfo_constants
+from ._multiarray_umath import _finfo_get_realdtype, _populate_finfo_constants
 
 
 def _fr0(a):
@@ -27,12 +27,6 @@ def _fr1(a):
     return a
 
 
-_convert_to_float = {
-    ntypes.csingle: ntypes.single,
-    ntypes.complex128: ntypes.float64,
-    ntypes.clongdouble: ntypes.longdouble
-    }
-
 # Parameters for creating MachAr / MachAr-like objects
 _title_fmt = 'numpy {} precision floating point number'
 _MACHAR_PARAMS = {
@@ -193,17 +187,19 @@ def __new__(cls, dtype):
         if obj is not None:
             return obj
         dtypes = [dtype]
-        newdtype = ntypes.obj2sctype(dtype)
+        # Call result_type to normalize to e.g. native byte-order:
+        newdtype = numeric.result_type(dtype)
         if newdtype is not dtype:
             dtypes.append(newdtype)
             dtype = newdtype
-        if not issubclass(dtype, numeric.inexact):
-            raise ValueError(f"data type {dtype!r} not inexact")
+
         obj = cls._finfo_cache.get(dtype)
         if obj is not None:
             return obj
-        if not issubclass(dtype, numeric.floating):
-            newdtype = _convert_to_float[dtype]
+
+        sctype = newdtype.type
+        if sctype is not None and not issubclass(sctype, numeric.floating):
+            newdtype = _finfo_get_realdtype(dtype)
             if newdtype is not dtype:
                 # dtype changed, for example from complex128 to float64
                 dtypes.append(newdtype)

numpy/_core/src/multiarray/multiarraymodule.c

@@ -4350,6 +4350,97 @@ normalize_axis_index(PyObject *NPY_UNUSED(self),
 }
 
 
+static int
+resolve_part_view_descr(
+        PyBoundArrayMethodObject *meth, PyArray_Descr *descr,
+        PyArray_Descr **part_descr, npy_intp *view_offset)
+{
+    PyArray_Descr *descrs[2] = {descr, NULL};
+    PyArray_Descr *loop_descrs[2] = {NULL, NULL};
+    int res = meth->method->resolve_descriptors(
+            meth->method, meth->dtypes, descrs, loop_descrs, view_offset);
+    if (res < 0) {
+        return -1;
+    }
+
+    Py_DECREF(loop_descrs[0]);
+    *part_descr = loop_descrs[1];
+    return 0;
+}
+
+
+/*
+ * Resolve the descriptor for a dtype's `.real` or `.imag` method and
+ * indicate whether the result is a view (1), not a view (0), or errored (-1).
+ */
+static int
+resolve_view_part_descr(
+        PyBoundArrayMethodObject *meth, PyArray_Descr *descr,
+        PyArray_Descr **part_descr)
+{
+    if (meth == NULL) {
+        return 0;
+    }
+    npy_intp view_offset = NPY_MIN_INTP;
+    if (resolve_part_view_descr(meth, descr, part_descr, &view_offset) < 0) {
+        return -1;
+    }
+    return view_offset != NPY_MIN_INTP;
+}
+
+
+/*
+ * Resolve the real counterpart dtype for dtypes that expose compatible
+ * `.real`/`.imag` views. If not available, returns the input dtype unchanged
+ * (i.e. assume already a real dtype).
+ */
+static PyObject *
+_finfo_get_realdtype(PyObject *NPY_UNUSED(self), PyObject *descr_obj)
+{
+    if (!PyArray_DescrCheck(descr_obj)) {
+        PyErr_SetString(PyExc_TypeError, "Argument must be a dtype");
+        return NULL;
+    }
+    PyArray_Descr *descr = (PyArray_Descr *)descr_obj;
+    PyArray_Descr *real_descr = NULL;
+    PyArray_Descr *imag_descr = NULL;
+    PyArray_Descr *ret = NULL;
+
+    int real_is_view = resolve_view_part_descr(
+            NPY_DT_SLOTS(NPY_DTYPE(descr))->real_meth, descr, &real_descr);
+    if (real_is_view < 0) {
+        goto finish;
+    }
+    if (!real_is_view) {
+        ret = descr;
+        goto finish;
+    }
+
+    int imag_is_view = resolve_view_part_descr(
+            NPY_DT_SLOTS(NPY_DTYPE(descr))->imag_meth, descr, &imag_descr);
+    if (imag_is_view < 0) {
+        goto finish;
+    }
+    if (!imag_is_view) {
+        ret = descr;
+        goto finish;
+    }
+
+    if (PyArray_EquivTypes(real_descr, imag_descr)) {
+        ret = real_descr;
+    }
+    else {
+        ret = descr;
+    }
+
+  finish:
+    Py_XINCREF(ret);
+    Py_XDECREF(real_descr);
+    Py_XDECREF(imag_descr);
+    return (PyObject *)ret;
+}
+
+
 static PyObject *
 _populate_finfo_constants(PyObject *NPY_UNUSED(self), PyObject *args)
 {
@@ -4416,8 +4507,9 @@ _populate_finfo_constants(PyObject *NPY_UNUSED(self), PyObject *args)
                 goto fail;
             }
             if (res == 0) {
-                buffer_data += elsize;  // Move to next element
-                continue;
+                PyErr_Format(PyExc_ValueError,
+                    "data type %R not compatible with finfo", descr);
+                goto fail;
             }
             // Return as 0-d array item to preserve numpy scalar type
             value_obj = PyArray_ToScalar(buffer_data, buffer_array);
@@ -4430,7 +4522,9 @@ _populate_finfo_constants(PyObject *NPY_UNUSED(self), PyObject *args)
                 goto fail;
             }
             if (res == 0) {
-                continue;
+                PyErr_Format(PyExc_ValueError,
+                    "data type %R not compatible with finfo", descr);
+                goto fail;
             }
             value_obj = PyLong_FromSsize_t(int_value);
         }
@@ -4702,6 +4796,8 @@ static struct PyMethodDef array_module_methods[] = {
         METH_FASTCALL | METH_KEYWORDS, NULL},
     {"_populate_finfo_constants", (PyCFunction)_populate_finfo_constants,
         METH_VARARGS, NULL},
+    {"_finfo_get_realdtype", (PyCFunction)_finfo_get_realdtype,
+        METH_O, NULL},
     /* from umath */
     {"frompyfunc",
         (PyCFunction) ufunc_frompyfunc,

numpy/_core/tests/test_getlimits.py

@@ -9,6 +9,7 @@
 import numpy as np
 from numpy import double, half, longdouble, single
 from numpy._core import finfo, iinfo
+from numpy._core._rational_tests import rational
 from numpy.testing import assert_, assert_equal, assert_raises
 
 ##################################################
@@ -48,7 +49,7 @@ def assert_finfo_equal(f1, f2):
     for attr in ('bits', 'eps', 'epsneg', 'iexp', 'machep',
                  'max', 'maxexp', 'min', 'minexp', 'negep', 'nexp',
                  'nmant', 'precision', 'resolution', 'tiny',
-                 'smallest_normal', 'smallest_subnormal'):
+                 'smallest_normal', 'smallest_subnormal', 'dtype'):
         assert_equal(getattr(f1, attr), getattr(f2, attr),
                      f'finfo instances {f1} and {f2} differ on {attr}')
 
@@ -66,7 +67,20 @@ def test_basic(self):
         for dt1, dt2 in dts:
             assert_finfo_equal(finfo(dt1), finfo(dt2))
 
-        assert_raises(ValueError, finfo, 'i4')
+    @pytest.mark.parametrize('dt1, dt2',
+        [('>f2', '<f2'), ('>f4', '<f4'), ('>f8', '<f8'), ('>c8', '<c8'),
+         ('>c16', '<c16')])
+    def test_byteorder(self, dt1, dt2):
+        # finfo should normalize to native byte-order.
+        assert_finfo_equal(finfo(dt1), finfo(dt2))
+
+    @pytest.mark.parametrize('dt', [
+            np.int8, "V3", "S3", "f,f", rational, "O", "T"])
+    def test_rejects_others(self, dt):
+        dtype = np.dtype(dt)
+        with pytest.raises(ValueError,
+                match=r"data type .* not compatible with finfo"):
+            finfo(dtype)
 
     def test_regression_gh23108(self):
         # np.float32(1.0) and np.float64(1.0) have the same hash and are