Pyright中list[int]传入要求list[str|int]的函数报错的解决方法

代码场景 #

def myfun(X: list[str|int]):
    for x in X:
        print(x)


X = [1,2,3]
myfun(X)

Pyright报错的核心原因是Python的list类型是不变的——list[int]并不被视为list[str|int]的子类型，即便int是str|int的子类型。

1. 最优处理方式 #

把函数参数的类型注解从list[str|int]改为协变的抽象类型，比如Iterable[str|int]或Sequence[str|int]：

from typing import Iterable

def myfun(X: Iterable[str|int]):
    for x in X:
        print(x)

X = [1,2,3]
myfun(X)  # Pyright不再报错

这样做的好处：

• Iterable是协变类型，Iterable[int]会被自动视为Iterable[str|int]的子类型，既保留X的list[int]类型，又让函数正常接受该参数。
• 函数适用范围更广，除了列表，还能接受元组、生成器等其他可迭代对象，符合Python的鸭子类型设计。

如果函数需要列表特有的方法（比如append），可以改用Sequence[str|int]，它同样是协变类型，且包含序列类型的通用操作。

2. 让Pyright接受"子类型"的其他方法 #

除了上述最优方案，还有几种可选方式：

• 使用协变泛型类型变量：
  若要保留list的具体类型注解，可通过TypeVar声明协变类型：

  from typing import TypeVar
  
  T = TypeVar("T", str, int, covariant=True)
  
  def myfun(X: list[T]):
      for x in X:
          print(x)
  
  X = [1,2,3]
  myfun(X)  # Pyright正常识别
  

  这种方式明确告知类型检查器，函数接受list[int]或list[str]类型的参数，适配子类型兼容逻辑。

• 临时类型断言（不推荐）：
  用typing.cast跳过类型检查，但会失去静态类型检查的意义，仅适合临时调试：

  from typing import cast
  
  X = [1,2,3]
  myfun(cast(list[str|int], X))
  

• 调整Pyright配置（不推荐）：
  在pyrightconfig.json中设置strictParameterTypes=false，全局降低参数类型检查的严格程度，但可能掩盖其他真实的类型错误。

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