TYP: Add variance checks to aggregation tests and type assertions (#1546)

* Add variance checks to aggregation tests and type assertions

- Updated aggregation tests in `test_agg.py` to include checks for the `var()` method across different data types (float, bool, int, and complex).
- Added a warning check for complex series when calculating variance to handle potential loss of imaginary parts.
- Enhanced type assertions in `test_series.py` for the `var()` method to ensure it returns a float type.

* Undo the tests/_typing.py change

* TYP: Fix Series.var() return type annotations:
- Fix `Series[complex].var()` return type from `np.float64` to `float`
- Add `Series[Timedelta].var()` overload returning `Never` (invalid operation)
- Add upper bound `upper="2.3.99"` for complex variance warning test
- Add Timedelta var() invalid usage test

* GH1546 PR Feedback

* Update tests/series/test_agg.py

Co-authored-by: Yi-Fan Wang <[email protected]>

* Fix type checking for series variance function

---------

Co-authored-by: Loïc Diridollou <[email protected]>
Co-authored-by: Yi-Fan Wang <[email protected]>

Author: 3 people

pandas-stubs/core/series.pyi

@@ -4636,14 +4636,42 @@ class Series(IndexOpsMixin[S1], ElementOpsMixin[S1], NDFrame):
         **kwargs: Any,
     ) -> np_1darray: ...
     def tolist(self) -> list[S1]: ...
+    @overload
     def var(
-        self,
+        self: Series[Never],
         axis: AxisIndex | None = 0,
         skipna: _bool | None = True,
         ddof: int = 1,
         numeric_only: _bool = False,
         **kwargs: Any,
-    ) -> Scalar: ...
+    ) -> float: ...
+    @overload
+    def var(
+        self: Series[Timedelta] | Series[Timestamp],
+        axis: AxisIndex | None = 0,
+        skipna: _bool | None = True,
+        ddof: int = 1,
+        numeric_only: _bool = False,
+        **kwargs: Any,
+    ) -> Never: ...
+    @overload
+    def var(
+        self: Series[complex],
+        axis: AxisIndex | None = 0,
+        skipna: _bool | None = True,
+        ddof: int = 1,
+        numeric_only: _bool = False,
+        **kwargs: Any,
+    ) -> float: ...
+    @overload
+    def var(
+        self: SupportsGetItem[Scalar, SupportsTruedivInt[S2]],
+        axis: AxisIndex | None = 0,
+        skipna: _bool | None = True,
+        ddof: int = 1,
+        numeric_only: _bool = False,
+        **kwargs: Any,
+    ) -> S2: ...
     # Rename axis with `mapper`, `axis`, and `inplace=True`
     @overload
     def rename_axis(

tests/series/test_agg.py

@@ -1,6 +1,9 @@
 import numpy as np
 import pandas as pd
-from typing_extensions import assert_type
+from typing_extensions import (
+    Never,
+    assert_type,
+)
 
 from tests import (
     TYPE_CHECKING_INVALID_USAGE,
@@ -14,27 +17,31 @@ def test_agg_any_float() -> None:
     check(assert_type(series.mean(), float), np.float64)
     check(assert_type(series.median(), float), np.float64)
     check(assert_type(series.std(), float), np.float64)
+    check(assert_type(series.var(), float), np.float64)
 
 
 def test_agg_bool() -> None:
     series = pd.Series([True, False, True])
     check(assert_type(series.mean(), float), np.float64)
     check(assert_type(series.median(), float), np.float64)
     check(assert_type(series.std(), float), np.float64)
+    check(assert_type(series.var(), float), np.float64)
 
 
 def test_agg_int() -> None:
     series = pd.Series([3, 1, 2])
     check(assert_type(series.mean(), float), np.float64)
     check(assert_type(series.median(), float), np.float64)
     check(assert_type(series.std(), float), np.float64)
+    check(assert_type(series.var(), float), np.float64)
 
 
 def test_agg_float() -> None:
     series = pd.Series([3.0, float("nan"), 2.0])
     check(assert_type(series.mean(), float), np.float64)
     check(assert_type(series.median(), float), np.float64)
     check(assert_type(series.std(), float), np.float64)
+    check(assert_type(series.var(), float), np.float64)
 
 
 def test_agg_complex() -> None:
@@ -57,6 +64,12 @@ def test_agg_complex() -> None:
         ),
     ):
         check(assert_type(series.std(), np.float64), np.float64)
+    with pytest_warns_bounded(
+        np.exceptions.ComplexWarning,
+        r"Casting complex values to real discards the imaginary part",
+        upper="2.3.99",
+    ):
+        check(assert_type(series.var(), float), np.float64)
 
 
 def test_agg_str() -> None:
@@ -65,6 +78,7 @@ def test_agg_str() -> None:
         series.mean()  # type: ignore[misc] # pyright: ignore[reportAttributeAccessIssue]
         series.median()  # type: ignore[misc] # pyright: ignore[reportAttributeAccessIssue]
         series.std()  # type: ignore[misc] # pyright: ignore[reportAttributeAccessIssue]
+        series.var()  # type: ignore[misc] # pyright: ignore[reportAttributeAccessIssue]
 
 
 def test_agg_ts() -> None:
@@ -75,6 +89,11 @@ def test_agg_ts() -> None:
     check(assert_type(series.median(), pd.Timestamp), pd.Timestamp)
     check(assert_type(series.std(), pd.Timedelta), pd.Timedelta)
 
+    if TYPE_CHECKING_INVALID_USAGE:
+
+        def _0() -> None:  # pyright: ignore[reportUnusedFunction]
+            assert_type(series.var(), Never)
+
 
 def test_agg_td() -> None:
     series = pd.Series(pd.to_timedelta(["1 days", "2 days", "3 days"]))
@@ -83,3 +102,8 @@ def test_agg_td() -> None:
     check(assert_type(series.mean(), pd.Timedelta), pd.Timedelta)
     check(assert_type(series.median(), pd.Timedelta), pd.Timedelta)
     check(assert_type(series.std(), pd.Timedelta), pd.Timedelta)
+
+    if TYPE_CHECKING_INVALID_USAGE:
+
+        def _0() -> None:  # pyright: ignore[reportUnusedFunction]
+            assert_type(series.var(), Never)

tests/series/test_series.py

@@ -780,9 +780,9 @@ def test_types_abs() -> None:
 
 def test_types_var() -> None:
     s = pd.Series([-10, 2, 3, 10])
-    s.var()
-    s.var(axis=0, ddof=1)
-    s.var(skipna=True, numeric_only=False)
+    check(assert_type(s.var(), float), np.float64)
+    check(assert_type(s.var(axis=0, ddof=1), float), np.float64)
+    check(assert_type(s.var(skipna=True, numeric_only=False), float), np.float64)
 
 
 def test_types_std() -> None: