What are the actual allowed types of each individual overload?

[bzoracler]

I have a function which accepts either 1 positional int argument or any number of str arguments, all passed positionally, and packed into a tuple upon return. I thought I could do this:

from collections.abc import Callable
from typing import overload, Never as _InferFromUnion

def _positional_strs_only[F: Callable[..., object]](f: F, /) -> F | Callable[[*tuple[str, ...]], _InferFromUnion]:
    return f

@_positional_strs_only
def f_non_overloaded[*Ts](*args: *Ts) -> tuple[*Ts]: ...

@overload
def f(arg: int, /) -> None: ...
@overload
@_positional_strs_only
def f[*Ts](*args: *Ts) -> tuple[*Ts]: ...

This works in a non-overloaded context (reveal_type(f_non_overloaded("a", "b")) should reveal tuple[Literal['a'], Literal['b']] or tuple[str, str], and attempts to pass non-strs should emit typing errors). However, it doesn't work in an overloaded context.

Some quick experiments reveal that

1. No type-checkers seem to support a union of callables in any overload.
2. No type-checkers seem to support an overloaded callable in any overload (so a @transform_into_overloaded_callable is either not allowed on an overload item, or does not produce a valid overloaded callable type).
3. mypy allows nominal types which are callable in an individual overload item (see e.g. mypy Playground). Other type-checkers don't seem to allow this.

(1) also results in confusing error messages across type-checkers; mypy and pyrefly both say something to the effect of

Callable[[*Ts], tuple[*Ts]] | Callable[[*tuple[str, ...]], Never] is not callable

---

My questions are:

1. Should nominal types which support __call__ be allowed as the type of an overload item? (My gut feeling says this should be allowed, otherwise someone who wants to use the signature of a nominal type's __call__ will end up having to add a no-op def deco[**P, R](f: Callable[P, R], /) -> Callable[P, R]: return f just to appease type-checkers; pyright and pyrefly currently require this workaround).
2. Assuming this is just a under-specification with no supporting implementations at the moment, should union callable types and overloaded callable types be allowed as individual overload item types?

[RavshanSean]

I think there are two separate questions here: whether an overload item can be represented by an arbitrary callable object, and whether an overload item can itself contain multiple possible call signatures.

For the first case, a nominal class implementing __call__ can describe a valid callable signature. However, accepting that class as an overload item would require the type checker to extract its call signature after applying the decorator. That's a separate operation from checking whether the decorated object is callable.

For the second case, a union of callable types introduces an additional ambiguity. A union such as:

Callable[[int], int] | Callable[[str], str]

doesn't mean that the value supports both signatures. It means the value may implement either callable type, and callers must use arguments that are valid for every possible member.

By contrast, an overloaded callable describes one callable supporting multiple signatures.

Therefore, automatically flattening a union of callables into an overload set could be unsound.

An overloaded callable type is a more plausible candidate for expansion into multiple overload items, but that would need explicit specification of how the resulting signatures are ordered, how overlapping signatures are handled, and whether decorators are allowed to change the effective overload set.

I think these distinctions are worth making explicit before deciding whether decorated overload items should accept arbitrary callable types.

For the original use case, the most portable approach today is still to declare the desired overload signatures directly rather than rely on a decorator to transform an individual overload item.