如何为带inplace参数的Python函数添加正确类型提示？

要让类型检查器根据inplace参数的取值自动推断返回类型，你需要使用**函数重载（overload）**定义不同参数组合下的类型签名，替代模糊的Union[A, None]返回类型。具体实现如下：

代码示例 #

from typing import overload, TypeVar, Literal, Optional

# 定义泛型类型变量，匹配输入输出的类型
A = TypeVar("A")

# 重载1：明确inplace=True时返回None
@overload
def func(data: A, inplace: Literal[True]) -> None: ...

# 重载2：明确inplace=False（含默认值）时返回同类型副本
@overload
def func(data: A, inplace: Literal[False] = False) -> A: ...

# 实际函数实现
def func(data: A, inplace: bool = False) -> Optional[A]:
    if inplace:
        # 此处编写修改输入data的逻辑
        data.append(0)  # 示例操作，根据需求替换
        return None
    # 返回输入的副本
    return data.copy()

原理说明 #

• 函数重载通过@overload装饰器为同一个函数定义多个类型签名，类型检查器会根据调用时传入的inplace字面量值（True/False）自动匹配对应签名。
• 调用modified_data = func([1,2,3])时，类型检查器匹配第二个重载，推断返回类型为list[int]，此时调用modified_data.append(4)不会触发类型错误。
• 调用func([1,2,3], inplace=True)时，类型检查器匹配第一个重载，明确返回类型为None，若尝试对返回值调用方法，会直接提示类型错误。

这种方式符合Python类型提示最佳实践，能让mypy、pyright等工具准确识别不同场景下的返回类型，解决你遇到的问题。

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