feat(arithmetic): ✖️ multiplication (#1397)

* feat(arithmetic): multiplication

* feat: mul for timedelta indexes

* doc and refactor

* complex

* bool

* chore(poetry): update pyright

* fix(comment): #1397 (comment)

* fix(comment): #1397 (review)

* chore(pyrefly): remove-unused-ignores

* chore(comment): #1397 (comment)

* fix(comment): #1397 (comment)

* fix(nightly): pytest

* chore: naming

* fix(comment): pandas-dev/pandas#62595 #1397 (comment)

* fix: mypy

Author: cmp0xff

pandas-stubs/_libs/tslibs/period.pyi

@@ -13,6 +13,7 @@ from pandas import (
     Timedelta,
     TimedeltaIndex,
 )
+from typing_extensions import Self
 
 from pandas._libs.tslibs import NaTType
 from pandas._libs.tslibs.offsets import BaseOffset
@@ -87,15 +88,23 @@ class Period(PeriodMixin):
     @overload
     def __sub__(self, other: TimedeltaIndex) -> PeriodIndex: ...
     @overload
-    def __add__(self, other: _PeriodAddSub) -> Period: ...
+    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]
     @overload
-    def __add__(
-        self, other: Series[BaseOffset] | Series[Timedelta]
-    ) -> Series[Period]: ...  # pyrefly: ignore[bad-specialization]
+    def __radd__(self, other: _PeriodAddSub) -> Self: ...  # type: ignore[misc]
+    @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
@@ -168,18 +177,6 @@ class Period(PeriodMixin):
     def __ne__(self, other: np_ndarray[ShapeT, np.object_]) -> np_ndarray[ShapeT, np.bool]: ...  # type: ignore[overload-overlap]
     @overload
     def __ne__(self, other: object) -> Literal[True]: ...
-    # Ignored due to indecipherable error from mypy:
-    # Forward operator "__add__" is not callable  [misc]
-    @overload
-    def __radd__(self, other: _PeriodAddSub) -> Period: ...  # type: ignore[misc]
-    # 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) -> Index: ...
-    @overload
-    def __radd__(self, other: NaTType) -> NaTType: ...
     @property
     def day(self) -> int: ...
     @property

pandas-stubs/_libs/tslibs/timedeltas.pyi

@@ -1,6 +1,9 @@
 # pyright: strict
