Python中不使用子类化实现类属性的类型收窄（TypeGuard）

问题背景 #

当Python类（如dataclass、pydantic、attrs、Django模型等）包含Union[类型, None]的属性时，我们希望通过自定义校验函数告知类型检查器：部分属性已完成类型收窄。但子类化的实现方式存在诸多问题：

• 引入大量重复代码
• 部分数据类库对子类化有额外限制
• 元类或__subclasses__机制可能会特殊处理所有子类（比如自动为数据类创建数据库表）

现有子类化的实现示例：

import dataclasses
from typing import TypeGuard

@dataclasses.dataclass
class SomeDataClass:
    state: tuple[int, int] | None
    name: str
    # 假设还有更多属性

class SomeDataClassWithSetState(SomeDataClass):
    state: tuple[int, int]

def complex_check(data: SomeDataClass) -> TypeGuard[SomeDataClassWithSetState]:
    # 实际为复杂校验，此处简化为：
    return data.state is not None and data.name.startswith("SPECIAL")

def get_sum(data: SomeDataClass) -> int:
    if complex_check(data):
        return data.state[0] + data.state[1]
    return 0

解决方案 #

1. 使用Protocol协议（推荐） #

利用Protocol定义一个仅包含收窄后属性的协议，原类会隐式实现该协议，类型检查器可直接识别校验后的类型：

import dataclasses
from typing import TypeGuard, Protocol

class HasValidState(Protocol):
    state: tuple[int, int]
    name: str

@dataclasses.dataclass
class SomeDataClass:
    state: tuple[int, int] | None
    name: str

def complex_check(data: SomeDataClass) -> TypeGuard[HasValidState]:
    return data.state is not None and data.name.startswith("SPECIAL")

def get_sum(data: SomeDataClass) -> int:
    if complex_check(data):
        return data.state[0] + data.state[1]  # 类型检查器会识别state为非None类型
    return 0

该方案优势：

• 无需创建子类，规避子类化带来的所有问题
• Protocol仅作用于类型检查阶段，不影响运行时逻辑
• 适配所有类类型（dataclass、pydantic、Django模型等）

2. 使用TypedDict配合TypeGuard（适用于字典场景） #

定义与原类结构匹配的TypedDict，收窄目标属性类型，校验后可转换为字典使用：

import dataclasses
from typing import TypeGuard, TypedDict

@dataclasses.dataclass
class SomeDataClass:
    state: tuple[int, int] | None
    name: str

class SomeDataClassWithSetState(TypedDict):
    state: tuple[int, int]
    name: str

def complex_check(data: SomeDataClass) -> TypeGuard[SomeDataClassWithSetState]:
    return data.state is not None and data.name.startswith("SPECIAL")

def get_sum(data: SomeDataClass) -> int:
    if complex_check(data):
        data_dict = dataclasses.asdict(data)
        return data_dict["state"][0] + data_dict["state"][1]
    return 0

3. 使用cast强制类型转换（简单但严谨性不足） #

校验通过后直接用cast强制转换属性类型，依赖开发者保证校验逻辑的正确性，类型检查器无法验证：

import dataclasses
from typing import cast

@dataclasses.dataclass
class SomeDataClass:
    state: tuple[int, int] | None
    name: str

def complex_check(data: SomeDataClass) -> bool:
    return data.state is not None and data.name.startswith("SPECIAL")

def get_sum(data: SomeDataClass) -> int:
    if complex_check(data):
        state = cast(tuple[int, int], data.state)
        return state[0] + state[1]
    return 0

总结 #

优先选择Protocol方案，既能满足类型检查需求，又彻底避免子类化的弊端；TypedDict适合处理字典形式的数据；cast可作为简单场景下的兜底方案。

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