如何为返回动态导入类的Python函数编写合规类型注解？

针对你遇到的场景，这里有两种能同时让Pyright、Ruff、mypy都满意的写法，既不用Any作为返回类型，也无需添加会触发工具报错的忽略注释：

方法一：结合TYPE_CHECKING与条件导入 #

借助typing.TYPE_CHECKING常量（仅在类型检查阶段为True，运行时为False），我们可以在类型检查时尝试导入可选依赖的类，未安装依赖时用Any兜底，避免检查工具报错：

from typing import TYPE_CHECKING, Any

if TYPE_CHECKING:
    try:
        from optional_dependency import SomeClass
    except ImportError:
        # 类型检查环境未装依赖时，用Any替代类型，避免报错
        SomeClass = Any

def my_function() -> SomeClass:
    from optional_dependency import SomeClass
    return SomeClass()

效果说明 #

• 依赖已安装时：类型检查工具能识别SomeClass的真实类型，返回类型标注准确，无报错。
• 依赖未安装时：类型检查阶段SomeClass被替换为Any，不会触发工具报错；运行时函数内的导入会正常抛出ImportError（符合你的预期）。

方法二：配合延迟注解（Python 3.7+） #

如果你的Python版本在3.7及以上，可以启用延迟注解特性，进一步简化写法：

from __future__ import annotations
from typing import TYPE_CHECKING, Any

if TYPE_CHECKING:
    try:
        from optional_dependency import SomeClass
    except ImportError:
        SomeClass = Any

def my_function() -> SomeClass:
    from optional_dependency import SomeClass
    return SomeClass()

from __future__ import annotations会让Python延迟解析函数注解，类型检查工具依然能正常识别SomeClass的定义，同时避免运行时的注解解析问题。

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