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

jorenham · jorenham · commit 8176a278d16d · 2025-05-01T20:57:32.000+02:00
diff --git a/doc/release/upcoming_changes/28884.deprecation.rst b/doc/release/upcoming_changes/28884.deprecation.rst
@@ -0,0 +1,65 @@
+``numpy.typing.NBitBase`` deprecation
+-------------------------------------
+:obj:`numpy.typing.NBitBase` is 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:
+
+.. code-block:: python
+
+    import numpy as np
+    import numpy.typing as npt
+
+    def f[NT: npt.NBitBase](x: np.complexfloating[NT]) -> np.floating[NT]: ...
+
+However, due to changes in NumPy 2.2 where `float64` and `complex128` were
+changed to concrete subtypes of `floating` and `complexfloating`, this usage
+pattern now causes type compatibility issues. For example, `floating[_64Bit]`
+is no longer assignable to `float64`, causing type-checkers to reject valid
+code like `x: float64 = f(complex128(1))`.
+
+**Alternative approach using `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: ...
+
+While more verbose, this approach is more explicit and easier to understand.
+
+**Simpler alternative for cases where input and output types are related:**
+
+For situations where the input scalar type is the same as the output type,
+a more direct approach can be used:
+
+Old:
+
+.. code-block:: python
+
+    import numpy as np
+    import numpy.typing as npt
+
+    def f[NT: npt.NBitBase](x: np.floating[NT]) -> np.floating[NT]: ...
+
+New:
+
+.. code-block:: python
+
+    import numpy as np
+
+    def f[FloatT: np.floating](x: FloatT) -> FloatT: ...
+
+This new approach is not only more concise but also more readable.
+
+Note: The compatibility issue with `NBitBase` becomes more critical as NumPy
+and its type system evolve. In NumPy's upcoming typing system, all scalar types
+will be proper subtypes rather than type aliases, making this deprecation
+necessary for future type checking accuracy.
