gh-153740: support _Float16 complex in struct/array modules

Doc/conf.py

@@ -226,6 +226,9 @@
     ('envvar', 'USERPROFILE'),
 ]
 
+# Tell Sphinx to accept these tokens as valid parts of a C type/identifier
+c_id_attributes = ['_Float16']
+
 # Temporary undocumented names.
 # In future this list must be empty.
 nitpick_ignore += [

Doc/library/array.rst

@@ -46,9 +46,11 @@ defined:
 +-----------+--------------------+-------------------+-----------------------+-------+
 | ``'d'``   | double             | float             | 8                     |       |
 +-----------+--------------------+-------------------+-----------------------+-------+
-| ``'Zf'``  | float complex      | complex           | 8                     | \(3)  |
+| ``'Ze'``  | _Float16 complex   | complex           | 4                     | \(3)  |
 +-----------+--------------------+-------------------+-----------------------+-------+
-| ``'Zd'``  | double complex     | complex           | 16                    | \(3)  |
+| ``'Zf'``  | float complex      | complex           | 8                     | \(4)  |
++-----------+--------------------+-------------------+-----------------------+-------+
+| ``'Zd'``  | double complex     | complex           | 16                    | \(4)  |
 +-----------+--------------------+-------------------+-----------------------+-------+
 
 
@@ -67,6 +69,11 @@ Notes:
    .. versionadded:: 3.15
 
 (3)
+   Complex type ``Ze`` is available unconditionally.
+
+   .. versionadded:: 3.16
+
+(4)
    Complex types (``Zf`` and ``Zd``) are available unconditionally,
    regardless on support for complex types (the Annex G of the C11 standard)
    by the C compiler.

Doc/library/struct.rst

@@ -263,6 +263,9 @@ platform-dependent.
 +--------+--------------------------+--------------------+----------------+------------+
 | ``d``  | :c:expr:`double`         | float              | 8              | \(4)       |
 +--------+--------------------------+--------------------+----------------+------------+
+| ``Ze`` | :c:expr:`_Float16        | complex            | 4              | \(10)      |
+|        | complex`                 |                    |                |            |
++--------+--------------------------+--------------------+----------------+------------+
 | ``Zf`` | :c:expr:`float complex`  | complex            | 8              | \(10)      |
 +--------+--------------------------+--------------------+----------------+------------+
 | ``Zd`` | :c:expr:`double complex` | complex            | 16             | \(10)      |
@@ -289,6 +292,9 @@ platform-dependent.
 .. versionchanged:: 3.16
    ``'F'`` and ``'D'`` formats are deprecated.
 
+.. versionchanged:: 3.16
+   Added support for ``'Ze'`` format.
+
 .. seealso::
 
    The :mod:`array` and :ref:`ctypes <ctypes-fundamental-data-types>` modules,

Doc/whatsnew/3.16.rst

@@ -108,6 +108,14 @@ New modules
 Improved modules
 ================
 
+array
+-----
+
+* Support the :c:expr:`_Float16 complex` C type in
+  the :mod:`array` module (format code ``'Ze'``).
+  (Contributed by Sergey B Kirpichev in :gh:`153740`.)
+
+
 asyncio
 -------
 
@@ -491,6 +499,14 @@ sqlite3
   (Contributed by Jiseok CHOI in :gh:`150449`.)
 
 
+struct
+------
+
+* Support the :c:expr:`_Float16 complex` C type in
+  the :mod:`struct` module (format code ``'Ze'``).
+  (Contributed by Sergey B Kirpichev in :gh:`153740`.)
+
+
 symtable
 --------
 

Lib/test/test_array.py

@@ -144,8 +144,10 @@ def test_typecodes(self):
 IEEE_754_DOUBLE_COMPLEX_BE = 25
 IEEE_754_FLOAT16_LE = 26
 IEEE_754_FLOAT16_BE = 27
+IEEE_754_FLOAT16_COMPLEX_LE = 28
+IEEE_754_FLOAT16_COMPLEX_BE = 29
 
-MACHINE_FORMAT_CODE_MAX = 27
+MACHINE_FORMAT_CODE_MAX = 29
 
 
 class ArrayReconstructorTest(unittest.TestCase):
@@ -221,6 +223,10 @@ def test_numbers(self):
              [9006104071832581.0, float('inf'), float('-inf'), -0.0]),
             (['d'], IEEE_754_DOUBLE_BE, '>dddd',
              [9006104071832581.0, float('inf'), float('-inf'), -0.0]),
+            (['Ze'], IEEE_754_FLOAT16_COMPLEX_LE, '<ZeZeZeZe',
+             [167.0j, float('inf'), complex('1-infj'), -0.0]),
+            (['Ze'], IEEE_754_FLOAT16_COMPLEX_BE, '>ZeZeZeZe',
+             [167.0j, float('inf'), complex('1-infj'), -0.0]),
             (['Zf'], IEEE_754_FLOAT_COMPLEX_LE, '<ZfZfZfZf',
              [16711938.0j, float('inf'), complex('1-infj'), -0.0]),
             (['Zf'], IEEE_754_FLOAT_COMPLEX_BE, '>ZfZfZfZf',
@@ -1633,6 +1639,11 @@ def test_alloc_overflow(self):
             self.fail("Array of size > maxsize created - MemoryError expected")
 
 
+class ComplexHalfFloatTest(CFPTest, unittest.TestCase):
+    typecode = 'Ze'
+    minitemsize = 4
+    example = [-42j, 0, 42+1j, 1e2j, -1e3]
+
 class ComplexFloatTest(CFPTest, unittest.TestCase):
     typecode = 'Zf'
     minitemsize = 8

Lib/test/test_struct.py

@@ -1006,7 +1006,8 @@ def test_c_complex_round_trip(self):
         values = [complex(*_) for _ in combinations([1, -1, 0.0, -0.0, 2,
                                                      -3, INF, -INF, NAN], 2)]
         for z in values:
-            for f in ['Zf', 'Zd', '>Zf', '>Zd', '<Zf', '<Zd']:
+            for f in ['Zf', 'Zd', '>Zf', '>Zd', '<Zf', '<Zd',
+                      'Ze', '>Ze', '<Ze']:
                 with self.subTest(z=z, format=f):
                     round_trip = struct.unpack(f, struct.pack(f, z))[0]
                     self.assertComplexesAreIdentical(z, round_trip)

Misc/NEWS.d/next/Library/2026-09-02-06-10-09.gh-issue-153740.kNrXPv.rst

@@ -0,0 +1,2 @@
+Support the :c:expr:`_Float16 complex` C type in the :mod:`struct` and the
+:mod:`array` modules (format code ``'Ze'``).  Patch by Sergey B Kirpichev.

Modules/_struct.c

@@ -495,6 +495,30 @@ nu_double(_structmodulestate *state, const char *p, const formatdef *f)
     return PyFloat_FromDouble(x);
 }
 
+static PyObject *
+unpack_halfcomplex(const char *p, int le)
+{
+    double real = PyFloat_Unpack2(p, le);
+
+    if (real == -1.0 && PyErr_Occurred()) {
+        return NULL;
+    }
+
+    double imag = PyFloat_Unpack2(p + 2, le);
+
+    if (imag == -1.0 && PyErr_Occurred()) {
+        return NULL;
+    }
+    return PyComplex_FromDoubles(real, imag);
+}
+
+static PyObject *
+nu_halffloat_complex(_structmodulestate *state, const char *p,
+                     const formatdef *f)
+{
+    return unpack_halfcomplex(p, PY_LITTLE_ENDIAN);
+}
+
 static PyObject *
 nu_float_complex(_structmodulestate *state, const char *p, const formatdef *f)
 {
@@ -785,6 +809,34 @@ np_double(_structmodulestate *state, char *p, PyObject *v, const formatdef *f)
     return 0;
 }
 
+static int
+pack_halfcomplex(_structmodulestate *state, char *p,
+                 PyObject *v, int le)
+{
+    Py_complex c = PyComplex_AsCComplex(v);
+
+    if (c.real == -1 && PyErr_Occurred()) {
+        PyErr_SetString(state->StructError,
+                        "required argument is not a complex");
+        return -1;
+    }
+    if (PyFloat_Pack2(c.real, p, le) == -1) {
+        return -1;
+    }
+    if (PyFloat_Pack2(c.imag, p + 2, le) == -1) {
+        return -1;
+    }
+    return 0;
+
+}
+
+static int
+np_halffloat_complex(_structmodulestate *state, char *p, PyObject *v,
+                 const formatdef *f)
+{
+    return pack_halfcomplex(state, p, v, PY_LITTLE_ENDIAN);
+}
+
 static int
 np_float_complex(_structmodulestate *state, char *p, PyObject *v,
                  const formatdef *f)
