Pyright 类型检查器对 SQLAlchemy Mapped 类型窄化的行为变更解析

在 Pyright 1.1.387 版本中，针对 SQLAlchemy 的 Mapped 类型描述符的类型窄化行为进行了重要修正。这一变更影响了开发者在使用 SQLAlchemy ORM 时的类型检查体验，值得深入理解其技术背景和影响。

问题现象

开发者在使用 SQLAlchemy 的 MappedAsDataclass 时发现，当尝试访问可能为 None 的 Mapped 类型属性时，Pyright 1.1.387 会发出类型警告，而之前的 1.1.386 版本则不会。这种差异源于 Pyright 对"非对称描述符"（asymmetric descriptor）检测逻辑的改进。

技术背景

在 Python 类型系统中，描述符协议允许类属性具有自定义的获取和设置行为。当描述符的 __get__ 和 __set__ 方法接受和返回的类型不一致时，我们称之为"非对称描述符"。

SQLAlchemy 的 Mapped 类型正是一个典型的非对称描述符：

• __get__ 返回 _T_co 类型
• __set__ 接受 SQLCoreOperations[_T_co] | _T_co 类型

这种非对称性意味着设置操作可能会对输入值进行某种转换，因此类型检查器不能简单地假设通过 __get__ 获取的值会与设置的值保持相同类型。

Pyright 的行为变更

在 1.1.387 版本中，Pyright 修复了一个关于非对称描述符检测的 bug。此前版本未能正确识别使用重载 __get__ 方法的非对称描述符，导致对 Mapped 类型的类型窄化处理不够严格。

修正后，Pyright 能够正确识别 Mapped 的非对称性，并因此：

1. 禁止在赋值时进行类型窄化
2. 对可能为 None 的 Mapped 属性访问提供更严格的类型检查

对开发者的影响

这一变更意味着开发者需要更明确地处理可能为 None 的 Mapped 属性。在代码中，应当先进行显式的 None 检查，然后再访问属性：

if sqla_order.shipment is not None:
    # 现在可以安全访问 deliveries
    deliveries = sqla_order.shipment.deliveries

解决方案建议

对于长期解决方案，可以考虑以下方向：

1. 与 SQLAlchemy 社区讨论 Mapped 类型的对称性问题，如果可能，调整类型注解使其成为对称描述符
2. 在代码中增加显式的类型保护（type guard）逻辑
3. 使用类型断言（type assertion）在明确安全的上下文中覆盖类型检查

总结

Pyright 的这一行为变更是类型系统精确性的重要改进，虽然可能暂时影响现有代码，但有助于捕获更多潜在的类型错误。理解描述符的非对称性及其对类型窄化的影响，有助于开发者编写更健壮的 Python 代码。

对于使用 SQLAlchemy ORM 的开发者，建议审查代码中对 Mapped 类型属性的访问模式，确保正确处理可能的 None 值情况，以保持代码的类型安全性。