Improve stubs for __pow__ (#6287)

Author: AlexWaygood

stdlib/builtins.pyi

@@ -221,9 +221,13 @@ class int:
     def __rmod__(self, __x: int) -> int: ...
     def __rdivmod__(self, __x: int) -> tuple[int, int]: ...
     @overload
-    def __pow__(self, __x: Literal[2], __modulo: int | None = ...) -> int: ...
+    def __pow__(self, __x: int, __modulo: Literal[0]) -> NoReturn: ...
     @overload
-    def __pow__(self, __x: int, __modulo: int | None = ...) -> Any: ...  # Return type can be int or float, depending on x.
+    def __pow__(self, __x: Literal[2, 3, 4, 5], __modulo: int | None = ...) -> int: ...
+    # positive x -> int; negative x -> float
+    # return type must be Any as `int | float` causes too many false-positive errors
+    @overload
+    def __pow__(self, __x: int, __modulo: int | None = ...) -> Any: ...
     def __rpow__(self, __x: int, __mod: int | None = ...) -> Any: ...
     def __and__(self, __n: int) -> int: ...
     def __or__(self, __n: int) -> int: ...
@@ -276,9 +280,12 @@ class float:
     def __truediv__(self, __x: float) -> float: ...
     def __mod__(self, __x: float) -> float: ...
     def __divmod__(self, __x: float) -> tuple[float, float]: ...
-    def __pow__(
-        self, __x: float, __mod: None = ...
-    ) -> float: ...  # In Python 3, returns complex if self is negative and x is not whole
+    @overload
+    def __pow__(self, __x: int, __mod: None = ...) -> float: ...
+    # positive x -> float; negative x -> complex
+    # return type must be Any as `float | complex` causes too many false-positive errors
+    @overload
+    def __pow__(self, __x: float, __mod: None = ...) -> Any: ...
     def __radd__(self, __x: float) -> float: ...
     def __rsub__(self, __x: float) -> float: ...
     def __rmul__(self, __x: float) -> float: ...
@@ -1271,25 +1278,35 @@ class _SupportsPow3(Protocol[_E, _M, _T_co]):
 
 if sys.version_info >= (3, 8):
     @overload
-    def pow(base: int, exp: int, mod: None = ...) -> Any: ...  # returns int or float depending on whether exp is non-negative
+    def pow(base: int, exp: int, mod: Literal[0]) -> NoReturn: ...
+    # int base & positive-int exp -> int; int base & negative-int exp -> float
+    # return type must be Any as `int | float` causes too many false-positive errors
+    @overload
+    def pow(base: int, exp: int, mod: None = ...) -> Any: ...
     @overload
     def pow(base: int, exp: int, mod: int) -> int: ...
     @overload
-    def pow(base: float, exp: float, mod: None = ...) -> float: ...
+    def pow(base: float, exp: int, mod: None = ...) -> float: ...
+    # float base & float exp could return float or complex
+    # return type must be Any as `float | complex` causes too many false-positive errors
+    @overload
+    def pow(base: float, exp: float, mod: None = ...) -> Any: ...
     @overload
     def pow(base: _SupportsPow2[_E, _T_co], exp: _E) -> _T_co: ...
     @overload
     def pow(base: _SupportsPow3[_E, _M, _T_co], exp: _E, mod: _M) -> _T_co: ...
 
 else:
     @overload
-    def pow(
-        __base: int, __exp: int, __mod: None = ...
-    ) -> Any: ...  # returns int or float depending on whether exp is non-negative
+    def pow(__base: int, __exp: int, __mod: Literal[0]) -> NoReturn: ...
+    @overload
+    def pow(__base: int, __exp: int, __mod: None = ...) -> Any: ...
     @overload
     def pow(__base: int, __exp: int, __mod: int) -> int: ...
     @overload
-    def pow(__base: float, __exp: float, __mod: None = ...) -> float: ...
+    def pow(__base: float, __exp: int, __mod: None = ...) -> float: ...
+    @overload
+    def pow(__base: float, __exp: float, __mod: None = ...) -> Any: ...
     @overload
     def pow(__base: _SupportsPow2[_E, _T_co], __exp: _E) -> _T_co: ...
     @overload