For time related series, allow lists to define type, and fix mean, median, std (pandas-dev#493)

* split Series[IntervalT] into separate __new__

* allow sequences to define TimestampSeries, TimedeltaSeries, fix mean, median, std for time related series

* revert changes related to Series.__new__ and IntervalT

Author: Dr-Irv

pandas-stubs/core/series.pyi

@@ -10,6 +10,7 @@ from datetime import (
     date,
     datetime,
     time,
+    timedelta,
 )
 from typing import (
     Any,
@@ -186,7 +187,7 @@ class Series(IndexOpsMixin, NDFrame, Generic[S1]):
     @overload
     def __new__(
         cls,
-        data: DatetimeIndex,
+        data: DatetimeIndex | Sequence[Timestamp | np.datetime64 | datetime],
         index: Axes | None = ...,
         dtype=...,
         name: Hashable | None = ...,
@@ -206,7 +207,7 @@ class Series(IndexOpsMixin, NDFrame, Generic[S1]):
     @overload
     def __new__(
         cls,
-        data: TimedeltaIndex,
+        data: TimedeltaIndex | Sequence[Timedelta | np.timedelta64 | timedelta],
         index: Axes | None = ...,
         dtype=...,
         name: Hashable | None = ...,
@@ -1261,8 +1262,12 @@ class Series(IndexOpsMixin, NDFrame, Generic[S1]):
     def __div__(self, other: num | _ListLike | Series[S1]) -> Series[S1]: ...
     def __eq__(self, other: object) -> Series[_bool]: ...  # type: ignore[override]
     def __floordiv__(self, other: num | _ListLike | Series[S1]) -> Series[int]: ...
-    def __ge__(self, other: S1 | _ListLike | Series[S1]) -> Series[_bool]: ...
-    def __gt__(self, other: S1 | _ListLike | Series[S1]) -> Series[_bool]: ...
+    def __ge__(
+        self, other: S1 | _ListLike | Series[S1] | datetime | timedelta
+    ) -> Series[_bool]: ...
+    def __gt__(
+        self, other: S1 | _ListLike | Series[S1] | datetime | timedelta
+    ) -> Series[_bool]: ...
     # def __iadd__(self, other: S1) -> Series[S1]: ...
     # def __iand__(self, other: S1) -> Series[_bool]: ...
     # def __idiv__(self, other: S1) -> Series[S1]: ...
@@ -1275,8 +1280,12 @@ class Series(IndexOpsMixin, NDFrame, Generic[S1]):
     # def __itruediv__(self, other: S1) -> Series[S1]: ...
     # def __itruediv__(self, other) -> None: ...
     # def __ixor__(self, other: S1) -> Series[_bool]: ...
-    def __le__(self, other: S1 | _ListLike | Series[S1]) -> Series[_bool]: ...
-    def __lt__(self, other: S1 | _ListLike | Series[S1]) -> Series[_bool]: ...
+    def __le__(
+        self, other: S1 | _ListLike | Series[S1] | datetime | timedelta
+    ) -> Series[_bool]: ...
+    def __lt__(
+        self, other: S1 | _ListLike | Series[S1] | datetime | timedelta
+    ) -> Series[_bool]: ...
     @overload
     def __mul__(
         self, other: Timedelta | TimedeltaSeries | np.timedelta64
@@ -1777,6 +1786,31 @@ class TimestampSeries(Series[Timestamp]):
     def __add__(self, other: TimedeltaSeries | np.timedelta64) -> TimestampSeries: ...  # type: ignore[override]
     def __mul__(self, other: TimestampSeries | np.timedelta64 | TimedeltaSeries) -> Never: ...  # type: ignore[override]
     def __truediv__(self, other: TimestampSeries | np.timedelta64 | TimedeltaSeries) -> Never: ...  # type: ignore[override]
+    def mean(  # type: ignore[override]
+        self,
+        axis: SeriesAxisType | None = ...,
+        skipna: _bool = ...,
+        level: None = ...,
+        numeric_only: _bool = ...,
+        **kwargs,
+    ) -> Timestamp: ...
+    def median(  # type: ignore[override]
+        self,
+        axis: SeriesAxisType | None = ...,
+        skipna: _bool = ...,
+        level: None = ...,
+        numeric_only: _bool = ...,
+        **kwargs,
+    ) -> Timestamp: ...
+    def std(  # type: ignore[override]
+        self,
+        axis: SeriesAxisType | None = ...,
+        skipna: _bool | None = ...,
+        level: None = ...,
+        ddof: int = ...,
+        numeric_only: _bool = ...,
+        **kwargs,
+    ) -> Timedelta: ...
 
 class TimedeltaSeries(Series[Timedelta]):
     # ignores needed because of mypy
@@ -1801,6 +1835,31 @@ class TimedeltaSeries(Series[Timedelta]):
     def __truediv__(self, other: Timedelta | TimedeltaSeries | np.timedelta64 | TimedeltaIndex) -> Series[float]: ...  # type: ignore[override]
     @property
     def dt(self) -> TimedeltaProperties: ...  # type: ignore[override]
+    def mean(  # type: ignore[override]
+        self,
+        axis: SeriesAxisType | None = ...,
+        skipna: _bool = ...,
+        level: None = ...,
+        numeric_only: _bool = ...,
+        **kwargs,
+    ) -> Timedelta: ...
+    def median(  # type: ignore[override]
+        self,
+        axis: SeriesAxisType | None = ...,
+        skipna: _bool = ...,
+        level: None = ...,
+        numeric_only: _bool = ...,
+        **kwargs,
+    ) -> Timedelta: ...
+    def std(  # type: ignore[override]
+        self,
+        axis: SeriesAxisType | None = ...,
+        skipna: _bool | None = ...,
+        level: None = ...,
+        ddof: int = ...,
+        numeric_only: _bool = ...,
+        **kwargs,
+    ) -> Timedelta: ...
 
 class PeriodSeries(Series[Period]):
     # ignore needed because of mypy

tests/test_timefuncs.py

@@ -1067,3 +1067,21 @@ def test_timedeltaseries_add_timestampseries() -> None:
     tss = pd.Series(pd.date_range(start="2012-01-01", periods=10, freq="W-MON"))
     plus = tds + tss
     check(assert_type(plus, "TimestampSeries"), pd.Series, pd.Timestamp)
+
+
+def test_mean_median_std() -> None:
+    s = pd.Series([pd.Timedelta("1 ns"), pd.Timedelta("2 ns"), pd.Timedelta("3 ns")])
+    check(assert_type(s.mean(), pd.Timedelta), pd.Timedelta)
+    check(assert_type(s.median(), pd.Timedelta), pd.Timedelta)
+    check(assert_type(s.std(), pd.Timedelta), pd.Timedelta)
+
+    s2 = pd.Series(
+        [
+            pd.Timestamp("2021-01-01"),
+            pd.Timestamp("2021-01-02"),
+            pd.Timestamp("2021-01-03"),
+        ]
+    )
+    check(assert_type(s2.mean(), pd.Timestamp), pd.Timestamp)
+    check(assert_type(s2.median(), pd.Timestamp), pd.Timestamp)
+    check(assert_type(s2.std(), pd.Timedelta), pd.Timedelta)