如何为动态创建的Python类正确添加类型注解？

报错原因 #

静态类型检查器（如mypy、Pylance）要求类型注解必须是类型字面量（比如直接定义的类名），而RuntimeEntity是一个指向动态生成类的变量。在静态检查阶段，检查器无法将这个变量识别为合法的类型表达式，因此抛出"Variable not allowed in type expression"或类似错误。

正确的类型注解方式 #

方法1：使用TypeAlias（Python 3.10+） #

将RuntimeEntity标注为类型别名，明确告诉检查器这是一个类型：

from typing import Type, TypeAlias

class BaseEntity:
    id: str

def make_new_entity(name: str, attrs: dict) -> Type[BaseEntity]:
    return type("RuntimeEntity", (BaseEntity,), attrs)

# 标注为类型别名
RuntimeEntity: TypeAlias = make_new_entity("RuntimeEntity", {"id": "entity.RuntimeEntity"})

class Foo:
    entity_instances: list[RuntimeEntity]  # 类型检查器可正常识别

方法2：使用__future__.annotations（Python 3.7+） #

通过导入__future__.annotations，让注解以字符串形式延迟到运行时解析，避免静态检查阶段的报错：

from __future__ import annotations
from typing import Type

class BaseEntity:
    id: str

def make_new_entity(name: str, attrs: dict) -> Type[BaseEntity]:
    return type("RuntimeEntity", (BaseEntity,), attrs)

RuntimeEntity: Type[BaseEntity] = make_new_entity("RuntimeEntity", {"id": "entity.RuntimeEntity"})

class Foo:
    entity_instances: list[RuntimeEntity]
    other_entity_instances: list[RuntimeEntity]  # 无需手动加引号

方法3：手动使用字符串注解（兼容旧版本Python） #

如果无法使用上述特性，可以直接用字符串包裹类型名称，让检查器跳过静态解析：

from typing import Type

class BaseEntity:
    id: str

def make_new_entity(name: str, attrs: dict) -> Type[BaseEntity]:
    return type("RuntimeEntity", (BaseEntity,), attrs)

RuntimeEntity: Type[BaseEntity] = make_new_entity("RuntimeEntity", {"id": "entity.RuntimeEntity"})

class Foo:
    entity_instances: list["RuntimeEntity"]
    other_entity_instances: list["RuntimeEntity"]

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