Pylance 版本更新中类构造器签名提示的变化分析

问题背景

在 Pylance 语言服务器从 v2024.7.1 升级到 v2024.8.1 版本后，用户发现类构造器的签名提示信息发生了变化，导致代码补全功能受到影响。具体表现为构造器参数提示不再显示，且显示的签名信息对用户帮助不大。

技术分析

这一变化源于 Pyright 类型检查器对 Python 类型规范中构造器章节的更新实现。Pyright 现在更严格地遵循了 Python 类型规范中关于构造器行为的最新定义。

核心问题出现在类继承体系中的 __new__ 方法返回类型注解上。在受影响的库中，Model.__new__ 方法的返回类型被错误地注解为 "Model"，而根据 Python 类型规范，它应该使用 typing.Self 类型注解，因为 __new__ 方法需要支持子类继承。

根本原因

当 Pyright 检查构造器时，它会验证 __new__ 方法返回的类型是否是当前类的子类。如果返回类型被错误地注解为基类而非 Self 类型，类型检查器会认为构造器返回的类型与当前类不兼容，从而导致跳过对 __init__ 方法的签名分析。

解决方案

对于库开发者而言，修复方案是将 __new__ 方法的返回类型从具体的类名改为 typing.Self。例如：

def __new__(cls, *args: Any, **kwargs: Any) -> "Model":  # 错误的注解

应改为：

def __new__(cls, *args: Any, **kwargs: Any) -> Self:  # 正确的注解

影响范围

这一问题不仅影响了直接使用 Pylance 的用户体验，还暴露了上游库中类型注解的问题。在案例中，问题最终追溯到 autorest.python 代码生成工具中的类型注解生成逻辑，该工具被用于生成受影响库的代码。

最佳实践建议

1. 对于库开发者：

   • 在实现可继承类时，确保 __new__ 方法使用 typing.Self 作为返回类型
   • 定期更新类型检查工具以捕获潜在的注解问题

2. 对于终端用户：

   • 遇到类似问题时，可考虑检查依赖库的类型注解是否正确
   • 更新到库的最新版本可能解决此类问题

总结

这一案例展示了静态类型检查在 Python 生态系统中的重要性，以及类型注解准确性对开发工具链的影响。随着 Python 类型系统的不断演进，开发者和工具链都需要适应这些变化，以确保最佳的开发体验。