-import datetime as dt
-from datetime import timedelta
+from datetime import (
+    date,
+    datetime,
+    timedelta,
+)
 from typing import (
     ClassVar,
     Literal,
@@ -133,17 +136,17 @@ class Timedelta(timedelta):
     def ceil(self, freq: str | BaseOffset) -> Self: ...
     @property
     def resolution_string(self) -> str: ...
-    # Override due to more types supported than dt.timedelta
+    # Override due to more types supported than timedelta
     @overload  # type: ignore[override]
-    def __add__(self, other: dt.datetime | np.datetime64) -> Timestamp: ...
+    def __add__(self, other: datetime | np.datetime64) -> Timestamp: ...
     @overload
     def __add__(self, other: timedelta | np.timedelta64) -> Self: ...
     @overload
     def __add__(self, other: NaTType) -> NaTType: ...
     @overload
     def __add__(self, other: Period) -> Period: ...
     @overload
-    def __add__(self, other: dt.date) -> dt.date: ...
+    def __add__(self, other: date) -> date: ...
     @overload
     def __add__(
         self, other: np_ndarray[ShapeT, np.timedelta64]
@@ -153,13 +156,13 @@ class Timedelta(timedelta):
         self, other: np_ndarray[ShapeT, np.datetime64]
     ) -> np_ndarray[ShapeT, np.datetime64]: ...
     @overload
-    def __radd__(self, other: dt.datetime | np.datetime64) -> Timestamp: ...  # type: ignore[misc]
+    def __radd__(self, other: datetime | np.datetime64) -> Timestamp: ...  # type: ignore[misc]
     @overload
     def __radd__(self, other: timedelta | np.timedelta64) -> Self: ...
     @overload
     def __radd__(self, other: NaTType) -> NaTType: ...
     @overload
-    def __radd__(self, other: dt.date) -> dt.date: ...
+    def __radd__(self, other: date) -> date: ...
     @overload
     def __radd__(
         self, other: np_ndarray[ShapeT, np.timedelta64]
@@ -168,9 +171,9 @@ class Timedelta(timedelta):
     def __radd__(
         self, other: np_ndarray[ShapeT, np.datetime64]
     ) -> np_ndarray[ShapeT, np.datetime64]: ...
-    # Override due to more types supported than dt.timedelta
+    # Override due to more types supported than timedelta
     @overload  # type: ignore[override]
-    def __sub__(self, other: timedelta | Timedelta | np.timedelta64) -> Timedelta: ...
+    def __sub__(self, other: timedelta | Timedelta | np.timedelta64) -> Self: ...
     @overload
     def __sub__(self, other: NaTType) -> NaTType: ...
     @overload
@@ -180,11 +183,9 @@ class Timedelta(timedelta):
     @overload
     def __sub__(self, other: pd.TimedeltaIndex) -> TimedeltaIndex: ...
     @overload
-    def __sub__(self, other: Series[pd.Timedelta]) -> Series[pd.Timedelta]: ...
-    @overload
-    def __rsub__(self, other: timedelta | Timedelta | np.timedelta64) -> Timedelta: ...
+    def __rsub__(self, other: timedelta | Timedelta | np.timedelta64) -> Self: ...
     @overload
-    def __rsub__(self, other: dt.datetime | Timestamp | np.datetime64) -> Timestamp: ...  # type: ignore[misc]
+    def __rsub__(self, other: datetime | Timestamp | np.datetime64) -> Timestamp: ...  # type: ignore[misc]
     @overload
     def __rsub__(self, other: NaTType) -> NaTType: ...
     @overload
@@ -203,44 +204,31 @@ class Timedelta(timedelta):
     ) -> np_ndarray[ShapeT, np.timedelta64]: ...
     @overload
     def __rsub__(self, other: pd.TimedeltaIndex) -> pd.TimedeltaIndex: ...
-    def __neg__(self) -> Timedelta: ...
-    def __pos__(self) -> Timedelta: ...
-    def __abs__(self) -> Timedelta: ...
-    # Override due to more types supported than dt.timedelta
+    def __neg__(self) -> Self: ...
+    def __pos__(self) -> Self: ...
+    def __abs__(self) -> Self: ...
+    # Override due to more types supported than timedelta
     @overload  # type: ignore[override]
-    def __mul__(self, other: float) -> Timedelta: ...
+    def __mul__(self, other: float) -> Self: ...
     @overload
     def __mul__(
-        self, other: np_ndarray[ShapeT, np.integer] | np_ndarray[ShapeT, np.floating]
+        self, other: np_ndarray[ShapeT, np.bool_ | np.integer | np.floating]
     ) -> np_ndarray[ShapeT, np.timedelta64]: ...
     @overload
-    def __mul__(self, other: Series[int]) -> Series[Timedelta]: ...
-    @overload
-    def __mul__(self, other: Series[float]) -> Series[Timedelta]: ...
-    @overload
-    def __mul__(self, other: Index[int] | Index[float]) -> TimedeltaIndex: ...
-    @overload
-    def __rmul__(self, other: float) -> Timedelta: ...
+    def __rmul__(self, other: float) -> Self: ...
     @overload
     def __rmul__(
-        self, other: np_ndarray[ShapeT, np.floating] | np_ndarray[ShapeT, np.integer]
+        self, other: np_ndarray[ShapeT, np.bool_ | np.integer | np.floating]
     ) -> np_ndarray[ShapeT, np.timedelta64]: ...
-    @overload
-    def __rmul__(self, other: Series[int]) -> Series[Timedelta]: ...
-    @overload
-    def __rmul__(self, other: Series[float]) -> Series[Timedelta]: ...
-    # maybe related to https://github.com/python/mypy/issues/10755
-    @overload
-    def __rmul__(self, other: Index[int] | Index[float]) -> TimedeltaIndex: ...
-    # Override due to more types supported than dt.timedelta
+    # Override due to more types supported than timedelta
     # error: Signature of "__floordiv__" incompatible with supertype "timedelta"
     @overload  # type: ignore[override]
     def __floordiv__(self, other: timedelta | Timedelta | np.timedelta64) -> int: ...
     @overload
-    def __floordiv__(self, other: float) -> Timedelta: ...
+    def __floordiv__(self, other: float) -> Self: ...
     @overload
     def __floordiv__(
-        self, other: np_ndarray[ShapeT, np.integer] | np_ndarray[ShapeT, np.floating]
+        self, other: np_ndarray[ShapeT, np.integer | np.floating]
     ) -> np_ndarray[ShapeT, np.timedelta64]: ...
     @overload
     def __floordiv__(
@@ -264,14 +252,14 @@ class Timedelta(timedelta):
     def __rfloordiv__(
         self, other: np_ndarray[ShapeT, np.timedelta64]
     ) -> np_ndarray[ShapeT, np.int_]: ...
-    # Override due to more types supported than dt.timedelta
+    # Override due to more types supported than timedelta
     @overload  # type: ignore[override]
     def __truediv__(self, other: timedelta | Timedelta | NaTType) -> float: ...
     @overload
-    def __truediv__(self, other: float) -> Timedelta: ...
+    def __truediv__(self, other: float) -> Self: ...
     @overload
     def __truediv__(
-        self, other: np_ndarray[ShapeT, np.integer] | np_ndarray[ShapeT, np.floating]
+        self, other: np_ndarray[ShapeT, np.integer | np.floating]
     ) -> np_ndarray[ShapeT, np.timedelta64]: ...
     @overload
     def __truediv__(self, other: Series[Timedelta]) -> Series[float]: ...
@@ -282,7 +270,7 @@ class Timedelta(timedelta):
     @overload
     def __truediv__(self, other: Index[int] | Index[float]) -> TimedeltaIndex: ...
     def __rtruediv__(self, other: timedelta | Timedelta | NaTType) -> float: ...
-    # Override due to more types supported than dt.timedelta
+    # Override due to more types supported than timedelta
     @overload
     def __eq__(self, other: timedelta | Timedelta | np.timedelta64) -> bool: ...  # type: ignore[overload-overlap] # pyright: ignore[reportOverlappingOverload]
     @overload
@@ -295,7 +283,7 @@ class Timedelta(timedelta):
     ) -> np_ndarray[ShapeT, np.bool_]: ...
     @overload
     def __eq__(self, other: object) -> Literal[False]: ...
-    # Override due to more types supported than dt.timedelta
+    # Override due to more types supported than timedelta
     @overload
     def __ne__(self, other: timedelta | Timedelta | np.timedelta64) -> bool: ...  # type: ignore[overload-overlap] # pyright: ignore[reportOverlappingOverload]
     @overload
@@ -308,18 +296,18 @@ class Timedelta(timedelta):
     ) -> np_ndarray[ShapeT, np.bool_]: ...
     @overload
     def __ne__(self, other: object) -> Literal[True]: ...
