如何实现函数参数的关联类型提示，限定value_type与value的合法组合？

我有个函数，接收value和value_type两个参数，用来拼接GraphQL查询字符串（比如"endpoint(value_type: value) {...}"），需要分别使用这两个值。目前value_type标注为Literal["option1", "option2", "secret third option"]，value标注为Union[int, str]，但我想让这两个参数的类型绑定关联：

• 当value_type为"option1"时，value必须是str
• 当value_type为"option2"时，value必须是int
• 其他value_type对应的value类型也需要一一对应绑定

目前我用match/case加assert做运行时校验，但希望IDE在编码阶段就能提示类型错误，而且不想写大量文档，也不愿拆分成多个函数——除了字符串类型的value需要加引号适配GraphQL格式，其余代码完全一致。

用Python的**函数重载（typing.overload）**就能解决这个问题，不用拆分函数，还能让IDE识别参数的类型关联逻辑。

具体实现步骤： #

1. 导入overload、Literal、Union这些类型提示工具
2. 用@overload装饰器为每一组合法的参数组合定义专属的类型签名
3. 编写一个实际的函数实现，用宽泛的类型标注覆盖所有情况即可

代码示例： #

from typing import overload, Literal, Union

# 为每一组合法参数组合定义重载签名
@overload
def build_graphql_query(value_type: Literal["option1"], value: str) -> str:
    ...

@overload
def build_graphql_query(value_type: Literal["option2"], value: int) -> str:
    ...

@overload
def build_graphql_query(value_type: Literal["secret third option"], value: str) -> str:
    # 第三个选项对应的value类型可根据实际需求修改
    ...

# 实际执行的函数逻辑
def build_graphql_query(value_type: Literal["option1", "option2", "secret third option"], value: Union[int, str]) -> str:
    # 处理value格式：字符串加引号，数字直接转字符串
    formatted_value = f'"{value}"' if isinstance(value, str) else str(value)
    return f'endpoint({value_type}: {formatted_value}) {{...}}'

效果说明： #

• 当你传入value_type="option1"但给value传整数时，IDE会直接标红提示类型不匹配
• 运行时仍可保留原来的match/case+assert做兜底校验
• 函数逻辑只需编写一次，无需拆分成多个函数

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