feat(series): #1098 arithmetic addition #1275

cmp0xff · 2025-07-13T16:23:18Z

This PR is motivated by #1273 (review).

Comprehensive plan (maybe in another PR)

Inspired by #1093, one can draft the following comprehensive plan for all possible combinations of the left arithmetic operand, the binary arithmetic operator and the right arithmetic operand.

Left operand

Series[Any]
Series[int]
Series[float]
Series[complex]

Binary arithmetic operators

Include their right-version and functional version. In add we give a full example. We follow the official documentation.

__add__, __radd__, add, radd
__truediv__
__floordiv__
__pow__
__mod__
__mul__
__sub__

Right operand

Scalar
Sequence
numpy arrays
Series

Draft of a plan

We can have 4 ~ 5 test scripts for each left operand
In each test script, we can have 7 test functions for each binary arithmetic operator
In each test function, we test on all right operands. Do not forget the possible four variations, see the example of add.

Checklist

Closes Addition of a Series[int] with a complex returns Series[unknown] #1098, as stated in the title.
Tests added: Please use assert_type() to assert the type of any return value

tests/test_series.py

loicdiridollou

Looks like great progress here!

tests/test_series.py

pandas-stubs/core/series.pyi

tests/series/arithmetic/test_add.py

pandas-stubs/core/series.pyi

tests/series/arithmetic/complex/test_add.py

twoertwein

Thank you @cmp0xff!

I approved but I will let @Dr-Irv review/merge when he is back as this is a larger MR. I think adding all these overloads is in the the spirit of what pandas-stubs has been doing (but it might also create more maintenance burden).

(Personally, I'm still hoping for something like this #820 (comment) which would be more generic, but not supported by today's type checkers/python type system)

Dr-Irv

I really like the improvement of the tests and your approach. Thanks much for that.

