如何让Pylance识别动态定义类的type annotation且不关闭类型检查

Pylance 属于静态类型检查工具，不会执行运行时的元类__new__逻辑，因此动态注入的类属性和注解无法被识别，必须提供显式的静态类型提示才能解决报错，可行方案如下：

方案1：使用存根文件（.pyi）（最通用，无运行时侵入） #

在你存放 settings 类的模块同目录下，创建和模块同名的 .pyi 存根文件，比如你的代码写在 config.py 里，就新建 config.pyi，内容如下：

from typing import NoReturn

class settings:
    # 和 default 模块的配置字段保持一致，逐一添加类型注解
    DEBUG: bool
    SECRET_KEY: str
    # 其他配置字段...

    def __call__(self, *args, **kwargs) -> NoReturn: ...

Pylance 会优先读取存根文件的类型定义，既不会触发类型报错，也能获得完整的属性补全能力。

方案2：用 TypedDict + cast 做静态类型转换（维护成本低） #

首先在 default.py 中定义和配置字段完全匹配的 TypedDict：

# default.py 新增内容
from typing import TypedDict

class DefaultSettings(TypedDict):
    DEBUG: bool
    SECRET_KEY: str
    # 所有配置字段逐一声明注解

# 原有模块级配置保持不变
DEBUG = False
SECRET_KEY = "xxx"

然后在定义 settings 类的文件末尾，用 cast 做静态类型转换（cast 仅对静态检查生效，运行时无任何开销）：

from typing import cast
from .default import DefaultSettings

# 原有元类、settings 类定义保持不变
class settings(metaclass=settings_meta, settings=default):
    ...

# 新增这一行做静态类型转换
settings = cast(type[DefaultSettings], settings)

转换后 Pylance 会把 settings 类识别为 DefaultSettings 类型，自动获得所有配置字段的类型提示。

方案3：静态检查阶段内联声明属性（适合配置量少的场景） #

如果不想额外维护 TypedDict 或存根，也可以利用 TYPE_CHECKING 常量，在静态检查阶段给 settings 类加属性声明：

from typing import TYPE_CHECKING

class settings(metaclass=settings_meta, settings=default):
    if TYPE_CHECKING:
        # 仅静态检查阶段生效，运行时完全忽略
        DEBUG: bool
        SECRET_KEY: str
        # 其他配置字段逐一声明

该方案不需要改动其他文件，直接在现有类中添加静态声明即可。

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