Series + Timedelta = no overload variant of ...

[JoranDox]

Describe the bug

+ (__add__) between Series and Timedeltas is broken in 2.3.2, still works in 2.3.1 (the code still works so I'm assuming it's a pandas-stubs issue)

To Reproduce
about as small as I can get it

import pandas as pd
_ = pd.Series() + pd.Timedelta(hours=2)

result (using tox which runs mypy with these settings, and I don't think any other magic?):

type: commands[1]> mypy --warn-return-any --warn-unreachable --check-untyped-defs --no-namespace-packages ./app ./tests
tests/isolated example.py:5: error: No overload variant of "__add__" of "Series" matches argument type "Timedelta"  [operator]
tests/isolated example.py:5: note: Possible overload variants:
tests/isolated example.py:5: note:     def __add__(self, str, /) -> Never
tests/isolated example.py:5: note:     def __add__(self, complex | ExtensionArray | ndarray[tuple[Any, ...], dtype[Any]] | dict[str, ndarray[tuple[Any, ...], dtype[Any]]] | SequenceNotStr[Any] | Series[Any], /) -> Series[Any]
tests/isolated example.py:5: note:     def __add__(self, Series[Never], /) -> Series[Any]
tests/isolated example.py:5: note:     def [_T_COMPLEX: complex] __add__(self, _T_COMPLEX | Sequence[_T_COMPLEX] | Series[_T_COMPLEX], /) -> Series[_T_COMPLEX]
tests/isolated example.py:5: note:     def __add__(self, ndarray[tuple[Any, ...], dtype[numpy.bool[builtins.bool]]], /) -> Series[bool]
tests/isolated example.py:5: note:     def __add__(self, ndarray[tuple[Any, ...], dtype[integer[Any]]], /) -> Series[int]
tests/isolated example.py:5: note:     def __add__(self, ndarray[tuple[Any, ...], dtype[floating[Any]]], /) -> Series[float]
tests/isolated example.py:5: note:     def __add__(self, ndarray[tuple[Any, ...], dtype[complexfloating[Any, Any]]], /) -> Series[complex]
tests/isolated example.py:5: note:     def __add__(self, builtins.bool | Sequence[builtins.bool] | ndarray[tuple[Any, ...], dtype[numpy.bool[builtins.bool]]] | ndarray[tuple[Any, ...], dtype[integer[Any]]] | Series[builtins.bool], /) -> Series[int]
tests/isolated example.py:5: note:     def [_T_INT: int] __add__(self, int | Sequence[int] | ndarray[tuple[Any, ...], dtype[numpy.bool[builtins.bool]]] | ndarray[tuple[Any, ...], dtype[integer[Any]]] | ndarray[tuple[Any, ...], dtype[floating[Any]]] | Series[_T_INT], /) -> Series[float]
tests/isolated example.py:5: note:     def [_T_COMPLEX: complex] __add__(self, _T_COMPLEX | Sequence[_T_COMPLEX] | ndarray[tuple[Any, ...], dtype[numpy.bool[builtins.bool]]] | ndarray[tuple[Any, ...], dtype[integer[Any]]] | ndarray[tuple[Any, ...], dtype[floating[Any]]] | ndarray[tuple[Any, ...], dtype[complexfloating[Any, Any]]] | Series[_T_COMPLEX], /) -> Series[complex]
tests/isolated example.py:5: note:     def __add__(self, ndarray[tuple[Any, ...], dtype[numpy.bool[builtins.bool]]] | ndarray[tuple[Any, ...], dtype[integer[Any]]] | ndarray[tuple[Any, ...], dtype[floating[Any]]] | ndarray[tuple[Any, ...], dtype[complexfloating[Any, Any]]], /) -> Never
tests/isolated example.py:5: note:     def __add__(self, str | Sequence[str] | ndarray[tuple[Any, ...], dtype[str_]] | Series[str], /) -> Series[str]

interestingly: this doesn't trigger it somehow, which is actually closer to the code where I encountered the bug, but the minimal example works so idk:

import pandas as pd

def fun(s: pd.DataFrame) -> pd.Series:
    return s["some_column"] + pd.Timedelta(hours=1)

Please complete the following information:

• OS: linux
• OS Version: Kubuntu 25.04
• python version 3.12.4
• version of type checker: mypy: 1.17.1
• version of installed pandas-stubs: 2.3.2 (broken) 2.3.1 (works)

[Dr-Irv]

We made an intentional change with the latest version to make sure that when you are adding an untyped Series with Timedelta, that you have to tell the type checker that you know what you are doing.

In your first example, Series() is Series[Any]. If the series was a series of strings, then at runtime the code would fail. If you know that the series has a timestamp or timedelta, you can do a cast to tell the type checker that you know the type.

In the second example, if you write:

import pandas as pd

def fun(s: pd.DataFrame) -> pd.Series:
   foo = s["some_column"] + pd.Timedelta(hours=1)
   return foo

Then the new stubs will catch that for the same reason, because s["some_column"] has an unknown type.

I'm not quite sure why doing a return as you did in the second example isn't picked up, but it is most likely because of bi-directional type checking.

See discussion here: https://github.com/pandas-dev/pandas-stubs/blob/main/docs/philosophy.md#generic-series-have-restricted-arithmetic

[JoranDox]

Oh, that's cool, I like it!

It was very unclear from the response (I guess that's mypy's fault though?) that that's the reason (and kind of surprising to see this in a patch level change, but that's just because you're following pandas' versioning, so I can't really fault pandas-stubs for that either I guess).

In the actual code I have a dataframe that I reasonably trust (it's built from a list of typechecked dictionaries), and I'm taking a column from that which again I trust is correctly typed, how am I supposed to have this as automatically typed as possible?

e.g.

df["some_datetimes"] + some_timedelta

like this? ->

some_datetimes: pd.Series[pd.Timestamp] = df["some_datetimes"] 
some_datetimes + some_timedelta

now I still get
error: Unsupported operand types for + ("Series[Timestamp]" and "Timedelta") [operator]

so I guess I'm still doing something wrong?

[Dr-Irv]

Oh, that's cool, I like it!

Great!

so I guess I'm still doing something wrong?

Well, slightly. What would work for now is the following:

At top of file:

from typing import TYPE_CHECKING
if TYPE_CHECKING:
    from pandas.core.series import TimestampSeries

then

some_datetimes = cast("TimestampSeries",  df["some_datetimes"] )
some_datetimes + some_timedelta

would work.

However, we are soon going to be removing TimestampSeries so that the following would work:

some_datetimes = cast("pd.Series[Timestamp]",  df["some_datetimes"] )
some_datetimes + some_timedelta

Note that you may not be able to use some_datetimes: pd.Series[pd.Timestamp] = df["some_datetime"] as that may fail at runtime because Series is not generic in pandas.

I'm going to reopen the issue and see if @cmp0xff can add support for pd.Series[Timestamp] + Timedelta before we remove TimestampSeries to more quickly address your issue.

[Owen-OptiGrid]

I'm running into similar issues calling the add method on a series with a Timestamp. MyPy won't except add being passed a single Timestamp anymore.