为何Pylance对带列表参数的类型提示函数报错，元组参数函数却正常？

问题现象 #

在VSCode中使用Pylance v2023.9.20并开启严格类型检查时，以下代码中第一个函数调用触发类型错误，第二个却正常通过，二者仅差异在于前者参数被列表包裹：

def listTupleFunc(arg: list[tuple[str, tuple[str, ...]]]) -> None:
    pass
listTuple = [('x', ('a', 'b'))]
listTupleFunc(listTuple) # 此处报错

def tupleOnlyFunc(arg: tuple[str, tuple[str, ...]]) -> None:
    pass
tupleOnly = ('x', ('a', 'b'))
tupleOnlyFunc(tupleOnly) # 正常通过

报错详情 #

报错信息如下：

Argument of type "list[tuple[Literal['x'], tuple[Literal['a'], Literal['b']]]]" cannot be assigned to parameter "arg" of type "list[tuple[str, tuple[str, ...]]]" in function "listTupleFunc"
  "list[tuple[Literal['x'], tuple[Literal['a'], Literal['b']]]]" is incompatible with "list[tuple[str, tuple[str, ...]]]"
    Type parameter "_T@list" is invariant, but "tuple[Literal['x'], tuple[Literal['a'], Literal['b']]]" is not the same as "tuple[str, tuple[str, ...]]"

特殊情况 #

当修改部分字面量为f-string格式时，部分场景报错消失：

# 以下两种情况正常通过检查
listTuple = [(f'x', ('a', f'b'))]  
listTuple = [(f'x', (f'a', 'b'))]  
# 以下两种情况仍报错
listTuple = [('x', (f'a', f'b'))]
listTuple = [(f'x', ('a', 'b'))]

原因分析 #

这不是Pylance的Bug，而是Python类型系统中**不变类型（Invariant）与协变类型（Covariant）**的差异导致的：

1. list是不变类型：对于list[T]，只有当T完全匹配时才能赋值，子类型无法替代。这里Pylance推断listTuple的类型是list[tuple[Literal['x'], tuple[Literal['a'], Literal['b']]]]，与函数要求的list[tuple[str, tuple[str, ...]]]中元素类型不严格一致，因此报错。
2. tuple是协变类型：对于tuple[T, ...]，如果T是目标类型的子类型，则可以赋值。Literal['x']是str的子类型，因此tuple[Literal['x'], ...]可以兼容tuple[str, ...]，第二个函数调用正常。
3. f-string的影响：f-string表达式返回的类型是str而非字面量类型（Literal），当使用f'x'时，对应的元素类型被推断为str，此时tuple的类型变为tuple[str, tuple[str, ...]]，对应的list类型也匹配函数参数要求，因此不报错。

解决方法 #

可以通过以下几种方式消除报错：

• 显式标注变量类型：直接给listTuple指定目标类型，覆盖Pylance的字面量推断：

  listTuple: list[tuple[str, tuple[str, ...]]] = [('x', ('a', 'b'))]
  

• 使用typing.cast强制类型转换：在函数调用时显式转换类型（适合临时场景）：

  from typing import cast
  listTupleFunc(cast(list[tuple[str, tuple[str, ...]]], listTuple))
  

• 调整Pylance类型推断设置：在VSCode设置中降低字面量推断的严格性，例如将python.analysis.inferLiteralTypes设为false，但这会影响全局类型推断的精度。

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