-    # Override due to more types supported than dt.timedelta
+    # Override due to more types supported than timedelta
     @overload  # type: ignore[override]
-    def __mod__(self, other: timedelta) -> Timedelta: ...
+    def __mod__(self, other: timedelta) -> Self: ...
     @overload
-    def __mod__(self, other: float) -> Timedelta: ...
+    def __mod__(self, other: float) -> Self: ...
     @overload
     def __mod__(self, other: Series[int] | Series[float]) -> Series[Timedelta]: ...
     @overload
     def __mod__(self, other: Index[int] | Index[float]) -> TimedeltaIndex: ...
     @overload
     def __mod__(
-        self, other: np_ndarray[ShapeT, np.integer] | np_ndarray[ShapeT, np.floating]
+        self, other: np_ndarray[ShapeT, np.integer | np.floating]
     ) -> np_ndarray[ShapeT, np.timedelta64]: ...
     @overload
     def __mod__(
@@ -328,7 +316,7 @@ class Timedelta(timedelta):
     def __divmod__(self, other: timedelta) -> tuple[int, Timedelta]: ...
     # Mypy complains Forward operator "<inequality op>" is not callable, so ignore misc
     # for le, lt ge and gt
-    # Override due to more types supported than dt.timedelta
+    # Override due to more types supported than timedelta
     @overload  # type: ignore[override]
     def __le__(self, other: timedelta | Timedelta | np.timedelta64) -> bool: ...  # type: ignore[misc]
     @overload
@@ -339,7 +327,7 @@ class Timedelta(timedelta):
     ) -> np_ndarray[ShapeT, np.bool_]: ...
     @overload
     def __le__(self, other: Series[pd.Timedelta]) -> Series[bool]: ...
-    # Override due to more types supported than dt.timedelta
+    # Override due to more types supported than timedelta
     @overload  # type: ignore[override]
     def __lt__(self, other: timedelta | Timedelta | np.timedelta64) -> bool: ...  # type: ignore[misc]
     @overload
@@ -350,7 +338,7 @@ class Timedelta(timedelta):
     ) -> np_ndarray[ShapeT, np.bool_]: ...
     @overload
     def __lt__(self, other: Series[pd.Timedelta]) -> Series[bool]: ...
-    # Override due to more types supported than dt.timedelta
+    # Override due to more types supported than timedelta
     @overload  # type: ignore[override]
     def __ge__(self, other: timedelta | Timedelta | np.timedelta64) -> bool: ...  # type: ignore[misc]
     @overload
@@ -361,7 +349,7 @@ class Timedelta(timedelta):
     ) -> np_ndarray[ShapeT, np.bool_]: ...
     @overload
     def __ge__(self, other: Series[pd.Timedelta]) -> Series[bool]: ...
-    # Override due to more types supported than dt.timedelta
+    # Override due to more types supported than timedelta
     @overload  # type: ignore[override]
     def __gt__(self, other: timedelta | Timedelta | np.timedelta64) -> bool: ...  # type: ignore[misc]
     @overload

