feat(index): ➕ arithmetic addition

pandas-stubs/_typing.pyi

@@ -845,6 +845,8 @@ MaskType: TypeAlias = Series[bool] | np_ndarray_bool | list[bool]
 
 # Scratch types for generics
 
+T_INT = TypeVar("T_INT", bound=int)
+T_COMPLEX = TypeVar("T_COMPLEX", bound=complex)
 SeriesDType: TypeAlias = (
     str
     | bytes

pandas-stubs/core/arraylike.pyi

@@ -19,8 +19,6 @@ class OpsMixin:
     def __rxor__(self, other: Any) -> Self: ...
     # -------------------------------------------------------------
     # Arithmetic Methods
-    def __add__(self, other: Any) -> Self: ...
-    def __radd__(self, other: Any) -> Self: ...
     def __sub__(self, other: Any) -> Self: ...
     def __rsub__(self, other: Any) -> Self: ...
     def __mul__(self, other: Any) -> Self: ...

pandas-stubs/core/frame.pyi

@@ -1772,13 +1772,22 @@ class DataFrame(NDFrame, OpsMixin, _GetItemHack):
     # methods
     @final
     def abs(self) -> Self: ...
+    def __add__(self, other: Any) -> Self: ...
     def add(
         self,
         other: num | ListLike | DataFrame,
         axis: Axis | None = "columns",
         level: Level | None = None,
         fill_value: float | None = None,
     ) -> Self: ...
+    def __radd__(self, other: Any) -> Self: ...
+    def radd(
+        self,
+        other,
+        axis: Axis = "columns",
+        level: Level | None = None,
+        fill_value: float | None = None,
+    ) -> Self: ...
     @final
     def add_prefix(self, prefix: _str, axis: Axis | None = None) -> Self: ...
     @final
@@ -2222,13 +2231,6 @@ class DataFrame(NDFrame, OpsMixin, _GetItemHack):
         min_count: int = 0,
         **kwargs: Any,
     ) -> Series: ...
