Display of overloaded definitions

[dhruvmanila]

Currently, an overloaded definition is displayed using the following format:

Overload[<signature of overload 1>, <signature of overload 2>, ...]

For example:

Overload[() -> None, (x: int) -> int]

The main use cases are reveal_type, error messages (?), hover implementation in the language server.

This issue is to keep track of whether we want to improve the display and if so then how?

There was some discussion over at astral-sh/ruff#17294 (comment).

[erictraut]

Related to the question about how overloads should be displayed is the question about when they should be displayed.

In pyright, we try to avoid showing overloads when the user hovers over a call expression. In that context, the language server can typically tell which overload signature matches the supplied arguments, so it's possible to display only the overload that applies in that context. We added this behavior in response to strong user feedback that seeing all of the overloads was often overwhelming. You might want to consider doing something similar in ty.

There will still be situations (e.g. outside of a call expression or in cases where the overload matching algorithm matches more than one overload signature) where it will still be necessary to display multiple overload signatures, but those cases should be relatively rare.

[InSyncWithFoo]

Regarding #19275, here's my proposal:

• For bound methods: The format for a single overload is the same as that of a single-signature bound method. A note is added to help avoiding user confusion (compare with the existing bound method C[int].f(v: str) -> str). It can be either invalid syntax ((bound method)) or a comment (# bound method); I have no strong opinion on this.

   (bound method)
   @overload
   def C[int].f(v: str) -> str: ...
   @overload
   def C[int].f(v: int) -> int: ...

• For literal functions/unbound methods: The format for a single overload is the same as that of a single-signature function/unbound method.

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

• For (anonymous) callables: The format for a single overload is similar to that of a single-signature function/unbound method, but the name is replaced with <anonymous>, which is emphatically not a valid identifier.

   @overload
   def <anonymous>(v: str) -> str: ...
   @overload
   def <anonymous>(v: int) -> int: ...

Note that, since this "prettified" format is multiline, it is only used in hover popups and not type checker messages. Here's how an union would be displayed if this format were to be used indiscriminately:

int | Literal['foo'] | @overload
def f(v: str) -> str: ...
@overload
def f(v: int) -> int: ... | type[C]

One important thing to note is that the : ... parts, while do not carry useful information on their own, might be necessary for highlighters to work correctly. Take GitHub's highlighter for an example:

• With bodies: Everything is highlighted nicely.

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

• Without bodies: The second @overload and def pair are not highlighted.

   @overload
   def f(v: str) -> str
   @overload
   def f(v: int) -> int

This format is largely influenced by Pyright's, but with @overloads added to serve as some kind of visual separator and indicator. No strong opinion on that either.

[MichaReiser]

Thanks for writing this up. I'll try to take a look on Monday.

To clarify my understanding, is this what pyright would show:

def f(v: str) -> str
def f(v: int) -> int

[InSyncWithFoo]

@MichaReiser Pyright would show something like this, to be exact:

(function)
def f(v: str) -> str: ...
def f(v: int) -> int: ...

[MichaReiser]

I like the more compact representation and, for now, i'd probably defual to whatever pylance does unless we have good reasons not to,

[InSyncWithFoo]

@MichaReiser In that case, here's a snippet for reference (playground):

class C[T]:
    def __init__(self, v: T, /) -> None: ...

    @overload
    def f(self, v: int) -> int: ...
    @overload
    def f(self, v: str) -> str: ...

    def f(self, v: int | str) -> int | str: ...


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

def f(v: int | str) -> int | str: ...


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

    def f(v: int | str) -> int | str: ...

    return f

_ = C(0).f
# BoundMethod[C[int], Overload[(self: Self@C, v: int) -> int, (self: Self@C, v: str) -> str]]
#
# (method)
# def f(v: int) -> int: ...
# def f(v: str) -> str: ...

_ = C.f
# Overload[[T](self: C[T], v: int) -> int, [T](self: C[T], v: str) -> str]
#
# (method)
# def f(self: C[Unknown], v: int) -> int: ...
# def f(self: C[Unknown], v: str) -> str: ...

_ = C[int].f
# Overload[[T](self: C[T], v: int) -> int, [T](self: C[T], v: str) -> str]
#
# (method)
# def f(self: C[int], v: int) -> int: ...
# def f(self: C[int], v: str) -> str: ...

_ = f
# Overload[(v: int) -> int, (v: str) -> str]
#
# (function)
# def f(v: int) -> int: ...
# def f(v: str) -> str: ...

_ = g()
# Overload[(v: int) -> int, (v: str) -> str]
#
# (variable)
# def f(v: int) -> int: ...
# def f(v: str) -> str: ...

As you can see, Pyright doesn't use the notation C[...].f to denote a bound method like ty would. It also doesn't have an "anonymous" overloaded callable type (or at least I couldn't find out how to make one). Would you mind expanding on that?

[carljm]

Here's an example of an anonymous overloaded callable type in pyright

[InSyncWithFoo]

@carljm That one still has a name: method.