如何强制评估来自其他模块的Python类型注解？

我之前也踩过类似的坑，尤其是用了from __future__ import annotations拆分模块后，get_type_hints()的行为确实会让人头疼。咱们一步步来解决这两个核心问题：

1. 获取函数定义模块的全局命名空间 #

问题的根源在于：当你在其他模块调用get_type_hints(func)时，它默认会使用当前调用模块的全局命名空间来评估注解字符串，而非函数定义所在模块的。这就导致跨模块的类型定义根本找不到。

解决方法很直接：通过函数的__module__属性拿到它所属的模块，再获取该模块的全局命名空间（也就是模块的__dict__），然后传给get_type_hints的globals参数。

修改你的params_of函数如下：

import sys
import inspect
from typing import Callable, Iterable, Tuple, Any, TypeAnnotation
from __future__ import annotations

def params_of(func: Callable) -> Iterable[Tuple[str, TypeAnnotation]]:
    # 获取函数定义所在的模块对象
    func_module = sys.modules[func.__module__]
    # 传递模块的全局命名空间给get_type_hints，确保能正确解析跨模块类型
    type_hints = get_type_hints(func, globals=func_module.__dict__)
    
    sig = inspect.signature(func)
    for param_name in sig.parameters:
        if param_name == 'return':
            continue
        yield (param_name, type_hints.get(param_name, Any))

这样get_type_hints就能在函数定义的模块上下文里评估注解字符串，跨模块的类型也能正确识别了。

2. 处理TYPE_CHECKING导致的运行时类型缺失 #

用if TYPE_CHECKING:导入的类型在运行时是不存在的，直接评估注解字符串会抛出NameError。这里有两种实用的解决思路：

思路一：给运行时添加类型占位符 #

在定义类型注解的模块里，给TYPE_CHECKING块补充运行时的占位符，这样评估注解时不会找不到名称：

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    # 类型检查器能看到真实类型
    from other_module import ComplexType
else:
    # 运行时用Any代替，或者定义一个空类占位
    ComplexType = Any

这种方法简单直接，既保留了类型检查的准确性，又避免了运行时错误。

思路二：捕获评估错误并降级处理 #

如果不想修改原模块的导入逻辑，可以在解析注解时捕获NameError，把找不到的类型降级为Any：

def params_of(func: Callable) -> Iterable[Tuple[str, TypeAnnotation]]:
    func_module = sys.modules[func.__module__]
    type_hints = {}
    sig = inspect.signature(func)
    
    try:
        # 先尝试正常解析
        type_hints = get_type_hints(func, globals=func_module.__dict__)
    except NameError:
        # 遇到找不到的类型，手动解析注解字符串并处理错误
        for param_name in sig.parameters:
            ann_str = func.__annotations__.get(param_name)
            if not ann_str:
                type_hints[param_name] = Any
                continue
            try:
                # 尝试用模块全局空间评估注解
                evaluated_type = eval(ann_str, func_module.__dict__)
                type_hints[param_name] = evaluated_type
            except NameError:
                # 类型不存在，降级为Any
                type_hints[param_name] = Any
    
    for param_name in sig.parameters:
        if param_name == 'return':
            continue
        yield (param_name, type_hints.get(param_name, Any))

⚠️ 注意：eval会执行字符串里的代码，所以只在你信任自己的注解字符串时使用这个方法，避免安全风险。

额外提示 #

如果你用的是Python 3.10+，typing.get_type_hints已经对跨模块注解的处理有了一些优化，但核心逻辑还是要确保传入正确的全局命名空间。另外，如果你需要处理更复杂的类型（比如泛型、前向引用），可以结合typing.get_origin和typing.get_args来进一步解析。

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