VS Code函数参数含默认值时选择错误重载的问题排查

你的重载定义存在顺序和默认值设置问题，并非VS Code/Pylance等工具的bug。

问题原因 #

类型检查器（如Pylance）会从上到下依次匹配重载定义。你原代码中的第一个重载：

@typing.overload
def fn(val: int, to_none: typing.Literal[True] = ...) -> None: ...

这里的= ...表示to_none参数可以省略（使用默认值），当你调用fn(7)时，类型检查器会优先匹配这个重载，导致z被错误推断为None类型，而非预期的float。

修正方案 #

调整重载结构，去掉多余的第三个重载，同时让带Literal[True]的重载必须显式传参，带Literal[False]的重载保留默认值：

import typing

@typing.overload
def fn(val: int, to_none: typing.Literal[True]) -> None: ...

@typing.overload
def fn(val: int, to_none: typing.Literal[False] = ...) -> float: ...

def fn(val: int, to_none: bool = False) -> float | None:
    return None if to_none else float(val)

x = fn(5, to_none=True)  # 正确推断为 None
y = fn(6, to_none=False) # 正确推断为 float
z = fn(7)                # 正确推断为 float

原理说明 #

• 第一个重载仅匹配**显式传入to_none=True**的情况，无默认值，不会干扰无参调用。
• 第二个重载匹配**显式传入to_none=False或省略该参数（使用默认值False）**的情况，返回float类型。
• 实现体的返回类型float | None覆盖了所有可能的返回情况，符合类型注解规范。

内容的提问来源于stack exchange，提问作者chrsmrrtt