如何让Python懒加载器兼容静态类型检查？

问题背景 #

我编写了一个简易的懒导入工具，用法如下：

from loader import Lazy

httpx = Lazy("httpx")  # 此时`httpx`模块尚未加载

httpx.get("https://google.ca/")  # 加载`httpx`模块并调用`.get()`

工具的实现代码：

from functools import cached_property
from importlib import import_module
from typing import Any, TYPE_CHECKING


class Lazy:
    def __init__(self, name: str) -> None:
        self._name = name

    def __getattr__(self, item: str) -> Any:
        return getattr(self._module, item)

    @cached_property
    def _module(self):
        return import_module(self._name)

这个工具能正常运行，但Mypy、PyCharm等静态类型检查器会把懒导入的httpx视为Any类型，导致错误代码无法被检测到：

from loader import Lazy

httpx = Lazy("httpx")
httpx.get(42)  # 参数类型错误不会被标记
httpx.woot  # 不存在的属性不会被提示

同时PyCharm也无法提供方法名或参数的自动补全，增加了开发难度。我希望懒加载器能在静态检查时被识别为实际导入的模块，但不确定是否可行——毕竟项目规模极大，懒加载对本地开发启动速度提升明显。

可行解决方案 #

方案1：利用TYPE_CHECKING条件导入+类型注解 #

在使用懒导入的地方，给变量加上实际模块的类型注解，同时在类型检查阶段导入真实模块：

from typing import TYPE_CHECKING
from loader import Lazy

if TYPE_CHECKING:
    import httpx
else:
    httpx = Lazy("httpx")

这样静态检查器会认为httpx是真实的模块类型，能正常提供补全和类型检查，而运行时依然使用懒加载逻辑。缺点是每个懒导入都要写这段代码，略显繁琐，但兼容性最好。

方案2：将Lazy改为泛型类 #

修改Lazy的实现，让它支持泛型，这样可以在定义时指定目标模块的类型：

from functools import cached_property
from importlib import import_module
from typing import Any, TypeVar, Generic, TYPE_CHECKING

T = TypeVar("T")

class Lazy(Generic[T]):
    def __init__(self, name: str) -> None:
        self._name = name

    def __getattr__(self, item: str) -> Any:
        return getattr(self._module, item)

    @cached_property
    def _module(self) -> T:
        return import_module(self._name)  # type: ignore

使用时：

from typing import TYPE_CHECKING
from loader import Lazy

if TYPE_CHECKING:
    import httpx

httpx: httpx = Lazy("httpx")  # 指定类型为httpx模块

这种方式能让类型检查器识别到变量的真实类型，同时保持懒加载的运行逻辑，比方案1更简洁一些，不过需要修改Lazy类的实现。

方案3：自定义Mypy插件（仅针对Mypy） #

如果主要使用Mypy做类型检查，可以编写一个简单的插件，让Mypy识别Lazy("module_name")的返回类型为对应的模块类型。这种方式需要了解Mypy插件的开发机制，优点是无需修改业务代码，但只针对Mypy生效，PyCharm无法识别。

总结 #

如果要兼顾所有静态检查工具和IDE的自动补全，方案1是最稳妥的选择；如果愿意修改懒加载工具的实现，方案2能减少业务代码的重复；如果只关注Mypy的检查效果，可以尝试方案3。这些方案都能在保持懒加载提升启动速度的同时，解决类型检查和自动补全的问题。

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