如何为动态赋值属性的Python类添加类型注解以支持类型推断？

针对你实现的延迟导入注册表，有几种可行的方法让类型检查器（比如mypy、pyright）推断出read_csv这类动态导入属性的类型，核心思路是给静态类型检查器补充缺失的类型信息，同时保留运行时的延迟导入逻辑。

方案一：使用__getattr__ + @overload + TYPE_CHECKING #

原代码中的__getattribute__会拦截所有属性访问，不利于类型推断。改用__getattr__（仅在属性不存在时触发），配合@overload声明属性类型，同时利用TYPE_CHECKING常量在类型检查阶段导入真实类型，避免运行时提前加载模块：

from typing import TYPE_CHECKING, overload, Any

# 仅在类型检查时导入pandas的read_csv类型，运行时不执行
if TYPE_CHECKING:
    from pandas.io.parsers import read_csv as _read_csv_type


class _ModuleRegistry:
    _modules: dict[str, str] = {}

    def defer_import(self, import_statement: str, import_name: str) -> None:
        self._modules[import_name] = import_statement

    def __getattr__(self, name: str) -> Any:
        import_statement = self._modules.get(name)
        if import_statement:
            exec(import_statement, locals())
            attr = locals()[name]
            setattr(self, name, attr)
            return attr
        raise AttributeError(f"'_ModuleRegistry' object has no attribute '{name}'")

    # 为类型检查器声明read_csv的具体类型
    @overload
    def read_csv(self) -> _read_csv_type: ...


registry = _ModuleRegistry()
registry.defer_import("from pandas import read_csv", "read_csv")

# 现在类型检查器会识别registry.read_csv为pandas的read_csv函数类型
print(registry.read_csv)

原理说明 #

• TYPE_CHECKING是一个运行时为False的常量，因此if TYPE_CHECKING块内的代码不会被执行，不会破坏延迟导入的逻辑。
• @overload装饰器给类型检查器提供了静态的类型声明，让它知道registry.read_csv的真实类型，而运行时的属性获取逻辑依然由__getattr__处理。

方案二：使用Protocol协议标注注册表类型 #

如果你需要给多个动态导入的属性统一做类型声明，可以定义一个Protocol协议，然后将注册表实例标注为该协议类型：

from typing import Protocol, TYPE_CHECKING

if TYPE_CHECKING:
    from pandas.io.parsers import read_csv as _read_csv_type


# 定义包含read_csv属性的协议
class DataToolRegistry(Protocol):
    read_csv: _read_csv_type


class _ModuleRegistry:
    _modules: dict[str, str] = {}

    def defer_import(self, import_statement: str, import_name: str) -> None:
        self._modules[import_name] = import_statement

    def __getattr__(self, name: str) -> Any:
        import_statement = self._modules.get(name)
        if import_statement:
            exec(import_statement, locals())
            attr = locals()[name]
            setattr(self, name, attr)
            return attr
        raise AttributeError(f"'_ModuleRegistry' object has no attribute '{name}'")


# 将注册表实例标注为DataToolProtocol类型
registry: DataToolRegistry = _ModuleRegistry()
registry.defer_import("from pandas import read_csv", "read_csv")

# 类型检查器会识别registry.read_csv的类型
print(registry.read_csv)

原理说明 #

• Protocol定义了一个接口契约，类型检查器会验证实例是否符合该契约的属性类型，这里我们通过静态标注让它认为registry拥有read_csv属性，且类型为pandas的read_csv函数。
• 运行时依然保持延迟导入的逻辑，不会提前加载pandas模块。

注意事项 #

• 避免使用__getattribute__拦截所有属性访问，它会干扰类型检查器对类属性的正常识别，改用__getattr__更安全。
• 如果需要支持多个动态导入的属性，只需在@overload或Protocol中添加对应的属性声明即可。

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