Python参数化typing.Annotated类型：解决Pyright类型表达式报错

需求是创建一系列基于同一底层类型、绑定不同取值约束（优先用枚举）且附带元数据的typing.Annotated类型，手动逐个定义可行，但希望参数化实现更简洁。

编写的示例代码可运行，但Pyright报错：

• 将CType作为animal的类型注解时，报Variable not allowed in type expression (reportInvalidTypeForm)
• 内联ConstrainedType()调用时，报Call expression not allowed in type expression (reportInvalidTypeForm)

示例代码：

from dataclasses import dataclass
from enum import Enum
from typing import Annotated

from annotated_types import Predicate

class WildAnimals(Enum):
    LION = 'lion'
    BEAR = 'bear'

class PetAnimals(Enum):
    CAT = 'cat'
    DOG = 'dog'

def ConstrainedType(allowed_values: type[Enum]):
    return Annotated[
        str,
        Predicate(lambda val: val in (m.value for m in allowed_values)),
        f'Allowed: {list(allowed_values)}',
    ]

def ConstrainedContainer(allowed_values: type[Enum]):

    CType = ConstrainedType(allowed_values)

    @dataclass
    class Container:
        # error: Variable not allowed in type expression (reportInvalidTypeForm)
        animal: CType
        count: int

    return Container

PetCarrier = ConstrainedContainer(PetAnimals)
WildCarrier = ConstrainedContainer(WildAnimals)

疑问：是否需要使用TypeVar或Generic？如何创建可被类型检查器识别的非“变量式”参数化类型？

问题根源 #

类型检查器（如Pyright）要求类型注解必须是静态可解析的类型表达式，不能是运行时变量或函数调用——因为类型检查在代码执行前进行，无法解析动态生成的类型变量。

正确实现方式：泛型+Annotated元数据约束 #

要让类型检查器识别参数化的约束类型，需要结合TypeVar和Generic定义泛型数据类，同时将约束逻辑和元数据通过Annotated绑定，再针对不同枚举创建具体的类型别名。

修改后的代码：

from dataclasses import dataclass
from enum import Enum
from typing import Annotated, TypeVar, Generic

from annotated_types import Predicate

# 定义泛型变量，限定仅能绑定Enum子类
T = TypeVar('T', bound=Enum)

class WildAnimals(Enum):
    LION = 'lion'
    BEAR = 'bear'

class PetAnimals(Enum):
    CAT = 'cat'
    DOG = 'dog'

# 泛型数据类，通过TypeVar关联具体枚举类型
@dataclass
class ConstrainedContainer(Generic[T]):
    # 用Annotated绑定底层类型、约束逻辑和元数据，泛型变量T会被静态解析
    animal: Annotated[
        str,
        Predicate(lambda val: val in (m.value for m in T)),
        lambda: f'Allowed: {list(T)}'
    ]
    count: int

# 创建绑定具体枚举的类型别名
PetCarrier = ConstrainedContainer[PetAnimals]
WildCarrier = ConstrainedContainer[WildAnimals]

关键说明 #

1. TypeVar与Generic：通过bound=Enum限定泛型变量只能接收枚举子类，Generic[T]让ConstrainedContainer成为泛型类，类型检查器能识别不同枚举绑定的具体类型。
2. 静态可解析的Annotated：用泛型变量T替代动态传入的枚举参数，类型检查器在静态分析时就能关联到具体枚举，不会报动态表达式错误。
3. 元数据延迟计算：用lambda包裹元文本生成逻辑，避免在泛型类定义阶段就执行list(T)（此时T尚未绑定具体枚举）。

额外优化：提取通用约束类型 #

如果需要复用带约束的Annotated类型，可以单独定义泛型类型别名：

from typing import TypeAlias

# 泛型约束类型别名，可在多个地方复用
ConstrainedStr: TypeAlias = Annotated[
    str,
    Predicate(lambda val: val in (m.value for m in T)),
    lambda: f'Allowed: {list(T)}'
]

@dataclass
class ConstrainedContainer(Generic[T]):
    animal: ConstrainedStr
    count: int

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