Pyright是否错误泛化类型？线性代数维度检查异常

问题场景 #

我实现了一套用于线性代数维度静态检查的类型编码，加法操作在mypy和pyright中表现一致，但矩阵乘法时出现差异：

• mypy能正确保留Literal类型的具体维度，例如A @ B会被推断为Array[Shape2D[Literal[3],Literal[5]]]
• pyright会将Literal类型泛化为int，得到Array[Shape2D[int,int]]
• 使用N、M、K这类抽象泛型类型作为维度时，两个检查器都能正确推断维度。

原因分析 #

这不是对Literal类型的理解错误，而是pyright与mypy在泛型上下文的类型推断策略上存在差异：

• Mypy在处理泛型运算符（如__matmul__）时，会主动追踪并保留Literal类型的窄化信息，确保具体维度值不丢失。
• Pyright默认在这类泛型方法的类型推断中，会将Literal向上提升为其基础类型（如int），除非显式配置或调整类型签名以强制保留窄化信息。

修复方案 #

1. 启用Pyright严格参数类型检查 #

在项目根目录的pyrightconfig.json中添加以下配置，让Pyright更严格地保留泛型参数的窄化类型：

{
  "strictParameterTypes": true
}

这个选项会强制Pyright在泛型传递过程中保留Literal等窄化类型的具体信息，而不是自动泛化为基础类型。

2. 调整TypeVar的约束定义 #

确保用于维度的TypeVar显式绑定到支持窄化的类型，同时在__matmul__方法中明确泛型参数的传递关系：

from typing import Generic, Literal, TypeVar

# 定义维度专用的TypeVar，绑定int并支持窄化
Row = TypeVar("Row", bound=int)
Col = TypeVar("Col", bound=int)
OtherCol = TypeVar("OtherCol", bound=int)

class Shape2D(Generic[Row, Col]):
    pass

class Array(Generic[Row, Col]):
    # 明确标注输入输出的泛型参数关联
    def __matmul__(self, other: Array[Col, OtherCol]) -> Array[Row, OtherCol]:
        ...

这种明确的泛型绑定有助于Pyright识别并保留Literal类型的维度信息。

3. 升级到最新版本的Pyright #

Pyright的类型推断逻辑一直在迭代优化，部分旧版本存在对__matmul__等特殊方法中Literal类型追踪不完善的问题。升级到最新版后，可能无需额外配置即可修复该问题。

补充说明 #

使用抽象泛型参数（如N、M、K）时两个检查器表现一致，是因为这类参数本身就是未绑定的泛型占位符，不存在“窄化类型泛化”的情况。而Literal是具体的窄化类型，触发了Pyright默认的类型提升策略。

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