如何为带可选参数的Python函数按字面量类型添加类型注解？

要让类型检查器能识别不同路由名称对应的参数要求，你可以用typing.overload定义多个函数签名，分别对应每种name的参数规则。这样类型检查器会根据调用时传入的name字面量，自动校验后续参数是否合规。

完整代码示例 #

from typing import Literal, overload

# 重载1：name为"main"时，无额外参数
@overload
def route(name: Literal["main"]) -> None: ...

# 重载2：name为"edit"时，必须传入一个data参数（这里假设data是int类型，可根据实际调整）
@overload
def route(name: Literal["edit"], data: int) -> None: ...

# 实际实现函数
def route(name: Literal["main", "edit"], *args) -> None:
    match name:
        case "main":
            print("Main screen")
        case "edit":
            if not args:
                raise ValueError("No item id provided for editing.")
            print(f"Editing item id: {args[0]}")
        case _:
            raise ValueError(f"Invalid route name: {name}")

route("main") # 合法，符合重载1
route("edit", 12) # 合法，符合重载2
route("edit")  # 类型检查器会报错：缺少必填的data参数

说明 #

• 重载签名仅用于给类型检查器提供规则，无需实现逻辑，用...占位即可；
• 实际实现函数的参数注解可以保持宽泛（比如*args），但重载会约束外部调用的参数格式；
• 如果data的类型不固定，可将重载2的data改为Any或你需要的联合类型（比如int | str）。

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