Pylance不允许内置类型使用结构子类型，如何解决？

问题背景 #

我在学习Python Protocol相关内容时，参照PEP 544的子类型关系章节编写了示例代码，但遇到Pylance类型检查报错。代码如下：

from typing import Protocol, TypeVar

T = TypeVar("T", contravariant=True)
class ListLike(Protocol[T]):
    def append(self, x: T) -> None:
        ...

class MockStack:
    def append(self, x: int) -> None:
        ...

def populate(lst: ListLike[int]) -> int:
    ...

populate([1, 2, 3])
populate(MockStack())

预期list[int]和MockStack都能匹配ListLike[int]协议，但Pylance报错：

Argument of type "list[int]" cannot be assigned to parameter "lst" of type "ListLike[int]" in function "populate"
  "list[int]" is incompatible with protocol "ListLike[int]"
    "append" is an incompatible type
      Type "(__object: int, /) -> None" cannot be assigned to type "(x: T@ListLike) -> None"
        Position-only parameter mismatch; expected 1 but received 0  (reportGeneralTypeIssues)

解决方案 #

1. 调整Protocol的append方法为位置-only参数 #

Python标准库中list.append的参数是位置-only的（通过/标记），而你定义的ListLike协议里的append参数是普通参数，这导致类型检查器认为两者签名不兼容。修改协议中的方法签名，匹配list.append的定义：

from typing import Protocol, TypeVar

T = TypeVar("T", contravariant=True)
class ListLike(Protocol[T]):
    # 使用/标记位置-only参数
    def append(self, __x: T, /) -> None:
        ...

class MockStack:
    def append(self, x: int) -> None:
        ...

def populate(lst: ListLike[int]) -> int:
    ...

populate([1, 2, 3])  # 现在通过类型检查
populate(MockStack())  # 正常通过

2. 理解位置-only参数的类型匹配规则 #

Pylance等严格类型检查器会严格校验函数参数的签名细节，包括是否为位置-only。当协议方法的参数是位置-only类型时，可以兼容普通参数的实现（因为普通参数的实现能接受位置传参）；但反过来，普通参数的协议无法兼容位置-only参数的实现，这就是报错的核心原因。

3. 协变/逆变的正确性说明 #

你的代码中T标记为逆变是正确的——append方法的参数属于输入型参数，符合逆变的适用场景，这部分无需修改。

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