Pylance and @overload of functions

[ClementPinard]

Hi, I have some question regarding the handling of @overload by pylance / pyright.

Consider the following example :

from typing import overload


@overload
def my_func(arg1: int, arg2: str = ...) -> None:
    pass


@overload
def my_func(arg1: str, arg2: str = ...) -> str:
    pass


def my_func(arg1: int | str, arg2: str = "default_value") -> None | str:
    """Function docstring"""
    print(arg2)
    if isinstance(arg1, int):
        return None
    else:
        return arg1


def my_second_func(b: int | str) -> None | str:
    my_value = my_func(b)
    return my_value


int_value = 0
my_value = my_func(int_value)
reveal_type(my_value)

First question : When I point the cursor to the list line, I get the right signature (the second overload) and the docstring from the function implementation, which is great ! However I don't get the default value of arg2. Adding the default argument to arg2 in overload signatures instead of simply ... does solve the issue, but I though you were expected to replace all default values with ... . Is this behaviour expected ?

Second question : I am in a situation where I have many different overloads, with lots of parameters, something similar to https://discuss.python.org/t/make-overload-less-verbose/38803 . Is it possible to put all these overloads in a dedicated file to improve readability ? I do believe that you can use a .pyi file but the popup does not seem to take it into account. I changed the snippet to fit in two files :

test.pyi

from typing import overload

@overload
def my_func(arg1: int, arg2: str = ...) -> None:
    pass

@overload
def my_func(arg1: str, arg2: str = ...) -> str:
    pass

@overload
def my_func(arg1: int | float, arg2: str = "default_value") -> None | float:
    pass

test.py

def my_func(arg1: int | str, arg2: str = "default_value") -> None | str:
    """Function docstring"""
    print(arg2)
    if isinstance(arg1, int):
        return None
    else:
        return arg1

int_value = 0
my_value = my_func(int_value)
reveal_type(my_value)

my_value type is inferred to be None | str and not None, so it seems pyright is ignoring my .pyi file !

If you have any insight on either of these issue, your help is much appreciated 🙏

[erictraut]

I though you were expected to replace all default values with ...

You may include default argument values in an overload signature if you'd like the value to be displayed in hover text and signature help. Default arguments are often replaced by ... in type stubs, but that's a convention more than a requirement. Type checkers and other static analysis tools will handle it fine if you include the actual value. Typeshed stubs are increasingly including the default argument value to improve language server support.

it seems pyright is ignoring my .pyi file

Stub files are stand-ins for a source file within a library. Stubs are typically written because the source file is untyped or because the module is written in a language other than Python. A type checker will use a stub in place of the source file when an import statement targets that source file. If you have a source file named test.py and a corresponding stub file named test.pyi, the type information in test.pyi will be used if you import test from another file. The type information in test.pyi cannot be used to type check test.py itself because it doesn't import itself. If your intent is to type check the code in your module test.py, you should include the type annotations (including overloads) within that file.

I am in a situation where I have many different overloads

This tends to happen when you write functions and methods that are highly polymorphic. If you have the option of changing your interface, you might consider ways to make it less polymorphic. This would reduce the need to write such complex overloads.

[ClementPinard]

Hi thanks for the detailed explanation.

However, for the default argument, it feels like unnecessary duplication to also add it to the overload. Shouldn't we be able to deduce it from the original function signature ? Maybe it's less simple than I think, it's a genuine question.