Regression in 2.3.3.251201

[markgras]

Describe the bug
The following code snippet runs and passes mypy type checking w/ pandas-stubs==2.3.2.250926 (second-latest release at time of writing). However, it fails w/ pandas-stubs==2.3.3.251201 (latest release at time of writing).

To Reproduce

1. Provide a minimal runnable pandas example that is not properly checked by the stubs.

Code:

from datetime import UTC, datetime, timedelta
import pandas as pd

dt1 = datetime.now(UTC)
dt2 = dt1 + timedelta(seconds=5)
df = pd.DataFrame((dt1, dt2), columns=("time",))
diff = df["time"].diff()
dt = diff.dt  # First error here
print(dt.total_seconds())  # Second error here

Output when run:

0    NaN
1    5.0
Name: time, dtype: float64

2. Indicate which type checker you are using (mypy or pyright).

mypy

3. Show the error message received from that type checker while checking your example.

pd.py:8: error: Argument 1 to "__get__" of "DtDescriptor" has incompatible type "Series[float]"; expected "Series[Never]"  [arg-type]
pd.py:9: error: "Properties" has no attribute "total_seconds"  [attr-defined]
Found 2 errors in 1 file (checked 1 source file)

Please complete the following information:

• OS: Linux
• OS Version: Arch Linux x86_64
• python version: 3.13.7
• version of type checker: mypy 1.19.0 (compiled: yes)
• version of installed pandas-stubs: 2.3.3.251201

Additional context

$ pip list
Package           Version
----------------- -----------------
librt             0.6.3
mypy              1.19.0
mypy_extensions   1.1.0
numpy             2.3.5
pandas            2.3.3
pandas-stubs      2.3.3.251201
pathspec          0.12.1
pip               25.3
python-dateutil   2.9.0.post0
pytz              2025.2
six               1.17.0
types-pytz        2025.2.0.20251108
typing_extensions 4.15.0
tzdata            2025.2

[Dr-Irv]

This is on purpose.

The expression df["time"].diff() has an unknown type, because df["time"] could be a float, a string, a time, etc. So you have to tell the type checker "I know this is a time" by using a cast

So if you change line 7 to

diff = cast("pd.Series[pd.Timestamp]", df["time"]).diff()

by importing cast from typing, the error will go away.

[markgras]

Noted. Thanks for the quick reply!

[Dr-Irv]

So a colleague used the latest version and now we have to convert code like this:

# old code
s = (df["end_time"] - df["start_time"]).dt.total_seconds()

to

s = cast("pd.Series[pd.Timedelta]", (df["end_time"] - df["start_time"])).dt.total_seconds()

This is quite painful and makes the code less readable.

So I think we need to make Series[Any].dt work and let it allow whatever is possible after the dt attribute, independent of whether it is a Series[Timedelta] or Series[Timestamp] inside.

@cmp0xff can you take a look at this?

[cmp0xff]

now we have to convert code like this:

# old code
s = (df["end_time"] - df["start_time"]).dt.total_seconds()

to

s = cast("pd.Series[pd.Timedelta]", (df["end_time"] - df["start_time"])).dt.total_seconds()

This is what I wanted to discuss in #1519. Will take a look.