DOC: add release note for the numpy.typing.NBitBase deprecation

jorenham · jorenham · commit 72fcaa926f84 · 2025-05-01T23:23:28.000+02:00
diff --git a/doc/release/upcoming_changes/28884.deprecation.rst b/doc/release/upcoming_changes/28884.deprecation.rst
@@ -0,0 +1,28 @@
+``numpy.typing.NBitBase`` deprecation
+-------------------------------------
+The ``numpy.typing.NBitBase`` type has been deprecated and will be removed in a future version.
+
+This type was previously intended to be used as a generic upper bound for type-parameters, for example:
+
+.. code-block:: python
+
+    import numpy as np
+    import numpy.typing as npt
+
+    def f[NT: npt.NBitBase](x: np.complexfloating[NT]) -> np.floating[NT]: ...
+
+But in NumPy 2.2.0, ``float64`` and ``complex128`` were changed to concrete subtypes, causing static type-checkers to reject ``x: np.float64 = f(np.complex128(42j))``.
+
+So instead, the better approach is to use ``typing.overload``:
+
+.. code-block:: python
+
+    import numpy as np
+    from typing import overload
+
+    @overload
+    def f(x: np.complex64) -> np.float32: ...
+    @overload
+    def f(x: np.complex128) -> np.float64: ...
+    @overload
+    def f(x: np.clongdouble) -> np.longdouble: ...
