Proper annotation of python's add operator

add.py

"""An example of how deep python annotations can go.

Here I show a possible way to annotate an add() function to account for as many cases as possible.
We assume that the add() function simply adds the two numbers and does not call internal __add__ or __radd__ methods.
"""
from typing import Protocol, overload

T_contra = TypeVar('T_contra', contravariant=True)
T_co = TypeVar('T_co', covariant=True)

class SupportsAdd(Protocol[T_contra, T_co]):
    def __add__(self, x: T_contra) -> T_co: ...

class SupportsRAdd(Protocol[T_contra, T_co]):
    def __radd__(self, x: T_contra) -> T_co: ...

@overload
def add(x: SupportsAdd[T_contra, T_co], y: T_contra) -> T_co: ...
@overload
def add(x: T_contra, y: SupportsRAdd[T_contra, T_co]) -> T_co: ...

def add(x, y):
    return x + y