feat(arithmetic): #1347 #1378 ➗ truediv (#1431)

* refactor: truediv

* feat: truediv for index[bool]

* TimedeltaIndex

* TimedeltaIndex

* feat: truediv, also pandas-dev/pandas#62712

* Index[Any]

* Index[complex]

* mypy fails

* mypy unhappy

* mypy happiness

* mypy happiness

* pyright unhappy

* propagate pandas-dev/pandas#62229

* comments

* remove Index[Timedelta] and be independent of pandas-dev/pandas#62524

Author: cmp0xff

pandas-stubs/_libs/tslibs/period.pyi

@@ -91,8 +91,6 @@ class Period(PeriodMixin):
     def __add__(self, other: _PeriodAddSub) -> Self: ...
     @overload
     def __add__(self, other: NaTType) -> NaTType: ...
-    @overload
-    def __add__(self, other: Index) -> PeriodIndex: ...
     # Ignored due to indecipherable error from mypy:
     # Forward operator "__add__" is not callable  [misc]
     if sys.version_info >= (3, 11):
@@ -104,12 +102,6 @@ class Period(PeriodMixin):
 
     @overload
     def __radd__(self, other: NaTType) -> NaTType: ...
-    # Real signature is -> PeriodIndex, but conflicts with Index.__add__
-    # Changing Index is very hard due to Index inheritance
-    #   Signatures of "__radd__" of "Period" and "__add__" of "Index"
-    #   are unsafely overlapping
-    @overload
-    def __radd__(self, other: Index) -> PeriodIndex: ...
     #  ignore[misc] here because we know all other comparisons
     #  are False, so we use Literal[False]
     @overload

pandas-stubs/_libs/tslibs/timedeltas.pyi

@@ -13,6 +13,7 @@ from typing import (
 )
 
 import numpy as np
+from numpy import typing as npt
 from pandas.core.indexes.base import Index
 from pandas.core.indexes.datetimes import DatetimeIndex
 from pandas.core.indexes.period import PeriodIndex
@@ -30,7 +31,6 @@ from pandas._typing import (
     TimeUnit,
     np_1darray,
     np_ndarray,
-    npt,
 )
 
 class Components(NamedTuple):
@@ -250,22 +250,24 @@ class Timedelta(timedelta):
     ) -> np_ndarray[ShapeT, np.int_]: ...
     # Override due to more types supported than timedelta
     @overload  # type: ignore[override]
-    def __truediv__(self, other: timedelta | Timedelta | NaTType) -> float: ...
+    # pyrefly: ignore[bad-override]
+    def __truediv__(self, other: Just[int] | Just[float]) -> Self: ...
     @overload
-    def __truediv__(self, other: float) -> Self: ...
+    def __truediv__(self, other: Self | NaTType) -> float: ...
     @overload
     def __truediv__(
         self, other: np_ndarray[ShapeT, np.integer | np.floating]
     ) -> np_ndarray[ShapeT, np.timedelta64]: ...
     @overload
-    def __truediv__(self, other: Series[Timedelta]) -> Series[float]: ...
-    @overload
-    def __truediv__(self, other: Series[int]) -> Series[Timedelta]: ...
+    def __truediv__(
+        self, other: np_ndarray[ShapeT, np.timedelta64]
+    ) -> np_ndarray[ShapeT, np.floating]: ...
     @overload
-    def __truediv__(self, other: Series[float]) -> Series[Timedelta]: ...
+    def __rtruediv__(self, other: Self | NaTType) -> float: ...
     @overload
-    def __truediv__(self, other: Index[int] | Index[float]) -> TimedeltaIndex: ...
-    def __rtruediv__(self, other: timedelta | Timedelta | NaTType) -> float: ...
+    def __rtruediv__(
+        self, other: np_ndarray[ShapeT, np.timedelta64]
+    ) -> np_ndarray[ShapeT, np.floating]: ...
     # Override due to more types supported than timedelta
     @overload
     def __eq__(self, other: timedelta | np.timedelta64 | Self) -> bool: ...  # type: ignore[overload-overlap] # pyright: ignore[reportOverlappingOverload]

pandas-stubs/_libs/tslibs/timestamps.pyi

@@ -18,11 +18,9 @@ from typing import (
 )
 
 import numpy as np
-from pandas import (
-    DatetimeIndex,
-    TimedeltaIndex,
-)
 from pandas.core.indexes.base import Index
