BUG: Type stubs only support pd.Timedelta, but could (should?) also support datetime.timedelta

[gwerbin-tive]

Pandas version checks

• I have checked that this issue has not already been reported.

• I have confirmed this bug exists on the latest version of pandas.

• I have confirmed this bug exists on the main branch of pandas.

Reproducible Example

typ.py:

from datetime import timedelta

import pandas as pd


s1 = pd.date_range("2023-01-01", periods=10, freq='1D')

s2 = s1 - timedelta(days=1)

print(s2)

Output, showing the expected result:

DatetimeIndex(['2022-12-31', '2023-01-01', '2023-01-02', '2023-01-03',
               '2023-01-04', '2023-01-05', '2023-01-06', '2023-01-07',
               '2023-01-08', '2023-01-09'],
              dtype='datetime64[ns]', freq='D')

Mypy config in pyproject.toml:

[tool.mypy]

python_version = '3.11'

strict = true

plugins = [
  'numpy.typing.mypy_plugin',
  'pydantic.mypy',
]

Issue Description

The type stubs don't recognize datetime.timedelta as a valid operand:

% mypy typ.py
typ.py:7: error: No overload variant of "__sub__" of "DatetimeIndex" matches argument type "timedelta"  [operator]
typ.py:7: note: Possible overload variants:
typ.py:7: note:     def __sub__(self, TimedeltaSeries, /) -> TimestampSeries
typ.py:7: note:     def __sub__(self, Timedelta | TimedeltaIndex, /) -> DatetimeIndex
typ.py:7: note:     def __sub__(self, Timestamp | DatetimeIndex, /) -> TimedeltaIndex

Expected Behavior

I expected this to pass type-checking, because it works fine at runtime and is officially supported behavior (as far as I know).

If this isn't meant to be supported and only works by coincidence, then I apologize for the noise and feel free to close.

I did notice that pd.Timedelta is a subclass of datetime.timedelta, so this should be a really easy change.

I looked around for a while and didn't find the type stubs for this particular method, otherwise I would have just submitted a patch straight away.

Installed Versions

% mypy --version
mypy 1.7.1 (compiled: yes)

Python 3.11.6 (main, Oct  2 2023, 17:46:45) [Clang 13.1.6 (clang-1316.0.21.2.5)]
Type 'copyright', 'credits' or 'license' for more information
IPython 8.18.1 -- An enhanced Interactive Python. Type '?' for help.

In [1]: import pandas as pd

In [2]: pd.show_versions()

INSTALLED VERSIONS
------------------
commit              : a671b5a8bf5dd13fb19f0e88edc679bc9e15c673
python              : 3.11.6.final.0
python-bits         : 64
OS                  : Darwin
OS-release          : 21.6.0
Version             : Darwin Kernel Version 21.6.0: Fri Sep 15 16:17:04 PDT 2023; root:xnu-8020.240.18.703.5~1/RELEASE_ARM64_T6000
machine             : arm64
processor           : arm
byteorder           : little
LC_ALL              : en_US.UTF-8
LANG                : en_US.UTF-8
LOCALE              : en_US.UTF-8

pandas              : 2.1.4
numpy               : 1.26.2
pytz                : 2023.3.post1
dateutil            : 2.8.2
setuptools          : 68.2.2
pip                 : 23.3.1
Cython              : None
pytest              : 7.4.3
hypothesis          : 6.92.1
sphinx              : None
blosc               : None
feather             : None
xlsxwriter          : None
lxml.etree          : None
html5lib            : None
pymysql             : None
psycopg2            : None
jinja2              : None
IPython             : 8.18.1
pandas_datareader   : None
bs4                 : None
bottleneck          : None
dataframe-api-compat: None
fastparquet         : None
fsspec              : 2023.12.2
gcsfs               : None
matplotlib          : None
numba               : None
numexpr             : None
odfpy               : None
openpyxl            : None
pandas_gbq          : None
pyarrow             : 14.0.2
pyreadstat          : None
pyxlsb              : None
s3fs                : 2023.12.2
scipy               : None
sqlalchemy          : 1.4.50
tables              : None
tabulate            : None
xarray              : None
xlrd                : None
zstandard           : None
tzdata              : 2023.3
qtpy                : None
pyqt5               : None

[Dr-Irv]

Thanks for the report. In pandas-stubs/core/indexes/datetimes.pyi, have to change the arithmetic methods that accept Timedelta as an argument to use timedelta instead, since pd.Timedelta is a subclass of datetime.timedelta.

PR with tests welcome

[gwerbin-tive]

Thanks @twoertwein & @Dr-Irv!