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.

Mypy already takes first overload for ambiguous arguments. This example is however genuinely unsafe from the static typing point of view. Please read the docs https://mypy.readthedocs.io/en/latest/more_types.html#type-checking-the-variants

> Mypy already takes first overload for ambiguous arguments.

This is true, but it requires that the return types match (covariantly, IIUC) for the overlapping types. So you can have

@overload
def foo(x: int) -> int: ...
@overload
def foo(x: float) -> float: ...

But you can't have

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

(and the docs explain why -- search for "unsafe_func").