@@ -857,6 +909,7 @@ static const formatdef native_table[] = {
     {"d",       sizeof(double), _Alignof(double),   nu_double,      np_double},
     {"F",       2*sizeof(float), _Alignof(float), nu_float_complex, np_float_complex},
     {"D",       2*sizeof(double), _Alignof(double), nu_double_complex, np_double_complex},
+    {"Ze",      2*sizeof(short), _Alignof(short), nu_halffloat_complex, np_halffloat_complex},
     {"Zf",      2*sizeof(float), _Alignof(float), nu_float_complex, np_float_complex},
     {"Zd",      2*sizeof(double), _Alignof(double), nu_double_complex, np_double_complex},
     {"P",       sizeof(void *), _Alignof(void *),   nu_void_p,      np_void_p},
@@ -959,6 +1012,12 @@ bu_double(_structmodulestate *state, const char *p, const formatdef *f)
     return unpack_double(p, 0);
 }
 
+static PyObject *
+bu_halffloat_complex(_structmodulestate *state, const char *p, const formatdef *f)
+{
+    return unpack_halfcomplex(p, 0);
+}
+
 static PyObject *
 bu_float_complex(_structmodulestate *state, const char *p, const formatdef *f)
 {
@@ -1128,6 +1187,12 @@ bp_double(_structmodulestate *state, char *p, PyObject *v, const formatdef *f)
     return PyFloat_Pack8(x, p, 0);
 }
 
+static int
+bp_halffloat_complex(_structmodulestate *state, char *p, PyObject *v, const formatdef *f)
+{
+    return pack_halfcomplex(state, p, v, 0);
+}
+
 static int
 bp_float_complex(_structmodulestate *state, char *p, PyObject *v, const formatdef *f)
 {
@@ -1190,6 +1255,7 @@ static formatdef bigendian_table[] = {
     {"d",       8,              0,              bu_double,      bp_double},
     {"F",       8,              0,              bu_float_complex, bp_float_complex},
     {"D",       16,             0,              bu_double_complex, bp_double_complex},
+    {"Ze",      4,              0,              bu_halffloat_complex, bp_halffloat_complex},
     {"Zf",      8,              0,              bu_float_complex, bp_float_complex},
     {"Zd",      16,             0,              bu_double_complex, bp_double_complex},
     {0}
@@ -1291,6 +1357,12 @@ lu_double(_structmodulestate *state, const char *p, const formatdef *f)
     return unpack_double(p, 1);
 }
 
+static PyObject *
+lu_halffloat_complex(_structmodulestate *state, const char *p, const formatdef *f)
+{
+    return unpack_halfcomplex(p, 1);
+}
+
 static PyObject *
 lu_float_complex(_structmodulestate *state, const char *p, const formatdef *f)
 {
@@ -1454,6 +1526,12 @@ lp_double(_structmodulestate *state, char *p, PyObject *v, const formatdef *f)
     return PyFloat_Pack8(x, p, 1);
 }
 
+static int
+lp_halffloat_complex(_structmodulestate *state, char *p, PyObject *v, const formatdef *f)
+{
+    return pack_halfcomplex(state, p, v, 1);
+}
+
 static int
 lp_float_complex(_structmodulestate *state, char *p, PyObject *v, const formatdef *f)
 {
@@ -1507,6 +1585,7 @@ static formatdef lilendian_table[] = {
     {"d",       8,              0,              lu_double,      lp_double},
     {"F",       8,              0,              lu_float_complex, lp_float_complex},
     {"D",       16,             0,              lu_double_complex, lp_double_complex},
+    {"Ze",      4,              0,              lu_halffloat_complex, lp_halffloat_complex},
     {"Zf",      8,              0,              lu_float_complex, lp_float_complex},
     {"Zd",      16,             0,              lu_double_complex, lp_double_complex},
     {0}