Improve stubs for operator

[Lehmaning]

• Narrowing type of operator.add, operator.mulwith existing Protocol SupportsAdd, SupportsMul

[github-actions]

Diff from mypy_primer, showing the effect of this PR on open source code:

spark (https://github.com/apache/spark)
+ python/pyspark/core/rdd.py:2159: error: Argument 2 to "fold" of "RDD" has incompatible type "Callable[[SupportsAdd[_T_contra, _T_co], _T_contra], _T_co]"; expected "Callable[[float | Literal[0], float | Literal[0]], float | Literal[0]]"  [arg-type]
+ python/pyspark/core/rdd.py:2159: error: Argument 2 to "fold" of "RDD" has incompatible type "Callable[[SupportsAdd[_T_contra, _T_co], _T_contra], _T_co]"; expected "Callable[[complex | Literal[0], complex | Literal[0]], complex | Literal[0]]"  [arg-type]
+ python/pyspark/core/rdd.py:2159: error: Argument 2 to "fold" of "RDD" has incompatible type "Callable[[SupportsAdd[_T_contra, _T_co], _T_contra], _T_co]"; expected "Callable[[signedinteger[_32Bit] | Literal[0], signedinteger[_32Bit] | Literal[0]], signedinteger[_32Bit] | Literal[0]]"  [arg-type]
+ python/pyspark/core/rdd.py:2159: error: Argument 2 to "fold" of "RDD" has incompatible type "Callable[[SupportsAdd[_T_contra, _T_co], _T_contra], _T_co]"; expected "Callable[[signedinteger[_64Bit] | Literal[0], signedinteger[_64Bit] | Literal[0]], signedinteger[_64Bit] | Literal[0]]"  [arg-type]
+ python/pyspark/core/rdd.py:2159: error: Argument 2 to "fold" of "RDD" has incompatible type "Callable[[SupportsAdd[_T_contra, _T_co], _T_contra], _T_co]"; expected "Callable[[floating[_32Bit] | Literal[0], floating[_32Bit] | Literal[0]], floating[_32Bit] | Literal[0]]"  [arg-type]
+ python/pyspark/core/rdd.py:2159: error: Argument 2 to "fold" of "RDD" has incompatible type "Callable[[SupportsAdd[_T_contra, _T_co], _T_contra], _T_co]"; expected "Callable[[float64 | Literal[0], float64 | Literal[0]], float64 | Literal[0]]"  [arg-type]
+ python/pyspark/core/rdd.py:2159: error: Argument 2 to "fold" of "RDD" has incompatible type "Callable[[SupportsAdd[_T_contra, _T_co], _T_contra], _T_co]"; expected "Callable[[ndarray[Any, Any] | Literal[0], ndarray[Any, Any] | Literal[0]], ndarray[Any, Any] | Literal[0]]"  [arg-type]

jax (https://github.com/google/jax)
+ jax/_src/export/shape_poly.py:770: error: Argument 1 to "reduce" has incompatible type "Callable[[SupportsMul[_T_contra, _T_co], _T_contra], _T_co]"; expected "Callable[[int, _DimExpr], int]"  [arg-type]

sympy (https://github.com/sympy/sympy)
+ sympy/polys/matrices/dense.py:104: error: Argument 1 to "map" has incompatible type "Callable[[SupportsMul[_T_contra, _T_co], _T_contra], _T_co]"; expected "Callable[[R, Any], R]"  [arg-type]
+ sympy/tensor/array/expressions/arrayexpr_derivatives.py:44: error: Argument 1 to "reduce" has incompatible type "Callable[[SupportsAdd[_T_contra, _T_co], _T_contra], _T_co]"; expected "Callable[[tuple[()], Any], tuple[()]]"  [arg-type]
+ sympy/tensor/array/expressions/arrayexpr_derivatives.py:45: error: Argument 1 to "reduce" has incompatible type "Callable[[SupportsAdd[_T_contra, _T_co], _T_contra], _T_co]"; expected "Callable[[tuple[()], Any], tuple[()]]"  [arg-type]

[jorenham]

This won't work if you @overload your __add__ or __mul__ methods. Or at least, it certainly won't work on mypy, and can lead to unexpected results on pyright in case of valid overlapping overloads.

[jorenham]

This also doesn't cover the reflected cases, i.e. when a.__add__(b) returns NotImplemented and cpython delegates to b.__radd__(a).

And if that wasn't complicated enough: When type[b] <: type[a] holds, b.__radd__(a) is called before a.__add__(b)

[srittau]

Unfortunately, the type system currently can't express the various special rules that apply to operator.{add,mul}(), which is why we're using Any here, as @jorenham pointed out. (Per our current policy, this should be documented in the stubs itself, so there's room for improvement there.)