Optional keyword parameters vs overloads

[randolf-scholz]

I was writing a protocol class for Array-like objects supporting a round(self, *, decimals: int = 0) -> Self operation. To my surprise, it didn't like torch.Tensor, which defines:

@overload
def round_(self) -> Tensor: 
@overload
def round_(self, *, decimals: _int) -> Tensor:

Both mypy and pyright seem to agree that:

1. (self, *, decimals: int = 0) -> X is a subtype of Overload[(self) -> X, (self, *, decimals: int) -> X]
2. Overload[(self) -> X, (self, *, decimals: int) -> X] is not a subtype of (self, *, decimals: int = 0) -> X

But to me, it seems these signatures are equivalent. Am I missing something, or is this a limitation of the type checkers?

Code sample in pyright playground mypy-playground

from typing import overload, Protocol, Self, Any

class ArrayProto(Protocol):
    def round(self, *, decimals: int = ...) -> Self: ...

class Array:
    def round(self, *, decimals: int = 0) -> Self:
        return self

class TensorProto(Protocol):
    @overload
    def round(self) -> Self: ...
    @overload
    def round(self, *, decimals: int) -> Self: ...

class Tensor:
    @overload
    def round(self) -> Self: ...
    @overload
    def round(self, *, decimals: int) -> Self: ...
    def round(self, *args: Any, **kwargs: Any) -> Self:
        return self

x: TensorProto = Array()  # ✅
y: ArrayProto = Tensor()  # ❌

[erictraut]

Refer to this section of the typing spec for subtyping rules involving callables with overloads.

Here's the relevant part:

If a callable A is overloaded with two or more signatures, it is a subtype of callable B if at least one of the overloaded signatures in A is a subtype of B.

In your example, this condition is not met.

[randolf-scholz]

Where does this rule come from? On first inspection, it seems this is only a sufficient criterion, not a necessary one, and presupposes that the order of overloads is irrelevant. If we follow this wording strictly, then for any given target signature, the following would be a subtype:

@overload
def foo(*args: Any, **kwargs: Any) -> object:
@overload
def foo(<target signature>) -> <target type>

Despite that, by the usual convention of ordered overloads, this would return object for any input. The example in the spec also reminds me again of this issue: python/mypy#15790. So now, by definition, this is considered OK?

If we go from first principles, shouldn't the rule be:

For two functions A and B, A is a subtype of B if and only if for any valid arguments to B, these are also valid arguments to A, and the type returned by A for these arguments is a subtype of the type returned by B.
(i.e. $f<:g ⟺ ∀x∈\text{dom}(g): \big(x∈\text{dom}(f) ∧ f(x) <: g(x) \big)$ )

Contra-variance in the parameters and co-variance in the return type follows immediately. This condition is satisfied by the example I gave.