Should we adopt mypy's @overload?

[gvanrossum]

In mypy there's an @overload decorator. However, it was introduced before Union, and the latter is usually sufficient (or using type variables).

Is it still needed? If we need it, should it be part of this PEP or should it be a separate proposal for a runtime feature to be added to functools (like @singledispatch)? But if separate, how would it interact with generic types?

[JukkaL]

@overload (or something sufficiently similar) is still useful in certain cases, including certain built-in methods.

For example, consider the signature of __init__ of str:

@overload
def __init__(self) -> None: pass
@overload
def __init__(self, o: object) -> None: pass
@overload
def __init__(self, o: _byte_types, encoding: str = None, errors: str = 'strict') -> None: pass

Union types are not sufficient to represent the fact that encoding and errors are only valid if the first argument is a bytes-like object.

__getitem__ of bytes is another example:

@overload
def __getitem__(self, i: int) -> int: pass
@overload
def __getitem__(self, s: slice) -> bytes: pass

Again, union types (or type variables) are not sufficient.

map is a third example where we use overloading to support different numbers of arguments:

@overload
def map(func: Function[[_T1], _S], iter1: Iterable[_T1]) -> Iterator[_S]: pass
@overload
def map(func: Function[[_T1, _T2], _S], iter1: Iterable[_T1],
        iter2: Iterable[_T2]) -> Iterator[_S]: pass  
# ... and we could add more items to support more than two iterables

I think we need at least a stub-level feature for representing the above cases. A potential approach is to use multiple signatures for a function in a stub file, without a decorator. For example:

def __getitem__(self, i: int) -> int: pass
def __getitem__(self, s: slice) -> bytes: pass

[ambv]

The examples that @JukkaL listed here are one of the reasons pytypedecl went with a separate file for type definitions.

In general I saw some minor interest in having multiple dispatch implemented in functools after we introduced singledispatch. I'd be happy to work on that separate PEP as a follow-up.

Can we leave it out for now to not risk introducing a confusing feature that's impossible to remove later?

[gvanrossum]

We need something for stubs; there are a fair number of stdlib things
that are naturally expressed as overloads. (And then you have map() and
filter(), which are technically an overload of an infinite number of
different variants. But I'm okay with just listing 10 in the stub file.
This was discussed elsewhere, though I can't find it now.)

Okay to disallow it for non-stub files and doing a separate PEP for multi-dispatch.

[gvanrossum]

Closing .The decision is made. We'll support @overload in stubs only. The editing TODO is in README.rst. We'll also separately try to work on a PEP for multiple dispatch.