+from pandas.core.indexes.datetimes import DatetimeIndex
+from pandas.core.indexes.timedeltas import TimedeltaIndex
 from pandas.core.series import Series
 from typing_extensions import (
     Never,
@@ -99,10 +97,9 @@ class Timestamp(datetime, SupportsIndex):
     def tz(self) -> _tzinfo | None: ...
     @property
     def fold(self) -> int: ...
-
     if sys.version_info >= (3, 12):
         @classmethod
-        def fromtimestamp(  # pyright: ignore[reportIncompatibleMethodOverride]  # pyrefly: ignore
+        def fromtimestamp(  # pyright: ignore[reportIncompatibleMethodOverride]
             cls, t: float, tz: _tzinfo | str | None = ...
         ) -> Self: ...
     else:

pandas-stubs/_typing.pyi

@@ -25,6 +25,7 @@ from typing import (
     overload,
 )
 
+from _typeshed import _T_contra
 import numpy as np
 from numpy import typing as npt
 import pandas as pd
@@ -860,6 +861,9 @@ np_ndarray_td: TypeAlias = npt.NDArray[np.timedelta64]
 # Define shape and generic type variables with defaults similar to numpy
 GenericT = TypeVar("GenericT", bound=np.generic, default=Any)
 GenericT_co = TypeVar("GenericT_co", bound=np.generic, default=Any, covariant=True)
+GenericT_contra = TypeVar(
+    "GenericT_contra", bound=np.generic, default=Any, contravariant=True
+)
 ShapeT = TypeVar("ShapeT", bound=tuple[int, ...], default=tuple[Any, ...])
 # Numpy ndarray with more ergonomic typevar
 np_ndarray: TypeAlias = np.ndarray[ShapeT, np.dtype[GenericT]]
@@ -1114,4 +1118,10 @@ class Just(Protocol, Generic[T]):
     @override
     def __class__(self, t: type[T], /) -> None: ...
 
+class SupportsTrueDiv(Protocol[_T_contra, _T_co]):
+    def __truediv__(self, x: _T_contra, /) -> _T_co: ...
+
+class SupportsRTrueDiv(Protocol[_T_contra, _T_co]):
+    def __rtruediv__(self, x: _T_contra, /) -> _T_co: ...
+
 __all__ = ["npt", "type_t"]

pandas-stubs/core/base.pyi

@@ -3,6 +3,7 @@ from collections.abc import (
     Iterator,
     Sequence,
 )
+from datetime import timedelta
 from typing import (
     Any,
     Generic,
@@ -175,7 +176,6 @@ NumListLike: TypeAlias = (
     | np_ndarray_complex
     | dict[str, np.ndarray]
     | Sequence[complex]
-    | IndexOpsMixin[complex]
 )
 
 @type_check_only
@@ -266,6 +266,38 @@ class ElementOpsMixin(Generic[S2]):
     def _proto_rmul(
         self: ElementOpsMixin[str], other: Just[int] | np.integer
     ) -> ElementOpsMixin[str]: ...
+    @overload
+    def _proto_truediv(
+        self: ElementOpsMixin[int], other: int | np.integer
+    ) -> ElementOpsMixin[float]: ...
+    @overload
+    def _proto_truediv(
+        self: ElementOpsMixin[float], other: float | np.floating
+    ) -> ElementOpsMixin[float]: ...
+    @overload
+    def _proto_truediv(
+        self: ElementOpsMixin[complex], other: complex | np.complexfloating
+    ) -> ElementOpsMixin[complex]: ...
+    @overload
+    def _proto_truediv(
+        self: ElementOpsMixin[Timedelta], other: timedelta | Timedelta | np.timedelta64
+    ) -> ElementOpsMixin[float]: ...
+    @overload
+    def _proto_rtruediv(
+        self: ElementOpsMixin[int], other: int | np.integer
+    ) -> ElementOpsMixin[float]: ...
+    @overload
+    def _proto_rtruediv(
+        self: ElementOpsMixin[float], other: float | np.floating
+    ) -> ElementOpsMixin[float]: ...
+    @overload
+    def _proto_rtruediv(
+        self: ElementOpsMixin[complex], other: complex | np.complexfloating
+    ) -> ElementOpsMixin[complex]: ...
+    @overload
+    def _proto_rtruediv(
+        self: ElementOpsMixin[Timedelta], other: timedelta | Timedelta | np.timedelta64
+    ) -> ElementOpsMixin[float]: ...
 
 @type_check_only
 class Supports_ProtoAdd(Protocol[_T_contra, S2]):
@@ -282,3 +314,11 @@ class Supports_ProtoMul(Protocol[_T_contra, S2]):
 @type_check_only
 class Supports_ProtoRMul(Protocol[_T_contra, S2]):
     def _proto_rmul(self, other: _T_contra, /) -> ElementOpsMixin[S2]: ...
+
+@type_check_only
+class Supports_ProtoTrueDiv(Protocol[_T_contra, S2]):
+    def _proto_truediv(self, other: _T_contra, /) -> ElementOpsMixin[S2]: ...
+
+@type_check_only
+class Supports_ProtoRTrueDiv(Protocol[_T_contra, S2]):
+    def _proto_rtruediv(self, other: _T_contra, /) -> ElementOpsMixin[S2]: ...