TYP: Explicitly mark complexfloating.__round__ as deprecated

Author: jorenham

numpy/__init__.pyi

@@ -210,7 +210,7 @@ from typing import (
 # library include `typing_extensions` stubs:
 # https://github.com/python/typeshed/blob/main/stdlib/typing_extensions.pyi
 from _typeshed import StrOrBytesPath, SupportsFlush, SupportsLenAndGetItem, SupportsWrite
-from typing_extensions import CapsuleType, Generic, LiteralString, Protocol, Self, TypeVar, overload
+from typing_extensions import CapsuleType, Generic, LiteralString, Protocol, Self, TypeVar, deprecated, overload
 
 from numpy import (
     core,
@@ -3410,22 +3410,27 @@ _ComplexValue: TypeAlias = (
     | complex  # `complex` is not a subtype of `SupportsComplex`
 )
 
-class integer(number[_NBit1]):  # type: ignore
+@type_check_only
+class _Roundable:
+    @overload
+    def __round__(self, /, ndigits: None = None) -> int: ...
+    @overload
+    def __round__(self, /, ndigits: SupportsIndex) -> Self: ...
+
+class integer(_Roundable, number[_NBit1]):  # type: ignore
     @property
     def numerator(self) -> Self: ...
     @property
     def denominator(self) -> L[1]: ...
-    @overload
-    def __round__(self, ndigits: None = ..., /) -> int: ...
-    @overload
-    def __round__(self, ndigits: SupportsIndex, /) -> Self: ...
+    def is_integer(self, /) -> L[True]: ...
 
     def item(self, args: L[0] | tuple[()] | tuple[L[0]] = ..., /) -> int: ...
     def tolist(self) -> int: ...
-    def is_integer(self) -> L[True]: ...
-    def bit_count(self) -> int: ...
-    # NOTE: `__index__` is technically defined in the bottom-most sub-classes (`int64`, `uint32`, etc)
-    def __index__(self) -> int: ...
+
+    # NOTE: `bit_count` and `__index__` are technically defined in the concrete subtypes
+    def bit_count(self, /) -> int: ...
+    def __index__(self, /) -> int: ...
+
     __truediv__: _IntTrueDiv[_NBit1]
     __rtruediv__: _IntTrueDiv[_NBit1]
     def __mod__(self, value: _IntLike_co, /) -> integer[Any]: ...
@@ -3566,16 +3571,15 @@ class inexact(number[_NBit1]): ...  # type: ignore[misc]
 
 _IntType = TypeVar("_IntType", bound=integer[Any])
 
-class floating(inexact[_NBit1]):
+class floating(_Roundable, inexact[_NBit1]):
     def __init__(self, value: _FloatValue = ..., /) -> None: ...
     def item(self, args: L[0] | tuple[()] | tuple[L[0]] = ..., /) -> float: ...
     def tolist(self) -> float: ...
-    def is_integer(self) -> builtins.bool: ...
-    def as_integer_ratio(self) -> tuple[int, int]: ...
-    @overload
-    def __round__(self, ndigits: None = ..., /) -> int: ...
-    @overload
-    def __round__(self, ndigits: SupportsIndex, /) -> Self: ...
+
+    # NOTE: `is_integer` and `as_integer_ratio` are technically defined in the concrete subtypes
+    def is_integer(self, /) -> builtins.bool: ...
+    def as_integer_ratio(self, /) -> tuple[int, int]: ...
+
     __add__: _FloatOp[_NBit1]
     __radd__: _FloatOp[_NBit1]
     __sub__: _FloatOp[_NBit1]
@@ -3742,9 +3746,14 @@ class complexfloating(inexact[_NBit1], Generic[_NBit1, _NBit2]):
     @property
     def imag(self) -> floating[_NBit2]: ...  # type: ignore[override]
 
-    # NOTE: `__complex__` is not defined here, but in each of the concrete subtypes
+    # NOTE: `__complex__` is technically defined in the concrete subtypes
     def __complex__(self, /) -> complex: ...
     def __abs__(self, /) -> floating[_NBit1 | _NBit2]: ...  # type: ignore[override]
+    @deprecated(
+        "The Python built-in `round` is deprecated for complex scalars, and will raise a `TypeError` in a future release. "
+        "Use `np.round` or `scalar.round` instead."
+    )
+    def __round__(self, /, ndigits: SupportsIndex | None = None) -> Self: ...
 
     @overload
     def __add__(self, other: _Complex64_co, /) -> complexfloating[_NBit1, _NBit2]: ...

numpy/typing/tests/data/fail/scalars.pyi

@@ -82,8 +82,6 @@ def func(a: np.float32) -> None: ...
 func(f2)  # E: incompatible type
 func(f8)  # E: incompatible type
 
-round(c8)  # E: No overload variant
-
 c8.__getnewargs__()  # E: Invalid self argument
 f2.__getnewargs__()  # E: Invalid self argument
 f2.hex()  # E: Invalid self argument