本文介绍如何编写一个支持类型提示的装饰器，在对函数参数进行运行时类型转换的同时，保留原始函数的类型签名，使静态类型检查器（如 mypy）能正确推断参数类型。
本文介绍如何编写一个支持类型提示的装饰器，在对函数参数进行运行时类型转换的同时，保留原始函数的类型签名，使静态类型检查器（如 mypy）能正确推断参数类型。
在 Python 3.9+ 中，为装饰器编写精确的类型提示是提升代码可维护性与 IDE 支持的关键。但常见误区是：使用 Callable[..., R] 作为返回类型会导致类型检查器丢失原始函数的参数结构（例如 test(x: int) -> int 被弱化为 (...) -> int），丧失类型安全性。
要解决这一问题，核心在于不改变装饰器返回函数的类型签名，而是让类型检查器“感知”到被装饰函数仍具有原始的、带类型注解的参数列表。这无法通过 ParamSpec 直接实现（因其适用于转发签名的装饰器，而本例需在运行时修改参数值，且不保证所有参数都可安全转换），而应采用更稳健的策略：保留原始函数的类型信息，并在装饰器内部显式处理类型转换逻辑，同时对外暴露原函数的签名。
以下是经过优化、类型安全且兼容主流类型检查器（mypy、pyright）的实现：
import inspect
from functools import wraps
from typing import Any, Callable, TypeVar, get_type_hints
R = TypeVar("R")
def coerce_arguments(func: Callable[..., R]) -> Callable[..., R]:
"""
装饰器：尝试将传入参数按其类型注解进行强制转换（如 str → int），
若转换失败则保留原始值。关键：返回类型严格等同于 func 的原始签名。
"""
@wraps(func)
def wrapper(*args: Any, **kwargs: Any) -> R:
# 获取函数参数名（按定义顺序）
varnames = func.__code__.co_varnames[:func.__code__.co_argcount]
# 获取类型提示（自动解析 forward references，支持复杂泛型）
type_hints = get_type_hints(func)
new_args = []
for i, name in enumerate(varnames):
if i < len(args):
value = args[i]
# 仅对有明确类型注解的参数尝试转换
param_type = type_hints.get(name, Any)
if param_type is not Any and param_type is not inspect.Parameter.empty:
try:
coerced_value = param_type(value)
new_args.append(coerced_value)
except (TypeError, ValueError, AttributeError):
# 转换失败时降级为原始值（避免静默崩溃）
new_args.append(value)
else:
new_args.append(value)
else:
break # 处理位置参数已尽
# 注意：此处未处理 *args/**kwargs 的动态参数（如 func(*a, x=1)），如需支持，应结合 inspect.signature 做完整绑定
return func(*new_args, **kwargs)
return wrapper
# 使用示例
@coerce_arguments
def test(x: int, y: str = "default") -> str:
return f"int={x}, str='{y}'"
# 静态类型检查器（如 mypy）将正确识别：
# test(42) # ✅ OK —— x: int, y: str
# test("42") # ✅ OK —— x 将被转为 int；调用签名仍是 (x: int, y: str) -> str
# test(x="hello") # ❌ Error: Argument "x" has incompatible type "str"; expected "int"✅ 关键设计要点说明：
立即学习“Python免费学习笔记（深入）”；
- 签名保真：装饰器返回类型为 Callable[..., R]，但 @wraps(func) 确保 wrapper.__annotations__、wrapper.__signature__ 完全继承自 func，因此类型检查器（如 mypy）仍依据原始函数的 def test(x: int) -> int: 进行校验；
- 安全转换：仅对存在有效类型注解（非 Any、非 inspect.Parameter.empty）的参数尝试构造，捕获常见异常（TypeError, ValueError, AttributeError），失败即回退，保障运行时鲁棒性；
- 类型提示工具链友好：使用 get_type_hints()（而非 inspect.signature(...).parameters[...].annotation）可正确解析字符串字面量注解（PEP 563）、from __future__ import annotations 及嵌套泛型，避免类型反射错误；
-
注意事项：
- 当前实现主要处理位置参数（*args）；若需支持 **kwargs 或 *args 动态参数，建议改用 inspect.signature().bind() + apply_defaults() 方案（如原始问题中所示），但需额外维护 bound_args.arguments 的类型映射；
- 不建议对 Callable, Union, Optional 等抽象类型直接调用构造器（如 Union[int, str]("1") 会失败），应配合专用转换逻辑或第三方库（如 pydantic）；
- 生产环境建议添加日志记录转换行为，便于调试隐式类型变更。
该方案在类型安全、运行时灵活性与代码简洁性之间取得了良好平衡，是构建可验证、可维护 Python 工具函数的推荐实践。