I also like that you test the operator + (via both __add__() and __radd__(), and Series.add() and Series.radd(). But the arguments types for other for __add__() and Series.add() should be the same, and the argument types for other for __radd__() and Series.radd() should be the same.

As suggested in the review, if you make those changes, you should be in good shape.

Dr-Irv · 2025-07-24T19:55:45Z

tests/series/arithmetic/complex/test_add.py

+    # numpy typing gives ndarray instead of `pd.Series[...]` in reality, which we cannot fix
+    check(
+        assert_type(  # type: ignore[assert-type]
+            i + left, "pd.Series[complex]"  # pyright: ignore[reportAssertTypeFailure]
+        ),
+        pd.Series,
+        np.complex128,
+    )
+    check(
+        assert_type(  # type: ignore[assert-type]
+            f + left, "pd.Series[complex]"  # pyright: ignore[reportAssertTypeFailure]
+        ),
+        pd.Series,
+        np.complex128,
+    )
+    check(
+        assert_type(  # type: ignore[assert-type]
+            c + left, "pd.Series[complex]"  # pyright: ignore[reportAssertTypeFailure]
+        ),
+        pd.Series,
+        np.complex128,
+    )


I really do not want to have ignore statements in the tests.

I think if you modify __radd__() as follows it might work:

def __radd__( self: Series[complex], other: complex | Sequence[complex] | np_ndarray_anyint | np_ndarray_float | np_ndarray_complex ) -> Series[complex]: ...

As I suggested in the comment, it did not make a difference when I included np_ndarray_* in the typing for other. My guess is that pandas.Series.__radd__ has a lower priority than np.ndarray.__add__, which already gives Any.

So you're correct about the precedence.

Actually, I think np.ndarray.__add__() is type checking to return np.ndarray, so can you change the test to show that it does return np_ndarray_int or np_ndarray_float in the assert_type() statements, but that the runtime result is a Series.

Then add a comment indicating why the tests are this way because of the precedence.

4f11405 except for the mypy bug mentioned in the comment for the untyped Series

Dr-Irv · 2025-07-24T19:57:57Z

tests/series/arithmetic/float/test_add.py

+    # numpy typing gives ndarray instead of `pd.Series[...]` in reality, which we cannot fix
+    check(
+        assert_type(  # type: ignore[assert-type]
+            i + left, "pd.Series[float]"  # pyright: ignore[reportAssertTypeFailure]
+        ),
+        pd.Series,
+        np.float64,
+    )
+    check(
+        assert_type(  # type: ignore[assert-type]
+            f + left, "pd.Series[float]"  # pyright: ignore[reportAssertTypeFailure]
+        ),
+        pd.Series,
+        np.float64,
+    )
+    check(
+        assert_type(  # type: ignore[assert-type]
+            c + left, "pd.Series[complex]"  # pyright: ignore[reportAssertTypeFailure]
+        ),
+        pd.Series,
+        np.complex128,
+    )


same issue as above. Modify __radd__() to include the numpy arrays as the other argument.

Dr-Irv · 2025-07-24T19:58:34Z

tests/series/arithmetic/int/test_add.py

+    # numpy typing gives ndarray instead of `pd.Series[...]` in reality, which we cannot fix
+    check(
+        assert_type(  # type: ignore[assert-type]
+            i + left, "pd.Series[int]"  # pyright: ignore[reportAssertTypeFailure]
+        ),
+        pd.Series,
+        np.int64,
+    )
+    check(
+        assert_type(  # type: ignore[assert-type]
+            f + left, "pd.Series[float]"  # pyright: ignore[reportAssertTypeFailure]
+        ),
+        pd.Series,
+        np.float64,
+    )
+    check(
+        assert_type(  # type: ignore[assert-type]
+            c + left, "pd.Series[complex]"  # pyright: ignore[reportAssertTypeFailure]


same - modify __radd__()

Dr-Irv · 2025-07-24T19:59:46Z

tests/series/arithmetic/test_add.py

+    # numpy typing gives ndarray instead of `pd.Series[...]` in reality, which we cannot fix
+    check(
+        assert_type(  # type: ignore[assert-type]
+            i + left, pd.Series  # pyright: ignore[reportAssertTypeFailure]
+        ),
+        pd.Series,
+    )
+    check(
+        assert_type(  # type: ignore[assert-type]
+            f + left, pd.Series  # pyright: ignore[reportAssertTypeFailure]
+        ),
+        pd.Series,
+    )
+    check(
+        assert_type(  # type: ignore[assert-type]
+            c + left, pd.Series  # pyright: ignore[reportAssertTypeFailure]
+        ),
+        pd.Series,
+    )
+


same - modify __radd__()

pandas-stubs/core/series.pyi

…les#r2211559024

…les#r2211571551

cmp0xff

the arguments types for other for add() and Series.add() should be the same, and the argument types for other for radd() and Series.radd() should be the same.

With 2576640, arguments types are now

the same for Series.__add__ and Series.add`
almost the same for Series.__radd__ and Series.radd, except for np_ndarray_* are not added to the former case, because numpy has already defined the results to be of type Any.

cmp0xff · 2025-07-28T08:50:22Z

tests/series/arithmetic/complex/test_add.py

+    # numpy typing gives ndarray instead of `pd.Series[...]` in reality, which we cannot fix
+    check(
+        assert_type(  # type: ignore[assert-type]
+            i + left, "pd.Series[complex]"  # pyright: ignore[reportAssertTypeFailure]
+        ),
+        pd.Series,
+        np.complex128,
+    )
+    check(
+        assert_type(  # type: ignore[assert-type]
+            f + left, "pd.Series[complex]"  # pyright: ignore[reportAssertTypeFailure]
+        ),
+        pd.Series,
+        np.complex128,
+    )
+    check(
+        assert_type(  # type: ignore[assert-type]
+            c + left, "pd.Series[complex]"  # pyright: ignore[reportAssertTypeFailure]
+        ),
+        pd.Series,
+        np.complex128,
+    )


As I suggested in the comment, it did not make a difference when I included np_ndarray_* in the typing for other. My guess is that pandas.Series.__radd__ has a lower priority than np.ndarray.__add__, which already gives Any.

pandas-stubs/core/series.pyi

Dr-Irv

Can you make __radd__() and radd() have the same arguments, even though it doesn't do what we want?

Can you update the tests as indicated in the comment so that you don't have the # type: ignore, but you use assert_type() on the type that numpy is returning, and then check() on the runtime type (pd.Series)

Also, I'm finding it hard to see what you changed since you're original commit. Please don't force push your changes, but just push your latest commits.

cmp0xff · 2025-07-29T09:24:29Z

Can you make __radd__() and radd() have the same arguments, even though it doesn't do what we want?

They are almost the same now, except for __radd__s do not need Series in other, because they are governed by __add__ already.

Can you update the tests as indicated in the comment so that you don't have the # type: ignore, but you use assert_type() on the type that numpy is returning, and then check() on the runtime type (pd.Series)

Added, except for #1275 (comment)

Also, I'm finding it hard to see what you changed since you're original commit. Please don't force push your changes, but just push your latest commits.

I see, but the base branch had been updated and there were conflicts. What should I do instead of rebasing, which caused the forced-update?

Dr-Irv · 2025-07-29T13:47:46Z

I see, but the base branch had been updated and there were conflicts. What should I do instead of rebasing, which caused the forced-update?

git checkout mybranch
git fetch upstream
git merge upstream/main

If there are conflicts when you merge, fix them, and commit, and you should be good.

Dr-Irv

thanks @cmp0xff . Really nice work!

cmp0xff commented Jul 13, 2025

View reviewed changes

tests/test_series.py Outdated Show resolved Hide resolved

tests/test_series.py Outdated Show resolved Hide resolved

cmp0xff marked this pull request as ready for review July 13, 2025 16:32

loicdiridollou reviewed Jul 13, 2025

View reviewed changes

tests/test_series.py Outdated Show resolved Hide resolved

tests/test_series.py Outdated Show resolved Hide resolved

twoertwein reviewed Jul 14, 2025

View reviewed changes

pandas-stubs/core/series.pyi Outdated Show resolved Hide resolved

pandas-stubs/core/series.pyi Outdated Show resolved Hide resolved

cmp0xff marked this pull request as draft July 14, 2025 16:51

cmp0xff force-pushed the feature/cmp0xff/1098-__add__-and-__mul__ branch from 3b3f899 to bf79de1 Compare July 15, 2025 09:29

cmp0xff commented Jul 15, 2025

View reviewed changes

tests/series/arithmetic/test_add.py Outdated Show resolved Hide resolved

cmp0xff force-pushed the feature/cmp0xff/1098-__add__-and-__mul__ branch 2 times, most recently from 02c646d to 8f43efc Compare July 15, 2025 15:25

cmp0xff changed the title ~~feat(series): #1098 __add__ and __mul__~~ feat(series): #1098 additions Jul 15, 2025

cmp0xff changed the title ~~feat(series): #1098 additions~~ feat(series): #1098 arithmetic additions Jul 15, 2025

cmp0xff changed the title ~~feat(series): #1098 arithmetic additions~~ feat(series): #1098 arithmetic addition Jul 15, 2025

cmp0xff marked this pull request as ready for review July 15, 2025 16:57

cmp0xff requested review from loicdiridollou and twoertwein July 16, 2025 09:34

twoertwein reviewed Jul 16, 2025

View reviewed changes

pandas-stubs/core/series.pyi Outdated Show resolved Hide resolved

pandas-stubs/core/series.pyi Show resolved Hide resolved

cmp0xff added a commit to cmp0xff/pandas-stubs that referenced this pull request Jul 16, 2025

fix(comment): pandas-dev#1275 (comment)

0784786

twoertwein reviewed Jul 16, 2025

View reviewed changes

twoertwein approved these changes Jul 17, 2025

View reviewed changes

cmp0xff added a commit to cmp0xff/pandas-stubs that referenced this pull request Jul 17, 2025

fix(comment): pandas-dev#1275 (comment)

1e11d7e

cmp0xff force-pushed the feature/cmp0xff/1098-__add__-and-__mul__ branch from e101ff4 to 14f79a0 Compare July 17, 2025 07:32

cmp0xff added a commit to cmp0xff/pandas-stubs that referenced this pull request Jul 17, 2025

fix(comment): pandas-dev#1275 (comment)

8d5c397

cmp0xff force-pushed the feature/cmp0xff/1098-__add__-and-__mul__ branch from 14f79a0 to 2b94ab0 Compare July 17, 2025 15:10

This was referenced Jul 17, 2025

feat(series): #1098 arithmetic truediv #1280

Draft

refactor: #718 only drop TimestampSeries #1274

Draft

Dr-Irv requested changes Jul 24, 2025

View reviewed changes

Dr-Irv reviewed Jul 24, 2025

View reviewed changes

pandas-stubs/core/series.pyi Show resolved Hide resolved

cmp0xff added 3 commits July 28, 2025 12:31

refactor: minimal systematic implementation

c13e5cd

feat: Series[int] +

c494518

feat: Series[float] +

566d8ec

cmp0xff added 6 commits July 28, 2025 12:31

refactor: py310 and remove why

2581638

feat: Series[complex] +

6f8e00a

fix(comment): pandas-dev#1275 (comment)

7fa0a3e

fix(comment): https://github.com/pandas-dev/pandas-stubs/pull/1275/fi…

caa271b

…les#r2211559024

fix(comment): https://github.com/pandas-dev/pandas-stubs/pull/1275/fi…

fe4e10a

…les#r2211571551

fix(comment): argument types pandas-dev#1275 (review)

2576640

cmp0xff force-pushed the feature/cmp0xff/1098-__add__-and-__mul__ branch from 2b94ab0 to 2576640 Compare July 28, 2025 10:34

cmp0xff commented Jul 28, 2025

View reviewed changes

cmp0xff requested a review from Dr-Irv July 28, 2025 10:35

Dr-Irv requested changes Jul 28, 2025

View reviewed changes

fix(comment): pandas-dev#1275 (review)

4f11405

cmp0xff requested a review from Dr-Irv July 29, 2025 09:24

Dr-Irv approved these changes Jul 29, 2025

View reviewed changes

Dr-Irv merged commit 845f9c5 into pandas-dev:main Jul 29, 2025
13 checks passed

cmp0xff deleted the feature/cmp0xff/1098-__add__-and-__mul__ branch July 29, 2025 14:06

Uh oh!

feat(series): #1098 arithmetic addition #1275

feat(series): #1098 arithmetic addition #1275

Uh oh!

Conversation

cmp0xff commented Jul 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Comprehensive plan (maybe in another PR)

Left operand

Binary arithmetic operators

Right operand

Draft of a plan

Checklist

Uh oh!

Uh oh!

Uh oh!

loicdiridollou left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

twoertwein left a comment

Choose a reason for hiding this comment

Uh oh!

Dr-Irv left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cmp0xff left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Dr-Irv left a comment

Choose a reason for hiding this comment

Uh oh!

cmp0xff commented Jul 29, 2025

Uh oh!

Dr-Irv commented Jul 29, 2025

Uh oh!

Dr-Irv left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

cmp0xff commented Jul 13, 2025 •

edited

Loading