Python 3.10+中如何为可选属性正确添加类型提示？

问题背景 #

定义包含color和可选owner属性的Car类，新车初始无车主，owner设为可选属性。调用sell_to方法卖出车辆后，访问new_car.owner.name时，VSCode的Pylance会报错"name is not a known attribute of None"，但代码运行正常；若将类型提示改为仅Person，则__init__中默认值None又会触发类型错误。

相关代码如下：

from dataclasses import dataclass
from enum import Enum

class Color(Enum):
    RED = 0
    BLUE = 1

@dataclass
class Person():
    name: str
    license_id: int

class Car():
    def __init__(self, color: Color, owner: Person|None = None) -> None:
        self.color: Color = color
        self.owner: Person|None = owner

    def sell_to(self, buyer: Person) -> None:
        self.owner = buyer

调用代码：

if __name__ == "__main__":
    new_car = Car(Color.RED)
    john_doe = Person("John Doe", 123)
    new_car.sell_to(john_doe)
    print(f"Car sold to {new_car.owner.name}")

解决方案 #

方案1：使用断言明确状态 #

在访问owner属性前添加断言，告诉静态类型检查器此时owner不为None：

if __name__ == "__main__":
    new_car = Car(Color.RED)
    john_doe = Person("John Doe", 123)
    new_car.sell_to(john_doe)
    # 断言owner非空，消除类型检查错误
    assert new_car.owner is not None
    print(f"Car sold to {new_car.owner.name}")

方案2：用属性封装确保类型一致性 #

通过私有变量存储owner，对外暴露只读属性，在属性中保证卖出后返回非None的Person类型：

class Car():
    def __init__(self, color: Color, owner: Person|None = None) -> None:
        self.color: Color = color
        # 私有变量存储可选状态的owner
        self._owner: Person|None = owner

    def sell_to(self, buyer: Person) -> None:
        self._owner = buyer

    @property
    def owner(self) -> Person:
        # 未卖出时访问会触发断言错误，提前发现逻辑问题
        assert self._owner is not None, "车辆尚未售出，无车主信息"
        return self._owner

此时调用代码无需额外检查，类型检查器会识别owner属性返回的是Person类型：

if __name__ == "__main__":
    new_car = Car(Color.RED)
    john_doe = Person("John Doe", 123)
    new_car.sell_to(john_doe)
    print(f"Car sold to {new_car.owner.name}")

方案3：使用类型转换（cast） #

通过typing.cast强制指定类型，适用于确定状态但不想添加断言的场景：

from typing import cast

if __name__ == "__main__":
    new_car = Car(Color.RED)
    john_doe = Person("John Doe", 123)
    new_car.sell_to(john_doe)
    # 强制转换类型，消除检查错误
    print(f"Car sold to {cast(Person, new_car.owner).name}")

原理说明 #

Pylance作为静态类型检查工具，无法追踪代码运行时的状态变化——它不知道调用sell_to后owner已从None变为Person实例。上述方案通过明确告知类型检查器当前状态或封装属性保证类型一致性，解决了静态检查和运行逻辑的矛盾。

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