An exceedingly common pattern in many Python libraries is for a function to accept either a string or a list of strings, and change the function output accordingly.

This however does not play nice with @typing.overload, as a str variable is also an Iterable[str] that yields individual characters; a bytes variable is also an Iterable[bytes].

The example below confuses tools like mypy:

@overload
def f(x: str) -> int
   ...

@overload
def f(x: Iterable[str]) -> List[int]
   ...

def f(x):
    if isinstance(x, str):
        return len(x)
    return [len(i) for i in x]


mypy output:

error: Overloaded function signatures 1 and 2 overlap with incompatible return types


The proposed solution is to modify PEP484 to specify that, in case of ambiguity, whatever overloaded typing is defined first wins. This would be coherent with the behaviour of @functools.singledispatch.