如何解决Mypy无法识别间接Optional检查的类型收窄问题

问题本质 #

mypy的类型收窄默认是作用域内生效的，不会跨方法追溯判断逻辑：方法内部写的self.sequence_length is None判断仅能在当前方法内收窄self.sequence_length的类型，当你把这段判断封装到is_empty()方法中时，外部调用方只能拿到bool类型的返回值，mypy不会解析is_empty()内部的实现来推导实例属性的类型状态，因此会报类型不兼容错误。

最优低开销实现 #

不需要重构类层级拆分空/非空两个实现子类，使用TypeGuard结合仅类型检查阶段生效的私有类型标注即可实现统一空值检查的类型收窄，运行时无额外开销。

实现代码 #

from typing import Optional, TYPE_CHECKING
# Python 3.10及以上版本可直接从typing导入TypeGuard，低版本从typing_extensions导入
from typing_extensions import TypeGuard


class ItemSequence:
    def __init__(self, sequence_length: Optional[int]) -> None:
        self.sequence_length = sequence_length

    def is_empty(self) -> bool:
        return self.sequence_length is None

    def is_non_empty(self) -> TypeGuard["_NonEmptyItemSequence"]:
        """类型守卫：返回True时实例所有Optional成员均为非空值"""
        return self.sequence_length is not None

    def add_to_length_with_indirect_check(self, x: int) -> Optional[int]:
        if not self.is_non_empty():
            return None
        # 此处mypy可自动识别self.sequence_length为int类型，无报错
        return self.sequence_length + x


if TYPE_CHECKING:
    # 该类仅用于类型标注，运行时不会实际定义
    class _NonEmptyItemSequence(ItemSequence):
        sequence_length: int

方案优势 #

• 无运行时额外开销：_NonEmptyItemSequence仅在类型检查阶段存在，不影响实际运行逻辑
• 复用性强：如果类中有多个和空状态绑定的Optional成员，只需要在_NonEmptyItemSequence中补充对应非Optional类型标注，所有调用is_non_empty()判断的位置都能自动获得所有成员的类型收窄效果，不需要重复编写单个属性的None判断
• 改动量极小：不需要调整现有类的业务逻辑，仅需新增一个类型守卫方法和一段类型检查阶段的定义即可。

其他可选方案说明 #

• 断言辅助：如果不想新增is_non_empty方法，可以在if self.is_empty(): return None之后添加assert self.sequence_length is not None手动触发类型收窄，但这种方式需要在每个业务方法中重复编写断言，复用性差
• 类拆分方案：将ItemSequence定义为抽象类，派生空/非空两个子类的方案类型严谨性最高，但如果两类的业务逻辑几乎一致、仅存在属性是否为空的差异，实现成本和收益不匹配
• 外层Optional方案：禁止空实例存在、用Optional[ItemSequence]表示空序列的方案，会将空判断逻辑散落到所有使用该类的位置，大幅增加外围代码的复杂度，不推荐使用。

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