Mypy报错Optional类型属性缺失：索引遍历下的类型推断问题

我有一个数据类，其成员是另一个类的对象列表，该类包含类型为Optional[CustomType]的成员。我需要仅在该成员不为None时调用CustomType类的方法，但即便做了显式检查，mypy仍报错说CustomType | None联合类型中的None项缺少对应属性。

用str作为CustomType的示例复现代码如下：

from dataclasses import dataclass
from typing import Optional


@dataclass(frozen=True)
class Sample:
    tag: Optional[str] = None


@dataclass(frozen=True)
class Container:
    samples: list[Sample]


if __name__ == "__main__":
    containers: list[Container] = []
    tags: list[str] = []

    for container in containers:
        for index in range(len(container.samples)):
            if container.samples[index].tag is not None:
                tags.append(container.samples[index].tag.capitalize())

这段代码在mypy中会触发错误：Item "None" of "str | None" has no attribute "capitalize" Mypyunion-attr。我发现直接遍历元素而非用索引时问题消失，但可能无法采用这种方式；临时变量赋值、断言、海象运算符等方案也无法使用，且海象运算符在复杂场景中会报错Operator ":=" is not allowed in this context without surrounding parentheses。

背后的原因 #

Mypy无法对通过索引重复访问的列表元素进行可靠的类型窄化，核心逻辑如下：

• 当你第一次通过container.samples[index].tag检查is not None时，mypy只能确认这一瞬间该元素的tag是非None的。但由于列表是可变容器，mypy无法保证第二次访问container.samples[index].tag时，这个元素没有被其他代码修改（哪怕你的代码里没做修改，mypy的类型检查逻辑默认不会假设列表元素是不可变的）。因此它不能确定第二次访问的tag仍然是非None的。
• 而直接遍历元素时，你是把元素赋值给了一个临时变量（比如for sample in container.samples），mypy可以跟踪这个临时变量的类型——一旦你检查了sample.tag is not None，它就知道后续这个变量的tag是str类型，不会再报错。
• 你提到的其他方案受限的情况，本质上都是因为只有当类型信息绑定到一个固定的变量时，mypy才能准确做类型窄化；而索引访问属于动态访问，mypy无法确保两次访问的是同一个不可变状态的元素。

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