Pylance严格模式下Protocol声明的int属性与property不兼容如何解决

问题原因 #

Python静态类型系统遵循PEP544协议规范，默认会严格区分常规实例属性和property描述符的类型：

1. 当你在Protocol中定义value: int时，类型检查器默认要求实现类的value必须是类型为int的实例属性，而property本身是描述符对象，和int类型不匹配，因此触发重写错误。
2. 当你把Protocol中的value改为仅定义getter的@property时，该协议约束value为只读属性，而实现类的value: int是可读写属性，严格模式下会被判定为违反只读约束，因此报错。
   TypeScript的结构类型系统对属性访问做了语法层的兼容处理，会自动把getter/setter和同名普通属性判定为结构兼容，和Python的检查规则不同。

修复方案 #

方案1（推荐）：补全Protocol的property读写定义 #

在Protocol中同时定义value的getter和setter，即可同时兼容普通属性和带get/set的property两种实现方式：

from typing_extensions import Protocol

class IFoo(Protocol):
    @property
    def value(self) -> int: ...
    @value.setter
    def value(self, val: int) -> None: ...

此时两种实现都能通过类型检查：

• 带property的实现：同时满足读返回int、写接受int的约束
• 普通属性实现：value: int本身就是可读写的int属性，完全匹配协议要求

如果你的业务场景中value是只读的，只需要保留Protocol中的getter定义，同时把实现类的普通属性声明为只读即可：

from typing import Final

class Foo(IFoo):
    value: Final[int] = 2

方案2：调整类型检查规则（适配原有Protocol定义） #

如果你不想修改原有Protocol的value: int定义，可以通过两种方式消错：

1. 局部忽略报错：在实现类的property定义行加注释# type: ignore[override]
2. 全局关闭检查：在Pylance配置中把reportIncompatibleVariableOverride设置为false，该方案会降低类型检查严格度，仅推荐在老项目兼容场景使用。

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