如何让Python类型检查工具正确识别「类型转换装饰器」？

问题背景 #

需要实现一个Python装饰器，自动将适配类型的参数转换为函数注解指定的目标类型（例如将str转为Palindrome），外部调用时可直接传入适配类型，函数内部无需处理转换逻辑，同时要让VSCode/Pylance等工具能正确进行类型检查。

解决方案 #

1. 核心类型定义 #

利用ParamSpec和TypeVar处理泛型函数签名，确保装饰器的类型注解能被类型检查工具识别：

from typing import Callable, ParamSpec, TypeVar, cast

# 定义参数规范和返回值类型变量
P = ParamSpec("P")
R = TypeVar("R")
# 用于标记装饰器的输入参数类型
InP = ParamSpec("InP")

2. 通用装饰器实现 #

这个装饰器会读取函数的类型注解，自动将传入的适配类型参数转换为目标类型，同时通过cast解决类型检查的匹配问题：

def auto_convert(func: Callable[P, R]) -> Callable[InP, R]:
    """自动将参数转换为函数注解指定的目标类型"""
    def wrapper(*args: InP.args, **kwargs: InP.kwargs) -> R:
        # 获取函数的参数-类型映射（排除返回值注解）
        param_types = {k: v for k, v in func.__annotations__.items() if k != "return"}
        # 获取函数的位置参数名称列表
        param_names = list(func.__code__.co_varnames[:func.__code__.co_argcount])

        # 处理位置参数转换
        new_args = []
        for idx, arg in enumerate(args):
            param_name = param_names[idx]
            target_type = param_types.get(param_name)
            if target_type and not isinstance(arg, target_type):
                # 尝试转换类型，若失败则抛出原异常
                arg = target_type(arg)
            new_args.append(arg)

        # 处理关键字参数转换
        new_kwargs = {}
        for key, arg in kwargs.items():
            target_type = param_types.get(key)
            if target_type and not isinstance(arg, target_type):
                arg = target_type(arg)
            new_kwargs[key] = arg

        # 通过cast告知类型检查器：转换后的参数符合函数的预期类型
        return cast(Callable[InP, R], func)(*new_args, **new_kwargs)
    return wrapper

3. 测试示例 #

结合你提供的Palindrome类验证功能：

class Palindrome(str):
    def __new__(cls, value: str) -> "Palindrome":
        if value == value[::-1]:
            return super().__new__(cls, value)
        raise ValueError(f"{value!r} 不是回文字符串")

    def is_even(self) -> bool:
        return len(self) % 2 == 0

@auto_convert
def do_something(palindrome: Palindrome, text: str) -> None:
    print(type(palindrome), palindrome, palindrome.is_even())
    print(type(text), text)

# 测试用例1：传入目标类型
do_something(Palindrome("aibohphobia"), "aibohphobia")
# 输出：
# <class '__main__.Palindrome'> aibohphobia False
# <class 'str'> aibohphobia

# 测试用例2：传入适配类型（类型检查通过，自动转换）
do_something("aibohphobia", "aibohphobia")
# 输出同上

# 测试用例3：传入无效的目标类型实例（类型检查通过，运行时抛错）
do_something(Palindrome("not-a-palindrome"), "aibohphobia")
# 运行时抛出ValueError

# 测试用例4：传入无效的适配类型（类型检查通过，运行时抛错）
do_something("not-a-palindrome", "aibohphobia")
# 运行时抛出ValueError

关键优势 #

• 类型检查兼容：VSCode/Pylance能识别装饰后的函数可以接受适配类型参数，不会报类型错误。
• 无type: ignore：通过cast明确告知类型检查器参数已完成转换，避免忽略类型提示。
• 通用性：不依赖具体类型，任何支持从适配类型构造的目标类型都能使用（比如str转pathlib.Path、int转float等）。
• 全参数支持：同时处理位置参数和关键字参数的转换。

注意事项 #

• 目标类型必须支持从适配类型的构造逻辑（即目标类型的__init__或__new__能接受适配类型作为参数）。
• 类型系统无法检测运行时的转换合法性（比如非回文字符串转Palindrome），这类错误需要在运行时捕获处理。

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