pandas-stubs/_typing.pyi

@@ -173,7 +173,8 @@ RandomState: TypeAlias = (
 )
 
 # dtypes
-NpDtype: TypeAlias = str | np.dtype[np.generic] | type[str | complex | bool | object]
+NpDtypeNoStr: TypeAlias = np.dtype[np.generic] | type[complex | bool | object]
+NpDtype: TypeAlias = str | NpDtypeNoStr | type[str]
 Dtype: TypeAlias = ExtensionDtype | NpDtype
 
 # AstypeArg is more carefully defined here as compared to pandas
@@ -847,19 +848,21 @@ MaskType: TypeAlias = Series[bool] | np_ndarray_bool | list[bool]
 
 T_INT = TypeVar("T_INT", bound=int)
 T_COMPLEX = TypeVar("T_COMPLEX", bound=complex)
-SeriesDTypeNoDateTime: TypeAlias = (
-    str
-    | bytes
+SeriesDTypeNoStrDateTime: TypeAlias = (
+    bytes
     | bool
     | int
     | float
     | complex
-    | Dtype
+    | NpDtypeNoStr
+    | ExtensionDtype
     | Period
     | Interval
     | CategoricalDtype
     | BaseOffset
-    | list[str]
+)
+SeriesDTypeNoDateTime: TypeAlias = (
+    str | SeriesDTypeNoStrDateTime | type[str] | list[str]
 )
 SeriesDType: TypeAlias = (
     SeriesDTypeNoDateTime
@@ -869,6 +872,9 @@ SeriesDType: TypeAlias = (
     | datetime.timedelta  # includes pd.Timedelta
 )
 S1 = TypeVar("S1", bound=SeriesDType, default=Any)
+S1_CO_NSDT = TypeVar(
+    "S1_CO_NSDT", bound=SeriesDTypeNoStrDateTime, default=Any, covariant=True
+)
 S1_CT_NDT = TypeVar(
     "S1_CT_NDT", bound=SeriesDTypeNoDateTime, default=Any, contravariant=True
 )

pandas-stubs/core/arrays/datetimelike.pyi

@@ -60,7 +60,7 @@ class DatetimeLikeArrayMixin(ExtensionOpsMixin, ExtensionArray):
     @property
     def shape(self): ...
     def reshape(self, *args: Any, **kwargs: Any): ...
-    def ravel(self, *args: Any, **kwargs: Any): ...  # pyrefly: ignore
+    def ravel(self, *args: Any, **kwargs: Any): ...
     def __iter__(self): ...
     @property
     def asi8(self) -> np.ndarray: ...
@@ -85,7 +85,7 @@ class DatetimeLikeArrayMixin(ExtensionOpsMixin, ExtensionArray):
     def unique(self): ...
     def copy(self): ...
     def shift(self, periods: int = 1, fill_value=..., axis: int = ...): ...
-    def repeat(self, repeats, *args: Any, **kwargs: Any): ...  # pyrefly: ignore
+    def repeat(self, repeats, *args: Any, **kwargs: Any): ...
     def value_counts(self, dropna: bool = True): ...
     def map(self, mapper): ...
     def isna(self): ...

pandas-stubs/core/frame.pyi

@@ -60,9 +60,7 @@ from pandas.core.reshape.pivot import (
     _PivotTableIndexTypes,
     _PivotTableValuesTypes,
 )
-from pandas.core.series import (
-    Series,
-)
+from pandas.core.series import Series
 from pandas.core.window import (
     Expanding,
     ExponentialMovingWindow,

pandas-stubs/core/generic.pyi

@@ -24,9 +24,7 @@ import numpy as np
 from pandas import Index
 import pandas.core.indexing as indexing
 from pandas.core.resample import DatetimeIndexResampler
-from pandas.core.series import (
-    Series,
-)
+from pandas.core.series import Series
 import sqlalchemy.engine
 from typing_extensions import (
     Never,

pandas-stubs/core/groupby/generic.pyi

@@ -57,7 +57,7 @@ class NamedAgg(NamedTuple):
 
 class SeriesGroupBy(GroupBy[Series[S2]], Generic[S2, ByT]):
     @overload
-    def aggregate(  # pyrefly: ignore
+    def aggregate(
         self,
         func: Callable[Concatenate[Series[S2], P], S3],
         /,

pandas-stubs/core/groupby/groupby.pyi

@@ -20,9 +20,7 @@ from typing import (
 import numpy as np
 from pandas.core.base import SelectionMixin
 from pandas.core.frame import DataFrame
-from pandas.core.groupby import (
-    generic,
-)
+from pandas.core.groupby import generic
 from pandas.core.groupby.indexing import (
     GroupByIndexingMixin,
     GroupByNthSelector,