-    def radd(
-        self,
-        other,
-        axis: Axis = "columns",
-        level: Level | None = None,
-        fill_value: float | None = None,
-    ) -> Self: ...
     @final
     def rank(
         self,

pandas-stubs/core/indexes/base.pyi

@@ -39,12 +39,15 @@ from pandas.core.strings.accessor import StringMethods
 from typing_extensions import (
     Never,
     Self,
+    TypeAlias,
 )
 
 from pandas._libs.interval import _OrderableT
 from pandas._typing import (
     C2,
     S1,
+    T_COMPLEX,
+    T_INT,
     AnyAll,
     ArrayLike,
     AxesData,
@@ -70,18 +73,32 @@ from pandas._typing import (
     TimestampDtypeArg,
     np_1darray,
     np_ndarray_anyint,
+    np_ndarray_bool,
     np_ndarray_complex,
     np_ndarray_float,
+    np_ndarray_str,
     type_t,
 )
 
 class InvalidIndexError(Exception): ...
 
+_ListLike: TypeAlias = ArrayLike | dict[_str, np.ndarray] | SequenceNotStr[S1]
+
 class Index(IndexOpsMixin[S1]):
     __hash__: ClassVar[None]  # type: ignore[assignment]
     # overloads with additional dtypes
     @overload
     def __new__(  # pyright: ignore[reportOverlappingOverload]
+        cls,
+        data: Sequence[bool | np.bool_] | IndexOpsMixin[bool] | np_ndarray_bool,
+        *,
+        dtype: Literal["bool"] | type_t[bool | np.bool_] = ...,
+        copy: bool = ...,
+        name: Hashable = ...,
+        tupleize_cols: bool = ...,
+    ) -> Index[bool]: ...
+    @overload
+    def __new__(
         cls,
         data: Sequence[int | np.integer] | IndexOpsMixin[int] | np_ndarray_anyint,
         *,
@@ -460,6 +477,155 @@ class Index(IndexOpsMixin[S1]):
     def __gt__(self, other: Self | S1) -> np_1darray[np.bool]: ...  # type: ignore[override] # pyright: ignore[reportIncompatibleMethodOverride]
     # overwrite inherited methods from OpsMixin
     @overload
+    def __add__(self: Index[Never], other: _str) -> Never: ...
+    @overload
+    def __add__(self: Index[Never], other: complex | _ListLike | Index) -> Index: ...
+    @overload
+    def __add__(self, other: Index[Never]) -> Index: ...
+    @overload
+    def __add__(
+        self: Index[bool],
+        other: T_COMPLEX | Sequence[T_COMPLEX] | Index[T_COMPLEX],
+    ) -> Index[T_COMPLEX]: ...
+    @overload
+    def __add__(self: Index[bool], other: np_ndarray_bool) -> Index[bool]: ...
+    @overload
+    def __add__(self: Index[bool], other: np_ndarray_anyint) -> Index[int]: ...
+    @overload
+    def __add__(self: Index[bool], other: np_ndarray_float) -> Index[float]: ...
+    @overload
+    def __add__(self: Index[bool], other: np_ndarray_complex) -> Index[complex]: ...
+    @overload
+    def __add__(
+        self: Index[int],
+        other: (
+            bool | Sequence[bool] | np_ndarray_bool | np_ndarray_anyint | Index[bool]
+        ),
+    ) -> Index[int]: ...
+    @overload
+    def __add__(
+        self: Index[int],
+        other: T_COMPLEX | Sequence[T_COMPLEX] | Index[T_COMPLEX],
+    ) -> Index[T_COMPLEX]: ...
+    @overload
+    def __add__(self: Index[int], other: np_ndarray_float) -> Index[float]: ...
+    @overload
+    def __add__(self: Index[int], other: np_ndarray_complex) -> Index[complex]: ...
+    @overload
+    def __add__(
+        self: Index[float],
+        other: (
+            int
+            | Sequence[int]
+            | np_ndarray_bool
+            | np_ndarray_anyint
+            | np_ndarray_float
+            | Index[T_INT]
+        ),
+    ) -> Index[float]: ...
+    @overload
+    def __add__(
+        self: Index[float],
+        other: T_COMPLEX | Sequence[T_COMPLEX] | Index[T_COMPLEX],
+    ) -> Index[T_COMPLEX]: ...
+    @overload
+    def __add__(self: Index[float], other: np_ndarray_complex) -> Index[complex]: ...
+    @overload
+    def __add__(
+        self: Index[complex],
+        other: (
+            T_COMPLEX
+            | Sequence[T_COMPLEX]
+            | np_ndarray_bool
+            | np_ndarray_anyint
+            | np_ndarray_float
+            | np_ndarray_complex
+            | Index[T_COMPLEX]
+        ),
+    ) -> Index[complex]: ...
+    @overload
+    def __add__(
+        self: Index[_str],
+        other: (
+            np_ndarray_bool | np_ndarray_anyint | np_ndarray_float | np_ndarray_complex
+        ),
+    ) -> Never: ...
+    @overload
+    def __add__(
+        self: Index[_str], other: _str | Sequence[_str] | np_ndarray_str | Index[_str]
+    ) -> Index[_str]: ...
+    @overload
+    def __radd__(self: Index[Never], other: _str) -> Never: ...
+    @overload
+    def __radd__(self: Index[Never], other: complex | _ListLike | Index) -> Index: ...
+    @overload
+    def __radd__(
+        self: Index[bool],
+        other: T_COMPLEX | Sequence[T_COMPLEX] | Index[T_COMPLEX],
+    ) -> Index[T_COMPLEX]: ...
+    @overload
+    def __radd__(self: Index[bool], other: np_ndarray_bool) -> Index[bool]: ...
+    @overload
+    def __radd__(self: Index[bool], other: np_ndarray_anyint) -> Index[int]: ...
+    @overload
+    def __radd__(self: Index[bool], other: np_ndarray_float) -> Index[float]: ...
+    @overload
+    def __radd__(
+        self: Index[int],
+        other: (
+            bool | Sequence[bool] | np_ndarray_bool | np_ndarray_anyint | Index[bool]
+        ),
+    ) -> Index[int]: ...
+    @overload
+    def __radd__(
+        self: Index[int], other: T_COMPLEX | Sequence[T_COMPLEX] | Index[T_COMPLEX]
+    ) -> Index[T_COMPLEX]: ...
+    @overload
+    def __radd__(self: Index[int], other: np_ndarray_float) -> Index[float]: ...
+    @overload
+    def __radd__(
+        self: Index[float],
+        other: (
+            int
+            | Sequence[int]
+            | np_ndarray_bool
+            | np_ndarray_anyint
+            | np_ndarray_float
+            | Index[T_INT]
+        ),
+    ) -> Index[float]: ...
+    @overload
+    def __radd__(
+        self: Index[float], other: T_COMPLEX | Sequence[T_COMPLEX] | Index[T_COMPLEX]
+    ) -> Index[T_COMPLEX]: ...
+    @overload
+    def __radd__(
+        self: Index[complex],
+        other: (
+            T_COMPLEX
+            | Sequence[T_COMPLEX]
+            | np_ndarray_bool
+            | np_ndarray_anyint
+            | np_ndarray_float
+            | Index[T_COMPLEX]
+        ),
+    ) -> Index[complex]: ...
+    @overload
+    def __radd__(
+        self: Index[T_COMPLEX], other: np_ndarray_complex
+    ) -> Index[complex]: ...
+    @overload
+    def __radd__(
+        self: Index[_str],
+        other: (
+            np_ndarray_bool | np_ndarray_anyint | np_ndarray_float | np_ndarray_complex
+        ),
+    ) -> Never: ...
+    @overload
+    def __radd__(
+        self: Index[_str], other: _str | Sequence[_str] | np_ndarray_str | Index[_str]
+    ) -> Index[_str]: ...
+    @overload
     def __mul__(
         self: Index[int] | Index[float], other: timedelta
     ) -> TimedeltaIndex: ...

pandas-stubs/core/indexes/datetimes.pyi

@@ -61,10 +61,10 @@ class DatetimeIndex(
     def __reduce__(self): ...
     # various ignores needed for mypy, as we do want to restrict what can be used in
     # arithmetic for these types
-    @overload
+    @overload  # type: ignore[override]
     def __add__(self, other: TimedeltaSeries) -> TimestampSeries: ...
     @overload
-    def __add__(
+    def __add__(  # pyright: ignore[reportIncompatibleMethodOverride]
         self, other: timedelta | Timedelta | TimedeltaIndex | BaseOffset
     ) -> DatetimeIndex: ...
     @overload

pandas-stubs/core/indexes/timedeltas.pyi

@@ -49,12 +49,14 @@ class TimedeltaIndex(
     ) -> Self: ...
     # various ignores needed for mypy, as we do want to restrict what can be used in
     # arithmetic for these types
-    @overload
+    @overload  # type: ignore[override]
     def __add__(self, other: Period) -> PeriodIndex: ...
     @overload
     def __add__(self, other: DatetimeIndex) -> DatetimeIndex: ...
     @overload
-    def __add__(self, other: dt.timedelta | Timedelta | Self) -> Self: ...
+    def __add__(  # pyright: ignore[reportIncompatibleMethodOverride]
+        self, other: dt.timedelta | Timedelta | Self
+    ) -> Self: ...
     def __radd__(self, other: dt.datetime | Timestamp | DatetimeIndex) -> DatetimeIndex: ...  # type: ignore[override]
     def __sub__(self, other: dt.timedelta | Timedelta | Self) -> Self: ...
     def __mul__(self, other: num) -> Self: ...